```
El token identifica el **email remitente** y, a través de él, el proyecto — no hay `whatsappId`/`emailId` en la URL.
**Compatibilidad:** el **API Token del proyecto** (el mismo de la WABA API) también se acepta en este header. En ese caso el remitente es el **primer email verificado** del proyecto — útil para integraciones hechas antes del token por email, pero para elegir el remitente usa el token del email.
## Endpoints
| Método | Endpoint | Finalidad | Crédito |
| ------ | ---------------------- | ------------------------------------------------- | ----------- |
| `POST` | `/api/v1/email/send` | Enviar email transaccional | 1 por envío |
| `GET` | `/api/v1/email/health` | Diagnóstico: ¿el email del token está verificado? | no consume |
Límite: **20 solicitudes por minuto** por origen (`429 ERR_PUBLIC_EMAIL_RATE_LIMIT`).
## Envío de email
```txt
POST /api/v1/email/send
```
### Payload
| Campo | Tipo | Obligatorio | Observaciones |
| ---------- | --------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| `to` | `string` o `string[]` | Sí | hasta **10 destinatarios** por envío |
| `subject` | `string` | Sí | hasta 200 caracteres |
| `html` | `string` | Uno de los dos | cuerpo HTML, hasta 200.000 caracteres |
| `text` | `string` | Uno de los dos | cuerpo en texto plano, hasta 20.000 caracteres |
| `fromName` | `string` | No | nombre visible del remitente (hasta 80 caracteres). La dirección es siempre el email dueño del token |
El remitente (`fromEmail`) **no se acepta** en el payload: la ruta usa siempre el email dueño del token. Esto impide que un token envíe en nombre de un email que no es tuyo.
### Ejemplo
```bash
curl --location 'https://backend.sendeasy.app/api/v1/email/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN_DEL_EMAIL' \
--data '{
"to": "cliente@ejemplo.com",
"subject": "Restablecimiento de contraseña",
"fromName": "Mi Plataforma",
"html": "¡Hola! Haz clic en el enlace de abajo para crear una nueva contraseña.
"
}'
```
Respuesta de éxito:
```json
{
"success": true,
"id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61"
}
```
El `id` es el identificador del envío en el proveedor. La respuesta confirma que el email fue **aceptado para entrega** — la entrega final depende del servidor del destinatario.
## Diagnóstico de la integración
```txt
GET /api/v1/email/health
```
No consume crédito. Indica si el email del token ya está verificado — la causa más común de que un envío falle aun con crédito disponible.
```bash
curl --location 'https://backend.sendeasy.app/api/v1/email/health' \
--header 'Authorization: Bearer TOKEN_DEL_EMAIL'
```
```json
{
"ok": true,
"senderConfigured": true,
"sender": "no-reply@tuempresa.com",
"domain": "tuempresa.com",
"channelId": 12
}
```
Con `senderConfigured: false`, termina de verificar el email en **Canales → Email** antes de enviar. (Con el API Token del proyecto la respuesta viene sin `channelId` y dice si el proyecto tiene *algún* email verificado.)
## Créditos y reembolso
* Cada envío aceptado descuenta **1 crédito de email** del proyecto.
* Sin crédito, la ruta responde `402 ERR_NO_EMAIL_CREDITS` **antes** de cualquier débito.
* Si el envío falla **después** del débito (remitente no configurado, proveedor no disponible), el crédito se **reembolsa automáticamente** y la ruta responde `502`/`503`.
## Códigos de error
| HTTP | `error` | Cuándo ocurre |
| ---- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| 400 | `ERR_EMAIL_INVALID_BODY` | payload inválido (sin `to`/`subject`, sin `html` ni `text`, ningún destinatario válido) |
| 400 | `ERR_EMAIL_TOO_MANY_RECIPIENTS` | más de 10 destinatarios en un envío |
| 401 | `ERR_API_TOKEN_NOT_PROVIDED` / `ERR_API_TOKEN_INVALID` | header ausente o token inválido/inactivo |
| 402 | `ERR_NO_EMAIL_CREDITS` | proyecto sin créditos de email |
| 429 | `ERR_PUBLIC_EMAIL_RATE_LIMIT` | más de 20 solicitudes por minuto |
| 502 | `ERR_EMAIL_SEND_FAILED` | fallo del proveedor al enviar (crédito reembolsado) |
| 503 | `ERR_EMAIL_SENDER_NOT_CONFIGURED` | el email del token aún no está verificado (con token del email, antes de cualquier débito) |
## Email API vs. integración Custom
Sendeasy ofrece dos formas de enviar email por API — elige según el tipo de token que tengas:
| | Email API (`/api/v1/email/send`) | Custom (`/api/integration/generic`) |
| ---------- | ---------------------------------------------------- | ----------------------------------------------------- |
| Token | **token del email** (Canales → Email → API de envío) | token de integración ligado a **un canal** de email |
| Remitente | el email dueño del token | el canal del token |
| Uso típico | emails transaccionales desde tu propia aplicación | integraciones por canal, con `bcc`, `inReplyTo`, etc. |
Detalles de la integración Custom en [/es/server/integracoes](https://docs.sendeasy.app/es/server/integracoes.md).
**Seguridad:** trata el token como una contraseña. Nunca lo incrustes en JavaScript del navegador, repositorios públicos o logs — guárdalo en variables de entorno o en un secret manager en tu servidor.
---
# Integraciones (Server)
Sendeasy ofrece dos productos de integración:
* **Webhook** — Sendeasy envía eventos de tu proyecto a una URL tuya.
* **Custom (genérica)** — tu aplicación llama a Sendeasy para enviar mensajes.
Los webhooks admiten **dos alcances**:
* **General**: recibe eventos de **todos** los canales de la empresa.
* **Por canal específico**: recibe eventos **solo** del canal elegido (una instancia de WhatsApp, una casilla de Email, un número SMS).
Ambos alcances coexisten: puedes tener 1 webhook general + N webhooks por canal activos al mismo tiempo. Cada evento dispara la UNIÓN de los webhooks aplicables (general + específico). Los tokens **custom** siempre requieren un canal específico.
## Configuración en la UI
Ve a **Configuración → Integraciones**. Verás una lista de integraciones.
Para cada una:
1. Haz clic en **Nueva integración**.
2. Para webhook, elige el **alcance**: *General (todos los canales)* o *Canal específico*.
3. Si "Canal específico", elige el **tipo** (`whatsapp`/`email`/`sms`) y la instancia.
4. Para **webhook**: indica la URL y, opcionalmente, un bearer token enviado
en el header `Authorization`.
5. Para **custom**: el token lo genera el sistema y se muestra **una sola
vez**. Cópialo y guárdalo de inmediato.
## Envío de mensajes — `POST /api/integration/generic`
Este endpoint pasa a tener **payloads distintos por tipo de canal**. El canal
de destino se **deriva del token** — tu aplicación no envía `channelType` en
el body. Un token creado para Email solo puede enviar Email; un token de SMS
solo puede enviar SMS.
Header obligatorio:
```
Authorization: Bearer
```
### WhatsApp
```bash
curl -X POST https://backend.sendeasy.app/api/integration/generic \
-H "Authorization: Bearer 12G3N3R1$..." \
-H "Content-Type: application/json" \
-d '{
"name": "Lead WhatsApp",
"number": "5511999999999",
"message": "Quiero hablar con ventas",
"email": "lead@empresa.com",
"url": "https://landing.com/?utm_source=meta",
"files": ["https://landing.com/presentacion.pdf"],
"sector": "12"
}'
```
```json
{ "success": true, "channel": "whatsapp", "messageId": null, "contactId": null }
```
| Campo | Tipo | Obligatorio |
| --------- | ------------------------ | ----------- |
| `number` | `string` (E.164 sin `+`) | sí |
| `message` | `string` | sí |
| `name` | `string` | no |
| `email` | `string` | no |
| `url` | `string` (UTM) | no |
| `files` | `string[]` (URLs) | no |
| `sector` | `string` (id de cola) | no |
### Email
```bash
curl -X POST https://backend.sendeasy.app/api/integration/generic \
-H "Authorization: Bearer 12G3N3R1$..." \
-H "Content-Type: application/json" \
-d '{
"to": ["cliente@empresa.com"],
"subject": "Confirmación de tu pedido",
"html": "¡Gracias por tu compra!
",
"bcc": ["archivo@empresa.com"]
}'
```
```json
{ "success": true, "channel": "email", "messageId": "msg_abc123", "contactId": null }
```
| Campo | Tipo | Obligatorio |
| --------------- | ------------------------------ | -------------- |
| `to` | `string` o `string[]` (emails) | sí |
| `subject` | `string` | sí |
| `body` o `html` | `string` | uno de los dos |
| `bcc` | `string` o `string[]` | no |
| `text` | `string` | no |
| `fromName` | `string` | no |
| `inReplyTo` | `string` | no |
| `references` | `string` o `string[]` | no |
La dirección remitente (`fromEmail`) es la del canal vinculado al token.
### SMS
```bash
curl -X POST https://backend.sendeasy.app/api/integration/generic \
-H "Authorization: Bearer 12G3N3R1$..." \
-H "Content-Type: application/json" \
-d '{
"to": "+5511999999999",
"body": "Tu código: 123456"
}'
```
```json
{ "success": true, "channel": "sms", "messageId": "SMxxxxxxxx", "contactId": null }
```
| Campo | Tipo | Obligatorio |
| ----------- | -------------------------- | ----------- |
| `to` | `string` (E.164 con `+`) | sí |
| `body` | `string` (≤ 1600 chars) | sí |
| `mediaUrls` | `string[]` (URLs públicas) | no |
| `metadata` | `object` | no |
## Códigos de respuesta
| HTTP | `error` | Significado |
| ---- | ------------------- | ----------------------------------------- |
| 200 | — | Éxito |
| 400 | `VALIDATION_ERROR` | Payload inválido — ver `details[]` |
| 401 | `ERR_NO_PERMISSION` | Token ausente/inválido |
| 402 | `PROVIDER_ERROR` | Sin créditos para el canal |
| 404 | `CHANNEL_NOT_FOUND` | Canal eliminado tras crear el token |
| 502 | `PROVIDER_ERROR` | Falla en el proveedor (Twilio, Resend, …) |
| 410 | `GONE` | Endpoint legado descontinuado |
## Rotación de tokens
Los tokens `custom` pueden rotarse en cualquier momento en **Configuración →
Integraciones**. **La rotación invalida el token anterior de forma inmediata.**
Recomendamos rotación periódica (90 días) e inmediata ante sospecha de
filtración.
## Seguridad
**Nunca** incrustes tokens en JavaScript del navegador, repositorios
públicos, capturas de pantalla o logs. Trata el token como una contraseña.
Almacénalo en variables de entorno, vault o secret manager. Si se expone,
rótalo de inmediato.
## Dónde gestionar
Toda la gestión de tokens y webhooks vive en la plataforma, en
**Configuración → Integraciones**. Los tokens creados anteriormente siguen
funcionando — solo revisa y ajusta la configuración en la nueva pantalla.
---
# Integración Server
Esta sección es el punto de entrada técnico para integraciones backend con Sendeasy.
## Qué incluye
* **Referencia Técnica**: contratos prácticos de request/response.
* **API Pública**: autenticación, payloads y catálogo de endpoints.
* **Integraciones**: flujo público Generic.
* **WABA API**: endpoints de templates y media.
* **Email API**: envío de emails transaccionales vía `/api/v1/email/*`, con créditos del proyecto.
* **Bots API**: generación de texto, extracción de PDF y búsqueda vía `/api/v1/ai/*`, con créditos de bot del proyecto.
* **Webhooks**: eventos efectivamente reenviados al webhook de tu proyecto.
* **Traducciones de Errores**: estrategia de catálogo multilenguaje.
## Orden recomendado de lectura
1. [/es/server/referencia-tecnica](https://docs.sendeasy.app/es/server/referencia-tecnica.md)
2. [/es/server/api-publica](https://docs.sendeasy.app/es/server/api-publica.md)
3. [/es/server/integracoes](https://docs.sendeasy.app/es/server/integracoes.md)
4. [/es/server/waba](https://docs.sendeasy.app/es/server/waba.md)
5. [/es/server/email](https://docs.sendeasy.app/es/server/email.md)
6. [/es/server/bots](https://docs.sendeasy.app/es/server/bots.md)
7. [/es/server/webhooks](https://docs.sendeasy.app/es/server/webhooks.md)
8. [/es/server/traducoes](https://docs.sendeasy.app/es/server/traducoes.md)
---
# Referencia Técnica
Runbook orientado a desarrolladores para integraciones reales: endpoint, payload, respuesta y comportamiento operacional.
## TL;DR de integración
* Base URL: `https://backend.sendeasy.app`
* Auth: `Authorization: Bearer `
* Formatos: `application/json` y `multipart/form-data`
* Muchos flujos se encolan de forma asíncrona
* Trata `error` como contrato estable de máquina
## Endpoint principal de envío
`POST /api/messages/send`
```bash
curl --location 'https://backend.sendeasy.app/api/messages/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer CHANNEL_TOKEN' \
--data '{
"number": "5511999999999",
"body": "Hola desde la integración"
}'
```
Respuesta típica:
```json
{
"message": "Message queued successfully"
}
```
## Referencia rápida WABA
Prefijo:
```txt
/api/v1/waba/:whatsappId
```
Ejemplos:
* `GET /templates`
* `POST /send`
* `POST /send-text`
* `POST /send-image`
* `POST /send-document`
* `POST /marketing-lite/send`
## Referencia rápida Email API
Email transaccional desde el email dueño del token (cada email del proyecto tiene el suyo, en Canales → Email), 1 crédito de email por envío:
* `POST /api/v1/email/send` — body `{ to, subject, html | text, fromName? }`
* `GET /api/v1/email/health` — ¿el email del token está verificado? (sin crédito)
Referencia completa en [/es/server/email](https://docs.sendeasy.app/es/server/email.md).
## Referencia rápida Bots API
Generación de texto, extracción de PDF y búsqueda en la base de conocimiento, 1 crédito de bot por generación (el mismo saldo del bot de atención en WhatsApp). El prompt vive en el bot (`botId`); sin saldo la respuesta es `402 ERR_NO_BOT_CREDITS`:
* `POST /api/v1/ai/completion` — body `{ prompt, botId | instructions, responseFormat? }`
* `POST /api/v1/ai/extract` — multipart, campo `file` (PDF hasta 25 MB)
* `POST /api/v1/ai/search` — body `{ botId, query, topK? }`; solo recuperación (sin crédito)
* `GET /api/v1/ai/health` — ¿el servicio de IA está en línea y hay saldo? (sin crédito)
Referencia completa en [/es/server/bots](https://docs.sendeasy.app/es/server/bots.md).
## Referencia rápida de webhooks
Forma del payload enviado a tu URL de webhook:
```txt
{ event, channel, data, channelId }
```
Ejemplo:
```json
{
"event": "messages.upsert",
"channel": "whatsapp",
"data": {},
"channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
## Estrategia de error
```js
function normalizeApiError(status, body) {
return {
status,
code: body?.error || 'UNKNOWN_ERROR',
message: body?.message || null,
}
}
```
Para detalles completos por endpoint, continúa con las páginas de esta sección
server (API Pública, Integraciones, WABA, Webhooks y Traducciones de Errores).
---
# Traducciones de Errores (PT / EN / ES)
Esta página centraliza traducciones de códigos de error usados en integraciones de Sendeasy.
## Paridad con frontend
Usa el mismo modelo del frontend (`backendErrors`) para mantener consistencia entre:
* mensajes mostrados en el panel web
* mensajes mostrados en integraciones externas (portales, ERPs, apps propias)
Estrategia recomendada:
1. Backend retorna `error` (código estable).
2. Tu cliente traduce vía catálogo por idioma.
3. Fallback al código de error cuando falte traducción.
## Uso en integración
1. Trata `error` como clave estable de máquina.
2. Muestra `message` cuando esté disponible.
3. Opcionalmente usa fallback a tu catálogo local.
## Códigos comunes
| Código | Português | English | Español |
| ------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------ |
| `ERR_NO_PERMISSION` | Você não tem permissão para acessar este recurso. | You do not have permission to access this resource. | No tienes permiso para acceder a este recurso. |
| `ERR_SESSION_EXPIRED` | Sessão expirada. Por favor, faça login. | Session expired. Please log in. | Sesión expirada. Por favor, inicia sesión. |
| `ERR_API_TOKEN_NOT_PROVIDED` | API token não informado. | API token was not provided. | No se proporcionó API token. |
| `ERR_API_TOKEN_INVALID` | API token inválido. | Invalid API token. | API token inválido. |
| `ERR_API_TOKEN_INVALID_FORMAT` | Formato de API token inválido. | Invalid API token format. | Formato de API token inválido. |
| `ERR_API_TOKEN_AUTHENTICATION_FAILED` | Falha na autenticação do API token. | API token authentication failed. | Fallo en la autenticación del API token. |
| `ERR_SENDING_TEMPLATE` | Erro ao enviar template. | Error sending template. | Error al enviar plantilla. |
| `ERR_SENDING_MESSAGE` | Erro ao enviar mensagem. | Error sending message. | Error al enviar mensaje. |
| `ERR_SENDING_IMAGE` | Erro ao enviar imagem. | Error sending image. | Error al enviar imagen. |
| `ERR_SENDING_VIDEO` | Erro ao enviar vídeo. | Error sending video. | Error al enviar video. |
| `ERR_SENDING_AUDIO` | Erro ao enviar áudio. | Error sending audio. | Error al enviar audio. |
| `ERR_SENDING_DOCUMENT` | Erro ao enviar documento. | Error sending document. | Error al enviar documento. |
| `ERR_INVALID_WABA_RECIPIENT` | Destinatário WABA inválido. | Invalid WABA recipient. | Destinatario WABA inválido. |
| `ERR_EMAIL_INVALID_BODY` | Payload de e-mail inválido. | Invalid email payload. | Payload de email inválido. |
| `ERR_EMAIL_TOO_MANY_RECIPIENTS` | Muitos destinatários em um único envio (máximo 10). | Too many recipients in a single send (max 10). | Demasiados destinatarios en un solo envío (máximo 10). |
| `ERR_NO_EMAIL_CREDITS` | Sem créditos de e-mail. | No email credits. | Sin créditos de email. |
| `ERR_NO_BOT_CREDITS` | Sem créditos de bot. | No bot credits. | Sin créditos de bot. |
| `ERR_PUBLIC_EMAIL_RATE_LIMIT` | Limite de requisições de e-mail excedido. | Email request limit exceeded. | Límite de solicitudes de email excedido. |
| `ERR_PUBLIC_AI_RATE_LIMIT` | Limite de requisições de IA excedido. | AI request limit exceeded. | Límite de solicitudes de IA excedido. |
| `ERR_EMAIL_SEND_FAILED` | Falha ao enviar e-mail. | Failed to send email. | Error al enviar email. |
| `ERR_EMAIL_SENDER_NOT_CONFIGURED` | Projeto sem e-mail verificado para envio. | Project has no verified sender email. | Proyecto sin email verificado para envío. |
| `ERR_WAPP_NOT_CONNECTED` | WhatsApp não está conectado. | WhatsApp is not connected. | WhatsApp no está conectado. |
| `ERR_WIDGET_TOKEN_INVALID` | Token do widget inválido. | Invalid widget token. | Token del widget inválido. |
| `ERR_WIDGET_TOKEN_NOT_PROVIDED` | Token do widget não informado. | Widget token was not provided. | No se proporcionó token del widget. |
| `ERR_TRY_AGAIN_LATER` | Por favor, tente novamente mais tarde. | Please try again later. | Por favor, intenta de nuevo más tarde. |
| `FILE_TOO_LARGE` | Arquivo muito grande. O tamanho máximo é de 10MB. | File too large. The maximum size is 10MB. | Archivo demasiado grande. El tamaño máximo es de 10MB. |
## Ejemplo en cliente
```js
const fallbackTranslations = {
ERR_NO_PERMISSION: {
pt: 'Você não tem permissão para acessar este recurso.',
en: 'You do not have permission to access this resource.',
es: 'No tienes permiso para acceder a este recurso.',
},
}
function resolveErrorMessage(errorCode, locale, backendMessage) {
return backendMessage || fallbackTranslations?.[errorCode]?.[locale] || errorCode
}
```
Si tu producto es multilenguaje, versiona este catálogo junto al cliente para
mantener una UX predecible entre releases.
---
# WABA API
Referencia para integrar WhatsApp Business API por rutas públicas de Sendeasy.
## Autenticación
Header obligatorio:
```http
Authorization: Bearer
```
## Prefijo de rutas
```txt
/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) |
| `GET` | `/messages/:messageId/status` | Consultar historial de estados de un mensaje |
## Nueva API: mensaje de marketing
Endpoint público:
```txt
POST /api/v1/waba/:whatsappId/marketing-lite/send
```
Endpoint Meta usado por el backend:
```txt
POST /{phone-number-id}/marketing_messages
```
Prerrequisitos:
1. Cuenta WABA con onboarding de Marketing Messages Lite finalizado.
2. Términos de Marketing Messages Lite aceptados en la cuenta Meta.
3. 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
```bash
curl --location 'https://backend.sendeasy.app/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):
```json
{
"messages": [
{ "id": "wamid.HBg..." }
]
}
```
Error de límite/opt-out (ejemplo):
```json
{
"error": "MARKETING_LIMIT_REACHED",
"message": "User has opted out of marketing messages or reached the limit",
"details": "..."
}
```
## Ejemplo: envío de texto
```bash
curl --location 'https://backend.sendeasy.app/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
```json
{
"to": "5511999999999",
"templateName": "boas_vindas",
"language": "pt_BR",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Juan" }
]
}
]
}
```
### Template con header de medios (IMAGE / VIDEO / DOCUMENT)
Cuando el template aprobado tiene un header de medios, hay que enviar el componente `header` con `parameters`. Usa `type` en minúsculas (`header`/`body`), y la imagen debe servirse desde una **URL pública propia** (S3, CDN, etc.) — no uses el `header_handle` devuelto en la definición del template, expira.
```json
{
"to": "5511999999999",
"templateName": "promo_lanzamiento",
"language": "es_CO",
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": { "link": "https://tu-cdn.com/banner.jpg" }
}
]
}
]
}
```
Alternativamente, reemplaza `link` por `id` con el `media_id` devuelto por la subida en `/api/v1/waba/:whatsappId/media`.
## Consulta de estado de mensaje
La Cloud API de Meta **no expone un endpoint público para consultar el estado bajo demanda** — el estado se entrega exclusivamente por webhook (`sent` / `delivered` / `read` / `failed`). Sendeasy persiste cada evento recibido y entrega el historial en esta ruta, con el mismo formato del payload del webhook.
```txt
GET /api/v1/waba/:whatsappId/messages/:messageId/status
```
### Ejemplo
```bash
curl --location 'https://backend.sendeasy.app/api/v1/waba/TU_WHATSAPP_ID/messages/wamid.HBg.../status' \
--header 'Authorization: Bearer TU_API_TOKEN'
```
### Respuesta
```json
{
"statuses": [
{
"id": "wamid.HBgMNTUzMT...",
"status": "sent",
"timestamp": "1710000000",
"recipient_id": "5511999999999"
},
{
"id": "wamid.HBgMNTUzMT...",
"status": "failed",
"timestamp": "1710000003",
"recipient_id": "5511999999999",
"errors": [
{ "code": 131026, "title": "Message undeliverable" }
]
}
]
}
```
Cuando aún no hay eventos registrados para el `messageId`, la respuesta es `404` con `statuses: []` — basta con reintentar tras unos segundos. Solo los mensajes enviados por el canal WABA tienen estado persistido en esta ruta.
## 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:
1. `event: "messaging"` para eventos de mensaje.
2. `event: "message_status"` para actualizaciones de estado de entrega.
Ejemplo (`messaging`):
```json
{
"event": "messaging",
"channel": "waba",
"data": {},
"channelId": "uuid-del-canal"
}
```
Ejemplo (`message_status`):
```json
{
"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`
## Solicitar compartir el contacto
[Solicitar compartir el contacto](https://docs.sendeasy.app/es/integrations/waba/request-contact.md): Solicite el teléfono por WABA/BSUID o ZuckZapGo/LID con la API pública de SendEasy.
---
# Webhooks (Server)
Esta página describe **lo que tu aplicación recibe** en los webhooks
configurados cuando Sendeasy procesa eventos de canal y mensaje.
## Alcances: general y por canal
Los webhooks tienen **dos alcances posibles**:
* **General**: recibe eventos de **todos** los canales de la empresa. Piénsalo
como el webhook "global" de la cuenta.
* **Por canal específico**: recibe eventos **solo** del canal al que está
vinculado.
Ambos alcances coexisten. Para cada evento, Sendeasy dispara la **unión**:
todos los webhooks generales activos de la empresa **más** el/los webhook(s)
por canal de ese canal. Configura cuantos quieras de cada alcance.
Ejemplo: la empresa tiene 2 instancias de WhatsApp y 1 casilla de Email.
Puedes configurar:
* 1 webhook en URL A → solo recibe eventos del WhatsApp Ventas.
* 1 webhook en URL B → solo recibe eventos del WhatsApp Soporte.
* 1 webhook en URL C → solo recibe eventos del Email Soporte.
Configura desde **Configuración → Integraciones**.
## Flujo resumido
1. Sendeasy procesa un evento de canal/mensaje.
2. El payload se normaliza al contrato público.
3. Sendeasy busca todos los webhooks `enabled=true` vinculados al canal
origen del evento.
4. Para cada webhook encontrado, hace `POST` a la URL configurada con el
payload en el body. Si hay bearer token configurado, va en el header
`Authorization`.
## Payload base
| Campo | Tipo | Descripción |
| ----------- | ------------------ | ------------------------------------------------------------------- |
| `event` | `string` | nombre del evento |
| `channel` | `string` | tipo de canal: `"whatsapp"`, `"email"` o `"sms"` |
| `data` | `object` | payload específico del evento |
| `channelId` | `string \| number` | identificador del canal — UUID (WhatsApp) o id numérico (Email/SMS) |
```json
{
"event": "messages.upsert",
"channel": "whatsapp",
"data": {},
"channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
## Eventos por canal
### WhatsApp (`channel: "whatsapp"` o `"waba"`)
#### `connection.update`
```json
{ "state": "open" }
```
Valores comunes: `open`, `close`.
#### `messages.upsert` / `messages.set` / `send.message`
```json
{
"key": {
"remoteJid": "5511999999999@s.whatsapp.net",
"fromMe": false,
"id": "3EB0XXXXXX"
},
"message": { "conversation": "Hola, necesito ayuda" },
"messageTimestamp": "1634567890",
"pushName": "Cliente"
}
```
#### `messages.update`
```json
{ "keyId": "3EB0XXXXXX", "fromMe": true, "status": 3 }
```
`status`: `1` (sent), `2` (delivered), `3` (read).
#### `messages.delete`
```json
{ "id": "3EB0XXXXXX", "fromMe": false, "remoteJid": "5511999999999@s.whatsapp.net" }
```
#### `call`
```json
{ "id": "CALL_ID_123", "from": "5511999999999@s.whatsapp.net", "status": "reject" }
```
#### WABA — `messaging` y `message_status`
```json
{
"event": "message_status",
"channel": "whatsapp",
"data": { "messageId": "wamid.HBg...", "status": "read", "timestamp": "1713800010" },
"channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
### Email (`channel: "email"`)
Disparado cuando la casilla vinculada al webhook recibe un email.
```json
{
"event": "messaging",
"channel": "email",
"channelId": 7,
"data": {
"email": {
"direction": "inbound",
"mailbox": "soporte@empresa.com",
"from": { "email": "cliente@dominio.com", "name": "Cliente" },
"to": ["soporte@empresa.com"],
"subject": "Consulta sobre el pedido #1234",
"text": "Hola, quería saber...",
"html": "...
",
"messageId": "",
"receivedAt": "2026-04-28T13:45:00.000Z"
}
}
}
```
### SMS (`channel: "sms"`)
Disparado cuando el número vinculado al webhook recibe un SMS.
```json
{
"event": "messaging",
"channel": "sms",
"channelId": 15,
"data": {
"sms": {
"direction": "inbound",
"from": "+5511999999999",
"body": "Confirmar cita",
"providerPayload": { "...": "raw provider data" }
}
}
}
```
## Buenas prácticas de consumo
1. Trata el procesamiento como asíncrono e implementa retry con backoff.
2. Usa idempotencia por `event` + identificadores (`key.id`, `keyId`,
`data.email.messageId`, …).
3. Almacena el payload bruto para troubleshooting.
4. Valida el header `Authorization` cuando esté configurado en el webhook.
5. Configura timeouts cortos (≤ 5s) — si Sendeasy no recibe respuesta en
5s, el webhook se considera fallido y el evento se descarta (no hay
retry automático).
## Dónde gestionar
Los webhooks se configuran y activan en **Configuración → Integraciones**
en la plataforma.
---
# Integración Web
Esta página cubre integraciones de Sendeasy basadas en navegador.
## Flujo típico
1. Activa acceso API para el canal deseado.
2. Configura orígenes permitidos.
3. Usa token bearer en requests.
4. Envía mensajes con payload JSON o multipart.
Para integraciones server-to-server de nivel productivo, prioriza las guías de
Server API en [/es/server](https://docs.sendeasy.app/es/server.md).
---
# Crear Bot
En esta página encontrarás una guía detallada paso a paso para crear y configurar un bot en Sendeasy.
# Paso a paso para crear un bot
## 1. Acceder al proyecto
* En la página principal de Sendeasy, **haz clic en el proyecto** donde quieres crear el bot.
## 2. Ir a la sección de Bots
* Al entrar al proyecto, serás redirigido al **dashboard del proyecto**.
* En el menú del dashboard, **haz clic en "Bots"**.
## 3. Agregar un nuevo bot
* En la esquina superior derecha de la página de Bots, **haz clic en "+ Agregar"**.
* Esto abrirá un pop-up con el formulario para crear el bot.
## 4. Completar la información del bot
Completa los campos del formulario. Campos principales:
### Sector
* **Selecciona el sector** donde el bot estará asociado (ej.: "Sector Atención Bot").
* El bot responderá automáticamente a todos los mensajes enviados por el cliente a ese sector.
### Nombre del bot
* **Ingresa el nombre del bot**. Este campo es obligatorio y debe ser único.
* El nombre se usará para identificar el bot dentro de la plataforma.
### Búsqueda de datos en tiempo real
* **Activa la búsqueda en tiempo real** si necesitas que el bot consulte una fuente externa.
* Al activarla, el bot podrá hacer fetch en tiempo real a una URL específica.
* **Tipos soportados**: XML, JSON, HTML.
⚠️ **Importante**: No es compatible con proxy. El contratante es responsable por el uso indebido de esta funcionalidad. Asegúrate de que la URL sea legítima.
## 5. Guardar el bot
* **Haz clic en "Guardar"** después de completar los campos.
* Una vez guardado, el bot quedará activo para nuevas conversaciones asociadas al sector elegido.
## 6. Comportamiento del bot en atención
* Cuando nuevas conversaciones se asocian al sector del bot, este inicia el pre-atendimiento.
* **Bot desactivado automáticamente**: si un agente abre el ticket mientras el bot está activo, el bot se desactiva automáticamente.
* **Respuesta automática**: si no, el bot responde todos los mensajes del cliente cada 10 segundos.
**Ejemplo**: si el cliente envía tres mensajes seguidos ("Hola", "¿Cómo estás?", "Quiero saber los precios"), y no hay un intervalo mayor a 10 segundos entre cada uno, el bot responderá en secuencia, respetando el intervalo de 10 segundos.
***
Sigue estos pasos para configurar bots de atención de forma eficiente y automatizada en Sendeasy. Para dudas o soporte adicional, contacta a nuestro equipo por el chat de la plataforma.
---
# Chat Widget (antiguo)
El Chat Widget por token de integración (`sendeasy-widget-chat-dev.js`, `window.sendeasyConfig`) fue reemplazado por el [Chat del sitio](https://docs.sendeasy.app/widgets/live-chat.md). Ya no recibe mantenimiento ni aparece en el panel.
Los sitios que todavía lo usan siguen funcionando con el código ya instalado. Para migrar, crea un chat del sitio nuevo en **Chat del sitio > Nuevo widget**, pega el código generado y quita el antiguo.
---
# Formulario de captura
Formulario con los campos que elijas. Cada envío se convierte en un contacto (por teléfono, por correo o nuevo) y en un ticket pendiente en el sector elegido, con un mensaje que resume las respuestas.
## Instalación
Créalo en **Chat del sitio > Nuevo widget > Formulario de captura** y pega el código:
```html
```
## Modos
* **Botón flotante**: un botón en la esquina abre el formulario.
* **Pop-up automático**: se abre solo después del retraso, una vez por visita.
* **Dentro de la página**: el formulario aparece donde coloques ``. También puedes apuntar a un elemento con `data-target="#mi-elemento"` en la etiqueta del script. Sin el elemento, cae en el modo flotante.
## Campos
Tipos disponibles: texto, correo, WhatsApp/teléfono, texto largo, lista de opciones y casilla. Cada campo puede ser obligatorio. El nombre, el correo y el WhatsApp se convierten en los datos del contacto; los demás van a la información extra.
## Otras configuraciones
* Texto del botón enviar, mensaje después del envío y redirección opcional.
* Consentimiento (casilla obligatoria con tu texto).
* Etiquetas sobre los campos y marca en el pie.
* Apariencia: color principal, color del texto, color de fondo, título, subtítulo y posición.
## Límites
Por token: 10 envíos por minuto. Por dirección IP: 20 envíos cada 10 minutos.
---
# Chat del sitio
Chat en línea en el sitio, con bot y agentes en tiempo real. El visitante ingresa su nombre (y correo opcional), la conversación se convierte en un ticket pendiente en el sector elegido y el historial queda guardado en el navegador por 7 días.
## Instalación
Crea el widget en **Chat del sitio > Nuevo widget > Chat del sitio** y pega el código generado antes de `