WABA API

Referencia para integrar WhatsApp Business API por rutas públicas de Sendeasy.

Autenticación

Header obligatorio:

Authorization: Bearer <api_token>

Prefijo de rutas

/api/v1/waba/:whatsappId

Templates

Método	Endpoint	Finalidad
`GET`	`/templates`	Listar templates
`POST`	`/templates`	Crear template
`PUT`	`/templates/:templateId`	Actualizar template
`DELETE`	`/templates/:templateName`	Eliminar template

Mensajes

Método	Endpoint	Finalidad
`POST`	`/send`	Enviar template (o texto simple con body específico)
`POST`	`/send-text`	Enviar texto
`POST`	`/send-image`	Enviar imagen
`POST`	`/send-video`	Enviar video
`POST`	`/send-audio`	Enviar audio
`POST`	`/send-document`	Enviar documento
`POST`	`/marketing-lite/send`	Enviar mensaje de marketing (Marketing Messages Lite API)

Nueva API: mensaje de marketing

Endpoint público:

POST /api/v1/waba/:whatsappId/marketing-lite/send

Endpoint Meta usado por el backend:

POST /{phone-number-id}/marketing_messages

Prerrequisitos:

Cuenta WABA con onboarding de Marketing Messages Lite finalizado.
Términos de Marketing Messages Lite aceptados en la cuenta Meta.
Template en categoría MARKETING con estado APPROVED.

Payload

Campo	Tipo	Obligatorio	Observaciones
`to`	`string`	Sí	número en formato internacional (solo dígitos)
`templateName`	`string`	Sí	nombre de template aprobado en Meta
`language`	`string`	No	por defecto: `pt_BR`
`components`	`array`	No	componentes/parámetros del template
`productPolicy`	`string`	No	`CLOUD_API_FALLBACK` (default) o `STRICT`
`messageActivitySharing`	`boolean`	No	por defecto: `true`
`bizOpaqueCallbackData`	`string`	No	regresa en webhook para correlación de campaña

Ejemplo: envío de mensaje de marketing

curl --location 'https://server.sendeasy.pro/api/v1/waba/SEU_WHATSAPP_ID/marketing-lite/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_API_TOKEN' \
  --data '{
    "to": "5511999999999",
    "templateName": "promo_blackfriday",
    "language": "pt_BR",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Juan" }
        ]
      }
    ],
    "productPolicy": "CLOUD_API_FALLBACK",
    "messageActivitySharing": true,
    "bizOpaqueCallbackData": "campaign_blackfriday_2026"
  }'

Respuesta de éxito (ejemplo):

{
  "messages": [
    { "id": "wamid.HBg..." }
  ]
}

Error de límite/opt-out (ejemplo):

{
  "error": "MARKETING_LIMIT_REACHED",
  "message": "User has opted out of marketing messages or reached the limit",
  "details": "..."
}

Ejemplo: envío de texto

curl --location 'https://server.sendeasy.pro/api/v1/waba/SEU_WHATSAPP_ID/send-text' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_API_TOKEN' \
  --data '{
    "to": "5511999999999",
    "text": "¡Hola! Mensaje enviado por la WABA API."
  }'

Ejemplo: envío de template

{
  "to": "5511999999999",
  "templateName": "boas_vindas",
  "language": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Juan" }
      ]
    }
  ]
}

Códigos de error comunes

Código	Cuándo ocurre
`WHATSAPP_NOT_FOUND`	`whatsappId` no existe
`WHATSAPP_CREDENTIALS_MISSING`	canal sin credenciales WABA completas
`MISSING_PARAMETERS`	faltan campos obligatorios del payload
`MARKETING_LIMIT_REACHED`	contacto con opt-out o límite de marketing alcanzado
`WHATSAPP_API_ERROR`	error devuelto por la API de Meta

Webhooks WABA (contrato público)

Cuando el webhook del proyecto está habilitado, Sendeasy envía:

event: "messaging" para eventos de mensaje.
event: "message_status" para actualizaciones de estado de entrega.

Ejemplo (messaging):

{
  "event": "messaging",
  "channel": "waba",
  "data": {},
  "channelId": "uuid-del-canal"
}

Ejemplo (message_status):

{
  "event": "message_status",
  "channel": "whatsapp",
  "data": {
    "messageId": "wamid.HBg...",
    "status": "read",
    "timestamp": "1713800010"
  },
  "channelId": "uuid-del-canal"
}

Valores comunes de data.status:

sent
delivered
read
failed