Servicio de mensajería
WhatsApp · SMS · Email · v1.1
Usa PushLeads como tu proveedor de mensajería: envía por tu propia línea oficial de WhatsApp sin comisión por mensaje, gestiona plantillas y recibe en tu servidor cada mensaje entrante y cada recibo de entrega. Pensado para chatbots y sistemas externos que no usan los agentes de IA de PushLeads.
Qué es y cuánto cuesta
Tres canales, dos formas de conectar WhatsApp y un solo contrato de API
El servicio de mensajería expone por API lo mismo que PushLeads usa internamente para su inbox y sus campañas. Tú decides quién responde: puedes dejar que un agente de IA de PushLeads atienda la línea, o dejarla sin agente y conectar tu propio chatbot por webhooks. En ambos casos las conversaciones quedan en el inbox del workspace, con historial y contactos.
| Canal | Proveedor | Quién cobra el mensaje | Qué necesitas |
|---|---|---|---|
| Meta Cloud API (línea oficial del cliente) | Meta, directo a tu cuenta de WhatsApp Business. PushLeads no agrega comisión por mensaje. La tarifa depende de la categoría de la plantilla y del país del destinatario. | Conectar tu WABA en Canales → WhatsApp Cloud API (registro integrado de Meta). Si la línea es de PushLeads, el consumo se descuenta de tu saldo de WhatsApp. | |
| Twilio (número propio en tu cuenta de Twilio) | Twilio, según su tarifa por mensaje y la de Meta. | Credenciales de Twilio y un sender verificado en el workspace. | |
| SMS | Hablamé (Colombia) por PushLeads | Se descuenta de los SMS incluidos en tu plan o de paquetes de créditos. | Plan con SMS o un paquete de créditos. Remitente opcional. |
| Infraestructura de PushLeads (SendGrid) | Se descuenta de los correos incluidos en tu plan o de paquetes de créditos. | Un dominio o remitente verificado en el workspace. |
Guía rápida
De cero a tu primer mensaje de WhatsApp en seis pasos
- 1
Conecta la línea
En Canales → WhatsApp Cloud API inicia el registro integrado de Meta con tu cuenta de WhatsApp Business. Si ya tienes el número en otra plataforma, puedes migrarlo; si el número está activo en la app de WhatsApp Business, la coexistencia lo mantiene funcionando.
- 2
Deja la línea sin agente de IA
Si tu chatbot externo va a responder, no asignes ningún agente de PushLeads a la línea. Así PushLeads guarda la conversación en el inbox pero nadie contesta desde la plataforma y no hay respuestas dobles. Los eventos llegan con
humanControlled: true. - 3
Crea una API key
En Configuración → API keys crea una clave con los permisos
whatsapp:send,messages:read,messaging:read,templates:read,templates:writeywebhooks:manage. La clave queda atada a un workspace y hereda el rol del usuario que la crea. - 4
Registra tu webhook
En la pestaña Webhooks del mismo panel o con
POST /api/v1/webhooks, registra la URL HTTPS de tu servidor y suscríbete amessage.receivedymessage.status. Guarda el secreto: solo se muestra una vez. - 5
Consulta tus recursos
GET /api/v1/messaging/resourcesdevuelve elmetaPhoneNumberIdde cada línea y las plantillas aprobadas con sus variables. Son los identificadores que usarás al enviar. - 6
Envía
POST /api/v1/whatsapp/sendcontype: "text"para responder dentro de la ventana de 24 horas, otype: "template"con una plantilla aprobada para iniciar la conversación.
Autenticación y permisos
API keys por workspace con permisos granulares
Toda petición lleva la API key en el header Authorization: Bearer pk_live_... (o X-API-Key). Cada clave pertenece a un solo workspace y no puede ampliar los permisos del usuario que la creó: si ese usuario pierde el rol o el acceso al workspace, la clave deja de funcionar.
Permisos del servicio de mensajería
| Permiso de la API key | Habilita | Exige en el rol del workspace |
|---|---|---|
whatsapp:send | POST /whatsapp/send | Responder conversaciones |
sms:send | POST /sms/send | Responder conversaciones |
email:send | POST /email/send | Responder conversaciones |
messages:read | GET /messages/:id | Ver conversaciones |
messaging:read | GET /messaging/resources | Ver conversaciones o ver campañas |
templates:read | GET /whatsapp/templates y /:id | Ver plantillas o ver campañas |
templates:write | POST /whatsapp/templates, /:id/submit, /sync y DELETE /:id | Crear, editar y eliminar plantillas |
webhooks:manage | Todo /webhooks | Configuración del workspace |
* | Todos los permisos | Solo el dueño de la cuenta puede emitirla |
/api/v1/meSin permiso específicoDevuelve el workspace y los permisos de la clave. Úsalo al arrancar tu integración para fallar temprano si falta un permiso.
curl "https://app.pushleads.co/api/v1/me" \
-H "Authorization: Bearer pk_live_tu_api_key"
{
"success": true,
"data": {
"accountId": "user_owner",
"userId": "user_member",
"workspaceId": "ws_abc",
"permissions": ["whatsapp:send", "messages:read", "messaging:read", "templates:write", "webhooks:manage"],
"workspacePermissions": ["conversations.respond", "conversations.view", "templates.create", "..."]
}
}Convenciones
Formato, idempotencia y límites comunes a todos los endpoints
URL base y formato
- Base:
https://app.pushleads.co/api/v1. Siempre HTTPS, cuerpos en JSON conContent-Type: application/json, máximo 256 KB. - Respuestas correctas:
{ "success": true, "data": ... }. Los envíos devuelven202 Accepted; las creaciones201 Created. - Errores:
{ "success": false, "error": { "code", "message", "details" } }. Elcodees estable y sirve para programar; elmessagepuede cambiar. - Teléfonos siempre en formato E.164 con indicativo de país:
+573001234567. - El workspace lo define la API key. Si envías
workspaceIdoaccountIden el cuerpo, la query o los headers y no coinciden, la petición falla conCONTEXT_MISMATCH.
{
"success": false,
"error": {
"code": "whatsapp_window_closed",
"message": "No verified incoming message within 24 hours on this sender. Use an approved template.",
"details": null
}
}Idempotency-Key (obligatorio en todo POST que crea o envía)
- Entre 8 y 128 caracteres: letras, números, punto, guion, dos puntos o guion bajo. Usa un identificador tuyo, por ejemplo
reply-<messageId>uotp-<userId>-<intento>. - Repetir la misma clave con el mismo cuerpo devuelve la respuesta original con el header
Idempotency-Replayed: truey no vuelve a enviar. - La misma clave con otro cuerpo responde
409 IDEMPOTENCY_CONFLICT. Si la petición original sigue en curso,409 REQUEST_IN_PROGRESS: espera y repite con la misma clave, nunca con una nueva. - Cuando el proveedor no confirma ni rechaza (
502 provider_outcome_unknown) el resultado también queda guardado bajo la clave para que un reintento ciego no duplique un cobro.
Límites
- Los envíos descuentan de la asignación del plan (SMS, email) o del saldo de WhatsApp cuando la línea es de PushLeads. Al agotarse responden
403 plan_limit_reachedo402 whatsapp_balance_insufficient. - Hasta 10 webhooks activos por workspace; cada entrega espera máximo 10 segundos tu respuesta.
- Las peticiones por hora dependen del plan (ver la sección Rate Limits de la API general). Usa webhooks en lugar de consultar estados en bucle.
Líneas y recursos
Descubre qué líneas y plantillas puede usar la API key
/api/v1/messaging/resourcesRequiere: messaging:readDevuelve, para el workspace de la clave, el remitente de SMS, las líneas de WhatsApp (Meta con metaPhoneNumberId, Twilio con senderPhone y opcionalmente messagingServiceSid) y las plantillas aprobadas con sus variables. Solo aparecen líneas activas y cuentas de WhatsApp Business en estado activo.
curl "https://app.pushleads.co/api/v1/messaging/resources" \
-H "Authorization: Bearer pk_live_tu_api_key"
{
"success": true,
"data": {
"workspaceId": "ws_abc",
"sms": { "configured": true, "senderPhone": "+573101234567", "senderPhones": ["+573101234567"] },
"whatsapp": {
"senders": [
{ "provider": "meta", "senderPhone": "+573101234567", "name": "Tienda Centro",
"metaPhoneNumberId": "1098765432100", "wabaAccountId": "waba_..." },
{ "provider": "twilio", "senderPhone": "+14155238886", "name": "Twilio Sandbox",
"messagingServiceSid": "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
],
"templates": [
{ "provider": "meta", "metaTemplateId": "1234567890", "name": "confirmacion_pedido",
"language": "es", "category": "UTILITY",
"body": "Hola {{1}}, tu pedido {{2}} fue confirmado.", "variables": ["1", "2"],
"components": [ "..." ], "wabaAccountId": "waba_..." },
{ "provider": "twilio", "contentSid": "HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "name": "recordatorio_cita",
"language": "es", "category": "utility",
"body": "Hola {{1}}, te recordamos tu cita el {{2}}.", "variables": ["1", "2"] }
]
}
}
}Las plantillas de Meta incluyen components tal como los devuelve Meta: ahí verás si el encabezado es multimedia (necesitarás headerMediaUrl al enviar) o si hay un botón de cupón (necesitarás couponCode).
Mensajes individuales de texto o plantilla por Meta Cloud API o Twilio
Ventana de 24 horas
WhatsApp solo permite texto libre dentro de las 24 horas siguientes al último mensaje del cliente a esa misma línea. PushLeads lo verifica con los mensajes recibidos y, si la ventana está cerrada, responde 409 whatsapp_window_closed. Fuera de la ventana envía una plantilla aprobada.
/api/v1/whatsapp/sendRequiere: whatsapp:send · Idempotency-KeyBody (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
to | string | * | Destinatario en E.164. Debe ser distinto de la línea remitente. |
provider | "meta" | "twilio" | * | Por qué proveedor sale el mensaje. Determina qué otros campos se aceptan. |
type | "text" | "template" | * | Texto libre (solo dentro de la ventana de 24 h) o plantilla aprobada. |
text | string ≤ 4096 | si type=text | Contenido del mensaje. No se admite junto con campos de plantilla. |
metaPhoneNumberId | string | Meta | Identificador de la línea (de /messaging/resources). |
metaTemplateId | string | Meta + template | Identificador de la plantilla aprobada (metaTemplateId). |
senderPhone | string E.164 | Twilio | Número de Twilio verificado en el workspace. Obligatorio para texto libre (verifica la ventana) y si no envías messagingServiceSid. |
messagingServiceSid | string MG… | Twilio (alternativo) | Messaging Service asignado al workspace; solo para plantillas. |
contentSid | string HX… | Twilio + template | SID de la plantilla aprobada en Twilio Content. |
variables | objeto { "1": "..." } | opcional | Valores de las variables de la plantilla, con las claves exactas que devuelve resources. Faltantes o sobrantes → 400 invalid_variables con details.missing / details.extra. |
headerMediaUrl | string https | Meta, si la plantilla tiene encabezado multimedia | URL pública HTTPS de la imagen, video o documento del encabezado. |
couponCode | string ≤ 256 | Meta, si la plantilla tiene botón COPY_CODE | Código que verá el cliente en el botón de copiar. |
Texto por la línea oficial (Meta)
curl -X POST "https://app.pushleads.co/api/v1/whatsapp/send" \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reply-conv_123-0001" \
-d '{
"to": "+573001234567",
"provider": "meta",
"metaPhoneNumberId": "1098765432100",
"type": "text",
"text": "¡Hola Ana! Sí, hacemos envíos a Medellín. ¿Qué producto te interesa?"
}'Plantilla por Meta con documento y cupón
{
"to": "+573001234567",
"provider": "meta",
"metaPhoneNumberId": "1098765432100",
"type": "template",
"metaTemplateId": "1234567890",
"variables": { "1": "Ana", "2": "PED-123" },
"headerMediaUrl": "https://tu-cdn.com/facturas/PED-123.pdf",
"couponCode": "BIENVENIDA10"
}Por Twilio
# Plantilla aprobada en Twilio Content
{
"to": "+573001234567",
"provider": "twilio",
"senderPhone": "+14155238886",
"type": "template",
"contentSid": "HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"variables": { "1": "Ana", "2": "martes 3 p. m." }
}
# Texto libre dentro de la ventana de 24 h (exige senderPhone)
{
"to": "+573001234567",
"provider": "twilio",
"senderPhone": "+14155238886",
"type": "text",
"text": "Perfecto, te confirmo la cita."
}Respuesta
HTTP/1.1 202 Accepted
{
"success": true,
"data": {
"id": "api_msg_3f1c0d6e-....",
"workspaceId": "ws_abc",
"channel": "whatsapp",
"provider": "meta",
"to": "+573001234567",
"from": "+573101234567",
"status": "accepted",
"providerMessageId": "wamid.HBgM...",
"errorCode": null,
"errorMessage": null,
"deliveryTracking": "provider_callbacks",
"deliveredAt": null,
"readAt": null,
"createdAt": "2026-11-15T10:00:00.000Z",
"updatedAt": "2026-11-15T10:00:01.000Z"
}
}status: "accepted"significa que el proveedor recibió el mensaje. Los recibos sent, delivered, read y failed llegan después por el webhookmessage.statusy enGET /messages/:id.- Antes de enviar, PushLeads crea o actualiza el contacto y la conversación en el inbox, y bloquea el envío a contactos dados de baja (
409 recipient_unsubscribed) o con restricciones previas del proveedor (409 recipient_suppressed). - Las plantillas con texto dinámico en el encabezado o URL dinámica en botones no se admiten por este endpoint (
400 unsupported_template).
SMS
Códigos OTP, alertas y notificaciones transaccionales
/api/v1/sms/sendRequiere: sms:send · Idempotency-KeyBody (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
to | string E.164 | * | Destinatario. |
text | string ≤ 2000 | * | Texto del SMS. Se cobra por segmento (160 caracteres GSM o 70 si hay caracteres Unicode, como tildes y emojis). |
senderPhone | string E.164 | opcional | Remitente verificado del workspace. Si se omite, se usa el remitente compartido de PushLeads. |
priority | boolean (true) | opcional | Con true (por defecto) el SMS sale de inmediato, ideal para OTP. Con false respeta la franja horaria de marketing configurada y fuera de ella responde 409 send_window_closed. |
curl -X POST "https://app.pushleads.co/api/v1/sms/send" \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: otp-login-8841-1" \
-d '{
"to": "+573001234567",
"text": "Tu código de acceso es 482910. Vence en 5 minutos.",
"priority": true
}'La respuesta es la misma estructura de mensaje (channel: "sms", provider: "hablame") con estado accepted. Si el proveedor rechaza el número responde 502 provider_rejected con details.providerCode. El destinatario se guarda como contacto del workspace.
Correos unitarios o masivos con HTML propio, plantilla del workspace u OTP
/api/v1/email/sendRequiere: email:send o campaigns:write · Idempotency-KeyEnvía hasta 1000 destinatarios por llamada con html/text propios, una templateId del workspace con variables, o un otp con diseño listo. Acepta from, fromName y replyTo de remitentes verificados, y tags, source, listId y saveAsContact para organizar los destinatarios.
curl -X POST "https://app.pushleads.co/api/v1/email/send" \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: welcome-user-8841" \
-d '{
"to": { "email": "ana@ejemplo.com", "name": "Ana" },
"subject": "Bienvenida a la tienda",
"html": "<p>Hola Ana, gracias por registrarte.</p>",
"fromName": "Tienda Centro"
}'La referencia completa de campos, respuesta y eventos de correo está en la sección Email API de la documentación general.
Estado de un mensaje
Ciclo de vida de un envío y cómo seguirlo
| Estado | Significado | Siguiente |
|---|---|---|
processing | PushLeads registró la petición y está hablando con el proveedor. | accepted, failed o unknown |
accepted | El proveedor aceptó el mensaje (respuesta 202 del envío). | sent, delivered, read o failed |
sent | El proveedor lo entregó a la red de WhatsApp o del operador. | delivered, read o failed |
delivered | Llegó al dispositivo del destinatario. Se rellena deliveredAt. | read o failed |
read | El destinatario lo abrió (si tiene confirmaciones de lectura). Se rellena readAt. | estado final |
failed | Rechazado o no entregable. errorCode y errorMessage traen el motivo del proveedor. | estado final |
unknown | El proveedor no confirmó ni rechazó (timeout). Repite con la misma Idempotency-Key o revisa antes de reenviar. | puede resolverse con un recibo posterior |
Los estados avanzan solo hacia adelante: un recibo sent que llegue después de delivered se ignora, y failed siempre gana. Cada cambio dispara el webhook message.status, así que no necesitas consultar en bucle.
/api/v1/messages/:idRequiere: messages:readDevuelve el mensaje enviado por la API con su estado actual. Solo se ven mensajes del workspace de la clave; otro id responde 404 not_found.
curl "https://app.pushleads.co/api/v1/messages/api_msg_3f1c0d6e-...." \
-H "Authorization: Bearer pk_live_tu_api_key"
{
"success": true,
"data": {
"id": "api_msg_3f1c0d6e-....",
"status": "read",
"deliveredAt": "2026-11-15T10:00:04.000Z",
"readAt": "2026-11-15T10:02:40.000Z",
"errorCode": null,
"errorMessage": null,
"...": "..."
}
}Plantillas de WhatsApp
Crea, consulta, sincroniza y elimina plantillas sin entrar al panel
Las plantillas son obligatorias para iniciar conversaciones o escribir fuera de la ventana de 24 horas. Meta las revisa (minutos u horas) y las clasifica en marketing, utility o authentication, lo que define la tarifa por mensaje. La API trabaja igual con la línea oficial (Meta) y con Twilio Content; la respuesta siempre tiene la misma forma.
| Método | Ruta | Permiso | Descripción |
|---|---|---|---|
| GET | /api/v1/whatsapp/templates | templates:read | Lista todas. Filtros ?provider=meta|twilio y ?status=approved|pending|rejected|draft|unsubmitted. |
| POST | /api/v1/whatsapp/templates | templates:write · Idempotency-Key | Crea la plantilla. Meta: entra en revisión de inmediato. Twilio: guarda un borrador y lo envía a aprobación (submit: false para solo guardar). |
| GET | /api/v1/whatsapp/templates/:id | templates:read | Consulta al proveedor el estado de aprobación y actualiza la copia local. ?refresh=false lee solo la copia local. |
| POST | /api/v1/whatsapp/templates/:id/submit | templates:write | Twilio: envía un borrador o una plantilla rechazada a aprobación. |
| POST | /api/v1/whatsapp/templates/sync | templates:write | Importa a PushLeads las plantillas que ya existen en tu WABA o en tu cuenta de Twilio. |
| DELETE | /api/v1/whatsapp/templates/:id | templates:write | Elimina la plantilla. En Meta se borra también de la WABA (solo ese idioma). |
/api/v1/whatsapp/templatesRequiere: templates:write · Idempotency-KeyBody (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
provider | "meta" | "twilio" | * | Dónde se crea la plantilla. |
name | string ^[a-z0-9_]+$ | * | Nombre técnico, único por idioma dentro de la cuenta. Minúsculas, números y guion bajo. |
displayName | string ≤ 200 | opcional | Nombre amigable para el panel (Twilio lo usa como friendly name). |
language | string (es) | opcional | Código de idioma de Meta: es, es_MX, en_US, pt_BR… |
category | "marketing" | "utility" | "authentication" | opcional | Categoría de Meta. Marketing por defecto. Meta puede recategorizar al revisar. |
body | string ≤ 1024 | * | Cuerpo con variables consecutivas {{1}}, {{2}}… |
samples | string[] | Meta, si hay variables | Un ejemplo por variable, en orden. Meta lo exige para revisar. |
variables | { index, label?, sample? }[] | opcional | Alternativa a samples con etiqueta por variable (útil en Twilio y para el panel). |
headerText | string ≤ 60 | opcional | Encabezado de texto (sin variables). |
headerFormat | "TEXT" | "IMAGE" | "VIDEO" | "DOCUMENT" | opcional | Tipo de encabezado. Con IMAGE/VIDEO/DOCUMENT es obligatorio headerMediaUrl. |
headerMediaUrl | string https | opcional | Ejemplo del archivo del encabezado para la revisión de Meta. Al enviar podrás usar otro archivo. |
footerText | string ≤ 60 | opcional | Pie de la plantilla. |
buttons | TemplateButton[] ≤ 10 | opcional | Botones: QUICK_REPLY (title), URL (title, url), PHONE_NUMBER (title, phone), COPY_CODE (example), FLOW (title, flowId), CATALOG. |
metaPhoneNumberId | string | Meta (o wabaAccountId) | Línea cuya WABA recibirá la plantilla. |
wabaAccountId | string | Meta (alternativo) | Cuenta de WhatsApp Business destino cuando tienes varias. |
senderPhone | string E.164 | Twilio (o senderId) | Número de Twilio al que se asocia la plantilla. |
senderId | string | Twilio (alternativo) | Identificador interno del sender de Twilio. |
submit | boolean (true) | opcional | Twilio: enviar a aprobación tras crear el borrador. En Meta se ignora (siempre entra en revisión). |
Crear en la línea oficial (Meta)
curl -X POST "https://app.pushleads.co/api/v1/whatsapp/templates" \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tpl-confirmacion-pedido-v1" \
-d '{
"provider": "meta",
"metaPhoneNumberId": "1098765432100",
"name": "confirmacion_pedido",
"language": "es",
"category": "utility",
"headerFormat": "DOCUMENT",
"headerMediaUrl": "https://tu-cdn.com/ejemplos/factura.pdf",
"body": "Hola {{1}}, tu pedido {{2}} fue confirmado. Te avisaremos cuando salga a reparto.",
"samples": ["Ana", "PED-123"],
"footerText": "Responde a este mensaje si necesitas ayuda",
"buttons": [
{ "type": "URL", "title": "Ver pedido", "url": "https://tienda.com/pedidos" },
{ "type": "QUICK_REPLY", "title": "Cancelar" }
]
}'
HTTP/1.1 201 Created
{
"success": true,
"data": {
"id": "tpl_...",
"provider": "meta",
"name": "confirmacion_pedido",
"displayName": "confirmacion_pedido",
"language": "es",
"category": "UTILITY",
"status": "pending",
"rejectionReason": null,
"body": "Hola {{1}}, tu pedido {{2}} fue confirmado. Te avisaremos cuando salga a reparto.",
"variables": ["1", "2"],
"header": { "format": "DOCUMENT", "text": null, "mediaUrl": "https://tu-cdn.com/ejemplos/factura.pdf" },
"footer": "Responde a este mensaje si necesitas ayuda",
"buttons": [ { "type": "URL", "title": "Ver pedido", "url": "https://tienda.com/pedidos" }, { "type": "QUICK_REPLY", "title": "Cancelar" } ],
"contentSid": null,
"metaTemplateId": "1234567890",
"wabaAccountId": "waba_...",
"senderId": null,
"linePhone": "+573101234567",
"createdAt": "2026-11-15T10:00:00.000Z",
"updatedAt": "2026-11-15T10:00:00.000Z"
}
}Crear en Twilio
{
"provider": "twilio",
"senderPhone": "+14155238886",
"name": "recordatorio_cita",
"displayName": "Recordatorio de cita",
"language": "es",
"category": "utility",
"body": "Hola {{1}}, te recordamos tu cita el {{2}}.",
"variables": [
{ "index": 1, "label": "nombre", "sample": "Ana" },
{ "index": 2, "label": "fecha", "sample": "martes 3 p. m." }
],
"submit": true
}Listar, consultar, sincronizar y eliminar
curl "https://app.pushleads.co/api/v1/whatsapp/templates?provider=meta&status=approved" \ -H "Authorization: Bearer pk_live_tu_api_key" # Consultar al proveedor y refrescar la copia local curl "https://app.pushleads.co/api/v1/whatsapp/templates/tpl_..." \ -H "Authorization: Bearer pk_live_tu_api_key" # Traer a PushLeads las plantillas ya creadas en la WABA o en Twilio curl -X POST "https://app.pushleads.co/api/v1/whatsapp/templates/sync" \ -H "Authorization: Bearer pk_live_tu_api_key" # Eliminar (en Meta se borra también de la WABA, solo ese idioma) curl -X DELETE "https://app.pushleads.co/api/v1/whatsapp/templates/tpl_..." \ -H "Authorization: Bearer pk_live_tu_api_key"
- Estados posibles:
draft(solo Twilio),pending,approved,rejected(conrejectionReason),pausedydisabled. - Si ya existe una plantilla con el mismo nombre e idioma, la creación responde
409 duplicate_name. - Suscríbete al evento
template.statuspara enterarte de la aprobación sin consultar. Solo se emite para plantillas de Meta. - Para enviar con la plantilla usa
metaTemplateId(Meta) ocontentSid(Twilio) de la respuesta, una vez estéapproved.
Webhooks
Recibe en tu servidor los mensajes entrantes y los recibos de entrega
Un webhook es una URL HTTPS pública tuya a la que PushLeads hace un POST por cada evento al que te suscribas. Se registran en Configuración → API keys → Webhooks o con la API. Los eventos se envían al workspace dueño de la línea, así que la misma API key que recibe un message.received puede responder por esa línea.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/v1/webhooks | Lista los webhooks del workspace (secreto enmascarado). |
| POST | /api/v1/webhooks | Crea uno. La respuesta trae el secreto completo una única vez. |
| GET | /api/v1/webhooks/:id | Detalle con última entrega, último error y fallos consecutivos. |
| PATCH | /api/v1/webhooks/:id | Cambia name, url, events, isActive o rota el secreto con rotateSecret: true. |
| DELETE | /api/v1/webhooks/:id | Elimina el webhook y su historial de entregas. |
| POST | /api/v1/webhooks/:id/test | Envía un evento ping. Responde 200 si tu servidor contestó 2xx, 502 en caso contrario, con el código y el error. |
| GET | /api/v1/webhooks/:id/deliveries | Últimas entregas (?limit= hasta 100) con estado, intentos, código HTTP, error y payload. |
Body de creación (POST /api/v1/webhooks)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
name | string ≤ 100 | * | Nombre para identificarlo en el panel. |
url | string https | * | URL pública con HTTPS. Se rechazan direcciones privadas, localhost y hosts internos. |
events | string[] | opcional | Subconjunto de message.received, message.status, template.status. Por defecto los dos primeros. |
curl -X POST "https://app.pushleads.co/api/v1/webhooks" \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-produccion-v1" \
-d '{
"name": "Chatbot producción",
"url": "https://bot.tuempresa.com/pushleads/webhook",
"events": ["message.received", "message.status", "template.status"]
}'
HTTP/1.1 201 Created
{
"success": true,
"data": {
"id": "whe_...",
"workspaceId": "ws_abc",
"name": "Chatbot producción",
"url": "https://bot.tuempresa.com/pushleads/webhook",
"events": ["message.received", "message.status", "template.status"],
"isActive": true,
"secret": "whsec_9f8e7d6c...", // Guárdalo: solo se muestra completo aquí y al rotarlo
"lastDeliveryAt": null,
"lastDeliveryStatus": null,
"lastError": null,
"consecutiveFailures": 0,
"createdAt": "2026-11-15T10:00:00.000Z",
"updatedAt": "2026-11-15T10:00:00.000Z"
}
}# Pausar sin borrar
curl -X PATCH "https://app.pushleads.co/api/v1/webhooks/whe_..." \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{ "isActive": false }'
# Rotar el secreto (la respuesta trae el nuevo secreto completo)
curl -X PATCH "https://app.pushleads.co/api/v1/webhooks/whe_..." \
-H "Authorization: Bearer pk_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{ "rotateSecret": true }'
# Enviar un evento "ping" de prueba (200 si tu servidor respondió 2xx, 502 si no)
curl -X POST "https://app.pushleads.co/api/v1/webhooks/whe_.../test" \
-H "Authorization: Bearer pk_live_tu_api_key"
# Últimas entregas con código HTTP, error y payload (?limit=1..100)
curl "https://app.pushleads.co/api/v1/webhooks/whe_.../deliveries?limit=20" \
-H "Authorization: Bearer pk_live_tu_api_key"Entrega, reintentos y desactivación
- Cada evento se intenta entregar en el momento. Responde 2xx en menos de 10 segundos y procesa en segundo plano; cualquier otro código, un timeout o una redirección cuenta como fallo.
- Los fallos se reintentan tras 1, 5, 15, 60, 180, 360 y 720 minutos. El octavo fallo marca la entrega como
failedy no se repite. Los reintentos llevan el mismoX-PushLeads-Deliveryy el mismoidde evento: úsalos para descartar duplicados. - Las entregas pueden llegar fuera de orden (por ejemplo
deliveredantes de unsentreintentado). Guía tu lógica por el estado, no por el orden de llegada. - El panel muestra
consecutiveFailuresy el último error. Al reactivar un webhook o cambiar su URL el contador se reinicia. - Los eventos no se envían a los webhooks desactivados ni se acumulan mientras estén apagados.
Eventos y payloads
Sobre común y datos de cada tipo de evento
Sobre común y headers
POST https://bot.tuempresa.com/pushleads/webhook
Content-Type: application/json
User-Agent: PushLeads-Webhooks/1.0
X-PushLeads-Event: message.received
X-PushLeads-Delivery: whd_7f1c...
X-PushLeads-Signature: t=1763200000,v1=5f3a9c...
{
"id": "evt_1b2c...",
"type": "message.received",
"createdAt": "2026-11-15T10:00:00.000Z",
"workspaceId": "ws_abc",
"data": { "...": "depende del evento, ver abajo" }
}| Header | Contenido |
|---|---|
X-PushLeads-Event | Tipo de evento (message.received, message.status, template.status, ping). |
X-PushLeads-Delivery | Identificador único de la entrega. Se repite en los reintentos. |
X-PushLeads-Signature | Firma t=<unix>,v1=<hex>: HMAC-SHA256 del texto <t>.<cuerpo crudo> con el secreto del webhook. |
message.received: un cliente escribe a una línea del workspace
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
messageId | string | * | Identificador del mensaje en el inbox de PushLeads. |
conversationId | string | null | * | Conversación del inbox. Úsalo para agrupar o para abrirla en el panel. |
contactId | string | null | * | Contacto del CRM creado o reconocido por el número. |
channel | "whatsapp" | "sms" | * | Canal del mensaje. |
provider | "meta" | "twilio" | * | Proveedor de la línea. Define qué campos usar al responder. |
line | objeto | * | provider, metaPhoneNumberId (Meta), senderPhone (Twilio), phone (número visible de la línea) y label. |
from | objeto | * | phone en E.164, identity cuando WhatsApp no expone el número (identidad de negocio), name del perfil. |
text | string | * | Texto del mensaje. Vacío en mensajes solo multimedia. |
messageType | string | * | text, image, video, audio, document, sticker, location, contacts, interactive, button, reaction… |
media | { url, contentType, type }[] | * | Archivos adjuntos ya re-alojados por PushLeads en URLs HTTPS estables. |
providerMessageId | string | null | * | wamid (Meta) o MessageSid (Twilio). |
timestamp | string ISO | * | Momento en que el cliente envió el mensaje. |
referral | objeto | null | opcional | Datos del anuncio o enlace de origen cuando el cliente llega desde un anuncio Click-to-WhatsApp. |
humanControlled | boolean | * | true cuando ningún agente de IA de PushLeads va a responder (la línea está en manos del equipo o de tu chatbot). |
isNewConversation | boolean | * | true si este mensaje abrió la conversación. |
{
"id": "evt_1b2c...",
"type": "message.received",
"createdAt": "2026-11-15T10:00:00.000Z",
"workspaceId": "ws_abc",
"data": {
"messageId": "msg_1763200000_ab12cd",
"conversationId": "conv_...",
"contactId": "contact_...",
"channel": "whatsapp",
"provider": "meta",
"line": {
"provider": "meta",
"metaPhoneNumberId": "1098765432100",
"senderPhone": null,
"phone": "+573101234567",
"label": null
},
"from": { "phone": "+573001234567", "identity": null, "name": "Ana" },
"text": "Hola, ¿tienen envíos a Medellín?",
"messageType": "text",
"media": [],
"providerMessageId": "wamid.HBgM...",
"timestamp": "2026-11-15T09:59:58.000Z",
"referral": null,
"humanControlled": true,
"isNewConversation": false
}
}
# Mensaje con imagen
"text": "",
"messageType": "image",
"media": [ { "url": "https://.../blob/abc.jpg", "contentType": "image/jpeg", "type": "image" } ]message.status: el proveedor confirma un envío hecho por la API
Solo se emite para mensajes enviados por /api/v1; los envíos del inbox o de campañas no generan este evento. messageId es el mismo id que devolvió el envío.
{
"id": "evt_9a8b...",
"type": "message.status",
"createdAt": "2026-11-15T10:00:05.000Z",
"workspaceId": "ws_abc",
"data": {
"messageId": "api_msg_3f1c0d6e-....",
"status": "delivered",
"previousStatus": "sent",
"channel": "whatsapp",
"provider": "meta",
"to": "+573001234567",
"from": "+573101234567",
"providerMessageId": "wamid.HBgM...",
"errorCode": null,
"errorMessage": null,
"deliveredAt": "2026-11-15T10:00:04.000Z",
"readAt": null
}
}
# Fallo definitivo
"status": "failed",
"errorCode": "131026",
"errorMessage": "Message undeliverable"template.status: Meta aprueba, rechaza o pausa una plantilla
Requiere que la app de Meta tenga suscrito el campo message_template_status_update (ya lo está en la integración de PushLeads). Twilio no envía este aviso: consulta GET /whatsapp/templates/:id.
{
"id": "evt_c0d1...",
"type": "template.status",
"createdAt": "2026-11-15T12:30:00.000Z",
"workspaceId": "ws_abc",
"data": {
"templateId": "tpl_...",
"provider": "meta",
"metaTemplateId": "1234567890",
"name": "confirmacion_pedido",
"language": "es",
"category": "UTILITY",
"category": "utility",
"status": "approved", // approved | rejected | paused | disabled | pending
"providerStatus": "APPROVED", // valor crudo de Meta
"reason": null, // motivo de Meta cuando es rejected
"occurredAt": "2026-11-15T12:30:00.000Z"
}
}ping: prueba manual desde el panel o desde /test
{
"id": "evt_...",
"type": "ping",
"createdAt": "2026-11-15T10:00:00.000Z",
"workspaceId": "ws_abc",
"data": { "message": "Prueba de webhook de PushLeads", "endpointId": "whe_..." }
}Verificar la firma
Rechaza cualquier POST que no venga de PushLeads
- Lee el header
X-PushLeads-Signaturey separat(unix segundos) yv1(hex). - Descarta la entrega si
tdifiere más de 5 minutos de tu reloj (protección contra repetición). - Calcula HMAC-SHA256 con tu secreto sobre el texto
<t>.<cuerpo crudo>, usando el cuerpo exactamente como llegó (no lo parsees y vuelvas a serializar). - Compara en tiempo constante con
v1.
Node.js (Express)
import { createHmac, timingSafeEqual } from "node:crypto"
import express from "express"
const app = express()
const SECRET = process.env.PUSHLEADS_WEBHOOK_SECRET
// Importante: la firma se calcula sobre el cuerpo crudo, no sobre el JSON re-serializado.
app.post("/pushleads/webhook", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("X-PushLeads-Signature") || ""
if (!verifyPushLeads(SECRET, header, req.body.toString("utf8"))) return res.status(401).end()
res.status(200).end() // responde ya; procesa después
const event = JSON.parse(req.body.toString("utf8"))
const deliveryId = req.get("X-PushLeads-Delivery")
queue.push({ deliveryId, event }) // descarta deliveryId repetidos
})
export function verifyPushLeads(secret, signatureHeader, rawBody) {
const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")))
if (!parts.t || !parts.v1) return false
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t))
if (age > 300) return false // 5 minutos de tolerancia contra repetición
const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex")
return expected.length === parts.v1.length &&
timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(parts.v1, "hex"))
}Python (Flask)
import hmac, hashlib, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["PUSHLEADS_WEBHOOK_SECRET"]
def verify_pushleads(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
if "t" not in parts or "v1" not in parts:
return False
if abs(int(time.time()) - int(parts["t"])) > 300:
return False
signed = f"{parts['t']}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
@app.post("/pushleads/webhook")
def webhook():
if not verify_pushleads(SECRET, request.headers.get("X-PushLeads-Signature", ""), request.get_data()):
abort(401)
event = request.get_json()
handle_async(request.headers.get("X-PushLeads-Delivery"), event)
return "", 200Rotación del secreto
Al rotar el secreto (panel o rotateSecret: true) las entregas siguientes se firman con el nuevo de inmediato. Despliega el nuevo secreto en tu servidor antes de rotar, o acepta ambos durante unos minutos.
Códigos de error
Códigos estables para programar tus reintentos
Autenticación, contexto e idempotencia
| HTTP | code | Qué hacer |
|---|---|---|
| 401 | UNAUTHORIZED | API key inválida, revocada o vencida. No reintentes; corrige la clave. |
| 403 | INSUFFICIENT_SCOPE | A la clave le falta el permiso del endpoint. Crea otra clave o amplíala desde el panel. |
| 403 | WORKSPACE_ACCESS_DENIED | El usuario de la clave ya no pertenece al workspace. |
| 403 | WORKSPACE_PERMISSION_DENIED | El rol del usuario de la clave no permite la operación. |
| 403 | CONTEXT_MISMATCH | Enviaste un workspaceId/accountId distinto al de la clave. Quítalo. |
| 400 | INVALID_JSON | El cuerpo no es un objeto JSON válido. |
| 413 | BODY_TOO_LARGE | El cuerpo supera 256 KB. |
| 400 | IDEMPOTENCY_KEY_REQUIRED | Falta el header o no cumple el formato (8 a 128 caracteres permitidos). |
| 409 | IDEMPOTENCY_CONFLICT | La misma clave se usó con otro cuerpo. Usa una clave nueva para la nueva petición. |
| 409 | REQUEST_IN_PROGRESS | La petición original sigue en curso. Espera y repite con la misma clave. |
| 503 | IDEMPOTENCY_UNAVAILABLE | No se pudo verificar la clave. Reintenta con la misma clave. |
| 400 | validation_error | Un campo no cumple el esquema; message indica cuál. |
Envíos
| HTTP | code | Qué hacer |
|---|---|---|
| 400 | invalid_phone | El número no es E.164 válido o coincide con la línea remitente. |
| 400 | invalid_sender | La línea (metaPhoneNumberId, senderPhone o messagingServiceSid) no está activa en el workspace. Revisa /messaging/resources. |
| 400 | invalid_template | No hay plantilla aprobada con ese id para esa línea, o falta headerMediaUrl / couponCode que la plantilla exige. |
| 400 | invalid_variables | details.missing y details.extra listan las variables que faltan o sobran. |
| 400 | unsupported_template | La plantilla usa encabezado de texto dinámico o URL dinámica en botones. Envíala desde el panel o cámbiala. |
| 409 | whatsapp_window_closed | No hay mensaje del cliente en las últimas 24 h por esa línea. Envía una plantilla aprobada. |
| 409 | recipient_unsubscribed | El contacto se dio de baja. No reintentes. |
| 409 | recipient_suppressed | Un envío anterior fue rechazado por el proveedor para este número. Revisa el contacto en el panel antes de reintentar. |
| 409 | send_window_closed | SMS con priority:false fuera de la franja horaria de marketing. Reintenta dentro de la franja o usa priority:true. |
| 409 | provider_not_configured | Falta configurar el proveedor (Twilio o SMS) en el workspace o cuenta. |
| 403 | plan_limit_reached | Se agotó la asignación de SMS o email del plan. Compra créditos o sube de plan. |
| 402 | whatsapp_balance_insufficient | Saldo de WhatsApp insuficiente para una línea de PushLeads. details trae el costo estimado. |
| 502 | provider_rejected | El proveedor rechazó el mensaje (details.providerCode). El mensaje queda failed; corrige antes de reenviar. |
| 502 | provider_outcome_unknown | Sin confirmación del proveedor. Repite con la misma Idempotency-Key o consulta GET /messages/:id antes de reenviar. |
| 404 | not_found | El mensaje, plantilla o webhook no existe en el workspace de la clave. |
Plantillas y webhooks
| HTTP | code | Qué hacer |
|---|---|---|
| 409 | duplicate_name | Ya existe una plantilla con ese nombre en el workspace. Cambia el nombre o sincroniza. |
| 400 | provider_rejected | Meta rechazó la creación (message trae el motivo: variables no consecutivas, ejemplo faltante, archivo del encabezado, etc.). |
| 409 | already_submitted | La plantilla ya está en revisión o aprobada; consulta su estado en lugar de reenviarla. |
| 502 | provider_unavailable | Meta o Twilio no respondieron al consultar el estado. Reintenta más tarde. |
| 400 | invalid_url | La URL del webhook no es HTTPS pública (se rechazan redes privadas y localhost). |
| 409 | limit_reached | Ya hay 10 webhooks en el workspace. Elimina o reutiliza uno. |
| 502 | (test) | POST /webhooks/:id/test responde 502 con success:false cuando tu servidor no contestó 2xx; data trae statusCode y error. |
| 503 | feature_unavailable | Los webhooks aún no están habilitados en esta instalación. Contacta a soporte. |
Flujo de un chatbot externo
El patrón recomendado para usar PushLeads solo como transporte
// 1) Llega message.received
const { data } = event
if (data.channel !== "whatsapp") return
if (data.isNewConversation) await crm.openTicket(data.contactId)
// 2) Tu motor decide la respuesta
const reply = await bot.answer({ user: data.from.phone, text: data.text, media: data.media })
// 3) Respondes por la MISMA línea del evento, dentro de la ventana de 24 h
await fetch("https://app.pushleads.co/api/v1/whatsapp/send", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PUSHLEADS_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `reply-${data.messageId}`, // un reintento tuyo nunca duplica el envío
},
body: JSON.stringify({
to: data.from.phone,
provider: data.provider, // "meta" o "twilio"
...(data.provider === "meta"
? { metaPhoneNumberId: data.line.metaPhoneNumberId }
: { senderPhone: data.line.senderPhone }),
type: "text",
text: reply,
}),
})
// 4) message.status te confirma sent → delivered → read (o failed con errorCode)- Sin agente de IA en la línea. Es la única condición para que no haya dos respuestas. Si luego quieres que PushLeads atienda ciertas horas, asigna un agente y tu bot verá
humanControlled: falseen los eventos. - Responde por la misma línea. Copia
provideryline.metaPhoneNumberIdoline.senderPhonedel evento. Responder por otra línea abre otra conversación y cierra la ventana de 24 horas. - Idempotencia con el id del mensaje entrante.
reply-<messageId>garantiza una sola respuesta aunque tu servidor reintente o reciba el evento dos veces. - Confirma y procesa después. Responde 200 al webhook antes de llamar a tu modelo o tu CRM; 10 segundos pasan rápido.
- Deja el inbox para los humanos. Tu equipo puede entrar a la conversación desde PushLeads en cualquier momento y escribir al cliente; esos mensajes no pasan por tu webhook.
- Usa plantillas para iniciar. Recordatorios, confirmaciones y OTP salen con una plantilla
utilityoauthentication, más baratas que marketing.
Preguntas frecuentes
¿Necesito una cuenta de Twilio?
No. Con la línea oficial de Meta Cloud API conectada en PushLeads, Meta te factura directo y PushLeads no cobra comisión por mensaje. Twilio es opcional para quien ya tiene números allí.
¿Puedo usar un número que ya está en la app de WhatsApp Business?
Sí. La conexión en coexistencia mantiene la app funcionando y además habilita la API. Los mensajes que escribas desde la app aparecen en el inbox pero no disparan webhooks de salida.
¿Los mensajes que envío por la API aparecen en el inbox?
Sí. Cada envío crea o actualiza el contacto y la conversación, y tu equipo puede seguir la charla desde PushLeads.
¿Qué pasa si mi servidor está caído?
Las entregas se reintentan durante unas 23 horas (siete reintentos con espera creciente). Después quedan como failed y puedes verlas en el historial del webhook. Los mensajes del cliente siguen guardados en el inbox.
¿Puedo recibir mensajes de Instagram, Messenger o el chat web por webhook?
Hoy los eventos message.received cubren WhatsApp (Meta y Twilio) y SMS. Los demás canales se atienden desde el inbox o con los agentes de IA de PushLeads.
¿Cómo pruebo sin gastar?
Usa POST /api/v1/webhooks/:id/test para validar la firma y tu endpoint, y envía textos a tu propio número dentro de la ventana de 24 h (los mensajes de servicio dentro de la ventana no tienen costo en Meta).
¿Necesitas ayuda con la integración?
Escríbenos y te acompañamos en la conexión de la línea, la aprobación de plantillas y las pruebas de tu webhook.
