Prerrequisitos
Antes de crear una conexión, necesitará lo siguiente de Meta:| Requisito | Dónde Obtenerlo |
|---|---|
| Cuenta de WhatsApp Business (verificada) | Meta Business Manager |
| Token de Acceso de Usuario del Sistema | Meta Business Manager → Usuarios del Sistema |
| ID de Número de Teléfono | WhatsApp Manager → Números de Teléfono |
| ID de Cuenta Comercial | Opcional — requerido para llamadas avanzadas a Graph API |
| Plantillas de mensajes aprobadas | Meta Business Manager → Herramientas de Cuenta → Plantillas de Mensajes |
Crear una Conexión
El Toolkit de WhatsApp está disponible tanto en el Agent Builder como en el Workflow Builder. La configuración de la conexión es la misma en ambos, pero la ruta de navegación difiere.- Toolkit de Agente
- Toolkit de Flujo de Trabajo
- Abra su agente en el Agent Builder
- Vaya a la pestaña Toolkits en la barra lateral izquierda
- Encuentre WhatsApp y haga clic en Agregar al Agente
- En el panel del Toolkit, haga clic en Seleccionar una Conexión > Crear una Conexión
- En la ventana emergente que aparece, ingrese un Nombre de Conexión, su Token de Acceso de Usuario del Sistema, ID de Cuenta Comercial.
- Ingrese su Token de Acceso, ID de Cuenta Comercial (opcional) y un Nombre para la conexión
- Haga clic en Guardar — EKB validará las credenciales antes de guardar
Herramientas Disponibles
| Herramienta | Descripción |
|---|---|
| Enviar Mensaje | Envíe un mensaje de texto plano (hasta 4,096 caracteres, UTF-8) dentro de la ventana de sesión de 24 horas |
| Enviar Medios | Envíe una imagen, video, audio o documento a través de una URL HTTPS pública, con pie de foto o nombre de archivo opcional |
| Enviar Plantilla | Envíe un mensaje de plantilla pre-aprobado — requerido para mensajes salientes fuera de la ventana de sesión de 24 horas |
| Llamada API Personalizada | Realice una llamada directa a cualquier endpoint de Meta Graph API para casos de uso avanzados (vea más abajo) |
Llamada API Personalizada
La herramienta de Llamada API Personalizada es la opción más extensible. Permite acceso directo a endpoints de WhatsApp Graph API más allá de lo que cubren las otras herramientas, incluyendo:- Mensajes interactivos (botones, listas)
- Tarjetas de ubicación y contacto
- Mensajes de catálogo de productos
- Gestión programática de plantillas
- Actualizaciones de perfil comercial
- Analítica e información de mensajería
Notas de Configuración
- Formato de número de teléfono: Siempre use el formato internacional E.164 (por ejemplo,
+1...,+52...). Los espacios, guiones o un código de país faltante causarán fallos de entrega (error1006). - Ventana de sesión: Los mensajes de texto plano y medios solo pueden enviarse dentro de una ventana de 24 horas desde el último mensaje del destinatario. Fuera de esa ventana, use Enviar Plantilla en su lugar.
- URLs de medios: Deben ser accesibles públicamente a través de HTTPS. Las URLs privadas, de localhost o expiradas causarán fallos de descarga (error
1011). Verifique que los tipos MIME coincidan con el contenido del archivo. - Plantillas: Deben estar aprobadas en Meta Business Manager antes de usarse. El recuento y orden de parámetros debe coincidir exactamente con la plantilla aprobada. Monitoree la calificación de calidad de su plantilla — una calificación baja puede resultar en la pausa de una plantilla (error
131056). - Límites de velocidad: WhatsApp Business API impone límites de mensajería por número y por día. Para envíos masivos, use colas e implemente lógica de reintentos con retroceso exponencial.
- Seguridad: Almacene tokens de acceso de forma segura y rote las credenciales periódicamente. Asegúrese de obtener el consentimiento del usuario antes de enviar mensajes de marketing.
Ejemplos Prácticos
- Soporte al Cliente: Un agente recibe una solicitud de soporte, busca el registro del cliente y envía un mensaje de WhatsApp con el número de ticket y los próximos pasos — o usa una plantilla de botón interactivo para enrutar al usuario al equipo correcto.
- Notificaciones Transaccionales: Un flujo de trabajo se activa después de que se realiza un pedido y envía una plantilla con confirmación del pedido, actualizaciones de envío o notificaciones de pago.
- Entrega de Documentos: Un agente genera una factura PDF o contrato y lo entrega a través de la herramienta Enviar Medios con un pie de foto descriptivo.
- Campañas de Difusión: Un flujo de trabajo itera sobre una lista de contactos y envía una plantilla de marketing aprobada con sustitución de parámetros personalizados.
Solución de Problemas
| Código de Error | Síntoma | Solución |
|---|---|---|
401 / 190 | Token de acceso inválido | Regenere el token de Usuario del Sistema en Meta Business Manager y actualice la conexión |
33 | ID de Número de Teléfono inválido | Verifique el ID de Número de Teléfono en WhatsApp Manager |
1006 | Formato de número de teléfono inválido | Use formato E.164 — incluya + y código de país, sin espacios ni guiones |
131005 | Plantilla no encontrada | Confirme el nombre de la plantilla y que existe en Meta Business Manager |
131056 | Plantilla pausada | Verifique la calificación de calidad de la plantilla en Meta Business Manager |
1011 | Fallo de descarga de medios | Use una URL HTTPS pública y confirme que el tipo de archivo y tipo MIME son soportados |
- Verifique las credenciales y que la conexión sea válida
- Confirme que el número de teléfono del destinatario esté registrado en WhatsApp
- Valide el formato del mensaje y la estructura del payload
- Confirme el estado de aprobación de la plantilla
- Verifique si se alcanzaron los límites de velocidad de la API