```
The token identifies the **sender email** and, through it, the project — there is no `whatsappId`/`emailId` in the URL.
**Compatibility:** the project **API Token** (the WABA API one) is also accepted in this header. In that case the sender is the project's **first verified email** — handy for integrations built before per-email tokens, but to choose the sender use the email token.
## Endpoints
| Method | Endpoint | Purpose | Credit |
| ------ | ---------------------- | ------------------------------------------- | ---------- |
| `POST` | `/api/v1/email/send` | Send a transactional email | 1 per send |
| `GET` | `/api/v1/email/health` | Diagnostics: is the token's email verified? | none |
Rate limit: **20 requests per minute** per origin (`429 ERR_PUBLIC_EMAIL_RATE_LIMIT`).
## Sending an email
```txt
POST /api/v1/email/send
```
### Payload
| Field | Type | Required | Notes |
| ---------- | ---------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `to` | `string` or `string[]` | Yes | up to **10 recipients** per send |
| `subject` | `string` | Yes | up to 200 characters |
| `html` | `string` | One of the two | HTML body, up to 200,000 characters |
| `text` | `string` | One of the two | plain-text body, up to 20,000 characters |
| `fromName` | `string` | No | sender display name (up to 80 characters). The address is always the email that owns the token |
The sender address (`fromEmail`) is **not accepted** in the payload: the route always uses the email that owns the token. This prevents a token from sending on behalf of an email that is not yours.
### Example
```bash
curl --location 'https://backend.sendeasy.app/api/v1/email/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer EMAIL_TOKEN' \
--data '{
"to": "customer@example.com",
"subject": "Password reset",
"fromName": "My Platform",
"html": "Hi! Click the link below to create a new password.
"
}'
```
Success response:
```json
{
"success": true,
"id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61"
}
```
`id` is the provider's identifier for the send. The response confirms the email was **accepted for delivery** — final delivery depends on the recipient's mail server.
## Integration diagnostics
```txt
GET /api/v1/email/health
```
Does not consume credits. Tells whether the token's email is already verified — the most common reason a send fails even with credits available.
```bash
curl --location 'https://backend.sendeasy.app/api/v1/email/health' \
--header 'Authorization: Bearer EMAIL_TOKEN'
```
```json
{
"ok": true,
"senderConfigured": true,
"sender": "no-reply@yourcompany.com",
"domain": "yourcompany.com",
"channelId": 12
}
```
With `senderConfigured: false`, finish verifying the email in **Channels → Email** before sending. (With the project API Token the response has no `channelId` and tells whether the project has *any* verified email.)
## Credits and refunds
* Every accepted send debits **1 email credit** from the project.
* With no credits, the route answers `402 ERR_NO_EMAIL_CREDITS` **before** any debit.
* If the send fails **after** the debit (sender not configured, provider unavailable), the credit is **refunded automatically** and the route answers `502`/`503`.
## Error codes
| HTTP | `error` | When it happens |
| ---- | ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| 400 | `ERR_EMAIL_INVALID_BODY` | invalid payload (missing `to`/`subject`, neither `html` nor `text`, no valid recipient) |
| 400 | `ERR_EMAIL_TOO_MANY_RECIPIENTS` | more than 10 recipients in one send |
| 401 | `ERR_API_TOKEN_NOT_PROVIDED` / `ERR_API_TOKEN_INVALID` | header missing or token invalid/inactive |
| 402 | `ERR_NO_EMAIL_CREDITS` | project has no email credits |
| 429 | `ERR_PUBLIC_EMAIL_RATE_LIMIT` | more than 20 requests per minute |
| 502 | `ERR_EMAIL_SEND_FAILED` | provider failure while sending (credit refunded) |
| 503 | `ERR_EMAIL_SENDER_NOT_CONFIGURED` | the token's email is not verified yet (with an email token, before any debit) |
## Email API vs. Custom integration
Sendeasy offers two ways to send email by API — pick by the kind of token you have:
| | Email API (`/api/v1/email/send`) | Custom (`/api/integration/generic`) |
| ----------- | ------------------------------------------------ | ------------------------------------------------------ |
| Token | **email token** (Channels → Email → Sending API) | integration token bound to **one** email channel |
| Sender | the email that owns the token | the token's channel |
| Typical use | transactional emails from your own application | per-channel integrations with `bcc`, `inReplyTo`, etc. |
Custom integration details at [/en/server/integracoes](https://docs.sendeasy.app/en/server/integracoes.md).
**Security:** treat the token like a password. Never embed it in browser JavaScript, public repositories or logs — keep it in environment variables or a secret manager on your server.
---
# Integrations (Server)
Sendeasy offers two integration products:
* **Webhook** — Sendeasy pushes events from your project to a URL you control.
* **Custom (generic)** — your application calls Sendeasy to send messages.
Webhooks support **two scopes**:
* **General**: receives events from **every** channel of the company.
* **Channel-specific**: receives events **only** from the chosen channel (one WhatsApp instance, one Email mailbox, one SMS number).
The two scopes coexist: you can have 1 general webhook + N per-channel webhooks active at the same time. Each event fires the UNION of applicable webhooks (general + specific). **Custom** tokens always require a specific channel.
## UI configuration
Go to **Settings → Integrations**. There you'll see a list of integrations.
For each one:
1. Click **New integration**.
2. For webhook, choose the **scope**: *General (all channels)* or *Specific channel*.
3. If "Specific channel", pick the **type** (`whatsapp`/`email`/`sms`) and instance.
4. For **webhook**: provide the URL and, optionally, a bearer token sent in
the `Authorization` header.
5. For **custom**: the token is generated by the system and shown **only
once**. Copy and save it immediately.
## Sending messages — `POST /api/integration/generic`
This endpoint now has **different payloads per channel type**. The destination
channel is **derived from the token** — your application does NOT send
`channelType` in the body. A token created for Email can only send Email; an
SMS token can only send SMS.
Required header:
```
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": "WhatsApp Lead",
"number": "5511999999999",
"message": "I want to talk to sales",
"email": "lead@company.com",
"url": "https://landing.com/?utm_source=meta",
"files": ["https://landing.com/deck.pdf"],
"sector": "12"
}'
```
```json
{ "success": true, "channel": "whatsapp", "messageId": null, "contactId": null }
```
| Field | Type | Required |
| --------- | ---------------------------- | -------- |
| `number` | `string` (E.164 without `+`) | yes |
| `message` | `string` | yes |
| `name` | `string` | no |
| `email` | `string` | no |
| `url` | `string` (UTM) | no |
| `files` | `string[]` (URLs) | no |
| `sector` | `string` (queue id) | no |
### Email
```bash
curl -X POST https://backend.sendeasy.app/api/integration/generic \
-H "Authorization: Bearer 12G3N3R1$..." \
-H "Content-Type: application/json" \
-d '{
"to": ["customer@company.com"],
"subject": "Order confirmation",
"html": "Thanks for your purchase!
",
"bcc": ["archive@company.com"]
}'
```
```json
{ "success": true, "channel": "email", "messageId": "msg_abc123", "contactId": null }
```
| Field | Type | Required |
| ---------------- | ------------------------------- | -------- |
| `to` | `string` or `string[]` (emails) | yes |
| `subject` | `string` | yes |
| `body` or `html` | `string` | one of |
| `bcc` | `string` or `string[]` | no |
| `text` | `string` | no |
| `fromName` | `string` | no |
| `inReplyTo` | `string` | no |
| `references` | `string` or `string[]` | no |
The sender address (`fromEmail`) is the channel bound to the 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": "Your code: 123456"
}'
```
```json
{ "success": true, "channel": "sms", "messageId": "SMxxxxxxxx", "contactId": null }
```
| Field | Type | Required |
| ----------- | ------------------------- | -------- |
| `to` | `string` (E.164 with `+`) | yes |
| `body` | `string` (≤ 1600 chars) | yes |
| `mediaUrls` | `string[]` (public URLs) | no |
| `metadata` | `object` | no |
## Response codes
| HTTP | `error` | Meaning |
| ---- | ------------------- | ------------------------------------ |
| 200 | — | Success |
| 400 | `VALIDATION_ERROR` | Invalid payload — see `details[]` |
| 401 | `ERR_NO_PERMISSION` | Missing/invalid token |
| 402 | `PROVIDER_ERROR` | No credits on this channel |
| 404 | `CHANNEL_NOT_FOUND` | Channel deleted after token created |
| 502 | `PROVIDER_ERROR` | Provider failure (Twilio, Resend, …) |
| 410 | `GONE` | Deprecated legacy endpoint |
## Token rotation
`custom` tokens can be rotated at any time under **Settings → Integrations**.
**Rotation invalidates the previous token immediately.** We recommend periodic
rotation (90 days) and immediate rotation on suspected leaks.
## Security
**Never** embed tokens in browser JavaScript, public repos, screenshots, or
logs. Treat the token like a password. Store it in environment variables, a
vault, or a secret manager. If exposed, rotate immediately.
## Where to manage
All token and webhook management lives on the platform, under **Settings →
Integrations**. Previously created tokens continue to work — just review and
adjust the configuration on the new screen.
---
# Server Integration
This section is the technical entry point for backend integrations with Sendeasy.
## What is covered
* **Technical Reference**: practical request/response contracts.
* **Public API**: authentication, payloads and endpoint catalog.
* **Integrations**: public Generic flow.
* **WABA API**: template and media endpoints.
* **Email API**: transactional email sending via `/api/v1/email/*`, billed in project credits.
* **Bots API**: text generation, PDF extraction and search via `/api/v1/ai/*`, billed in project bot credits.
* **Webhooks**: events effectively forwarded to your project webhook.
* **Error Translations**: multilingual error catalog strategy.
## Recommended reading order
1. [/en/server/referencia-tecnica](https://docs.sendeasy.app/en/server/referencia-tecnica.md)
2. [/en/server/api-publica](https://docs.sendeasy.app/en/server/api-publica.md)
3. [/en/server/integracoes](https://docs.sendeasy.app/en/server/integracoes.md)
4. [/en/server/waba](https://docs.sendeasy.app/en/server/waba.md)
5. [/en/server/email](https://docs.sendeasy.app/en/server/email.md)
6. [/en/server/bots](https://docs.sendeasy.app/en/server/bots.md)
7. [/en/server/webhooks](https://docs.sendeasy.app/en/server/webhooks.md)
8. [/en/server/traducoes](https://docs.sendeasy.app/en/server/traducoes.md)
---
# Technical Reference
Developer-focused runbook for real integrations: endpoint, payload, response and operational behavior.
## Integration TL;DR
* Base URL: `https://backend.sendeasy.app`
* Auth: `Authorization: Bearer `
* Formats: `application/json` and `multipart/form-data`
* Many flows are queued asynchronously
* Treat `error` as stable machine contract
## Main send endpoint
`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": "Hello from integration"
}'
```
Typical response:
```json
{
"message": "Message queued successfully"
}
```
## WABA quick reference
Prefix:
```txt
/api/v1/waba/:whatsappId
```
Examples:
* `GET /templates`
* `POST /send`
* `POST /send-text`
* `POST /send-image`
* `POST /send-document`
* `POST /marketing-lite/send`
## Email API quick reference
Transactional email from the email that owns the token (each project email has its own, in Channels → Email), 1 email credit per send:
* `POST /api/v1/email/send` — body `{ to, subject, html | text, fromName? }`
* `GET /api/v1/email/health` — is the token's email verified? (no credit)
Full reference at [/en/server/email](https://docs.sendeasy.app/en/server/email.md).
## Bots API quick reference
Text generation, PDF extraction and knowledge base search, 1 bot credit per generation (the same balance as the WhatsApp support bot). The prompt lives in the bot (`botId`); no credit without balance answers `402 ERR_NO_BOT_CREDITS`:
* `POST /api/v1/ai/completion` — body `{ prompt, botId | instructions, responseFormat? }`
* `POST /api/v1/ai/extract` — multipart, `file` field (PDF up to 25 MB)
* `POST /api/v1/ai/search` — body `{ botId, query, topK? }`; retrieval only (no credit)
* `GET /api/v1/ai/health` — is the AI service up and is there balance? (no credit)
Full reference at [/en/server/bots](https://docs.sendeasy.app/en/server/bots.md).
## Webhook quick reference
Payload shape sent to your webhook URL:
```txt
{ event, channel, data, channelId }
```
Example:
```json
{
"event": "messages.upsert",
"channel": "whatsapp",
"data": {},
"channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
## Error strategy
```js
function normalizeApiError(status, body) {
return {
status,
code: body?.error || 'UNKNOWN_ERROR',
message: body?.message || null,
}
}
```
For complete endpoint-level details, continue with the pages in this server
section (Public API, Integrations, WABA, Webhooks and Error Translations).
---
# Error Translations (PT / EN / ES)
This page centralizes translations for integration error codes used by Sendeasy.
## Frontend parity
Use the same frontend model (`backendErrors`) to keep consistency between:
* messages shown inside the web dashboard
* messages displayed in external integrations (portals, ERPs, custom apps)
Recommended strategy:
1. Backend returns `error` (stable code).
2. Your client translates via locale catalog.
3. Fallback to the error code when translation is missing.
## Integration usage
1. Treat `error` as a stable machine key.
2. Display `message` when available.
3. Optionally fallback to your local translation catalog.
## Common codes
| Code | 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. |
## Client-side example
```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
}
```
If your product is multilingual, version this catalog with your client to keep
UX predictable across releases.
---
# WABA API
Reference for WhatsApp Business API integration through Sendeasy public routes.
## Authentication
Required header:
```http
Authorization: Bearer
```
## Route prefix
```txt
/api/v1/waba/:whatsappId
```
## Templates
| Method | Endpoint | Purpose |
| -------- | -------------------------- | --------------- |
| `GET` | `/templates` | List templates |
| `POST` | `/templates` | Create template |
| `PUT` | `/templates/:templateId` | Update template |
| `DELETE` | `/templates/:templateName` | Delete template |
## Messages
| Method | Endpoint | Purpose |
| ------ | ----------------------------- | -------------------------------------------------------- |
| `POST` | `/send` | Send template (or plain text with specific payload body) |
| `POST` | `/send-text` | Send text |
| `POST` | `/send-image` | Send image |
| `POST` | `/send-video` | Send video |
| `POST` | `/send-audio` | Send audio |
| `POST` | `/send-document` | Send document |
| `POST` | `/marketing-lite/send` | Send marketing message (Marketing Messages Lite API) |
| `GET` | `/messages/:messageId/status` | Fetch status history for a message |
## New API: marketing message
Public endpoint:
```txt
POST /api/v1/waba/:whatsappId/marketing-lite/send
```
Meta endpoint used by the backend:
```txt
POST /{phone-number-id}/marketing_messages
```
Prerequisites:
1. WABA account with Marketing Messages Lite onboarding completed.
2. Marketing Messages Lite terms accepted in Meta account.
3. Template in `MARKETING` category with `APPROVED` status.
### Payload
| Field | Type | Required | Notes |
| ------------------------ | --------- | -------- | ----------------------------------------------- |
| `to` | `string` | Yes | international number format (digits only) |
| `templateName` | `string` | Yes | approved template name in Meta |
| `language` | `string` | No | default: `pt_BR` |
| `components` | `array` | No | template components/parameters |
| `productPolicy` | `string` | No | `CLOUD_API_FALLBACK` (default) or `STRICT` |
| `messageActivitySharing` | `boolean` | No | default: `true` |
| `bizOpaqueCallbackData` | `string` | No | echoed back in webhook for campaign correlation |
### Example: send marketing message
```bash
curl --location 'https://backend.sendeasy.app/api/v1/waba/YOUR_WHATSAPP_ID/marketing-lite/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
"to": "5511999999999",
"templateName": "promo_blackfriday",
"language": "pt_BR",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "John" }
]
}
],
"productPolicy": "CLOUD_API_FALLBACK",
"messageActivitySharing": true,
"bizOpaqueCallbackData": "campaign_blackfriday_2026"
}'
```
Success response (example):
```json
{
"messages": [
{ "id": "wamid.HBg..." }
]
}
```
Limit/opt-out error (example):
```json
{
"error": "MARKETING_LIMIT_REACHED",
"message": "User has opted out of marketing messages or reached the limit",
"details": "..."
}
```
## Example: send text
```bash
curl --location 'https://backend.sendeasy.app/api/v1/waba/YOUR_WHATSAPP_ID/send-text' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
"to": "5511999999999",
"text": "Hello! Message sent through WABA API."
}'
```
## Example: send template
```json
{
"to": "5511999999999",
"templateName": "welcome",
"language": "en_US",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "John" }
]
}
]
}
```
### Template with media header (IMAGE / VIDEO / DOCUMENT)
When the approved template has a media header, you must send the `header` component with `parameters`. Use lowercase `type` (`header`/`body`), and the image must be served from a **public URL of your own** (S3, CDN, etc.) — do not use the `header_handle` returned in the template definition, it expires.
```json
{
"to": "5511999999999",
"templateName": "promo_launch",
"language": "en_US",
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": { "link": "https://your-cdn.com/banner.jpg" }
}
]
}
]
}
```
Alternatively, replace `link` with `id` using the `media_id` returned by upload at `/api/v1/waba/:whatsappId/media`.
## Message status lookup
Meta's Cloud API **does not expose a public endpoint to query message status on demand** — status is delivered exclusively via webhook (`sent` / `delivered` / `read` / `failed`). Sendeasy persists every received event and serves the full history at this route, in the same format as the webhook payload.
```txt
GET /api/v1/waba/:whatsappId/messages/:messageId/status
```
### Example
```bash
curl --location 'https://backend.sendeasy.app/api/v1/waba/YOUR_WHATSAPP_ID/messages/wamid.HBg.../status' \
--header 'Authorization: Bearer YOUR_API_TOKEN'
```
### Response
```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" }
]
}
]
}
```
When no event has been recorded yet for the `messageId`, the response is `404` with `statuses: []` — just retry after a few seconds. Only messages sent through the WABA channel have their status persisted at this route.
## Common error codes
| Code | Typical cause |
| ------------------------------ | -------------------------------------------------- |
| `WHATSAPP_NOT_FOUND` | `whatsappId` does not exist |
| `WHATSAPP_CREDENTIALS_MISSING` | channel missing required WABA credentials |
| `MISSING_PARAMETERS` | required payload fields are missing |
| `MARKETING_LIMIT_REACHED` | recipient opted out or marketing limit was reached |
| `WHATSAPP_API_ERROR` | error returned by Meta API |
## WABA webhooks (public contract)
When project webhook is enabled, Sendeasy sends:
1. `event: "messaging"` for message events.
2. `event: "message_status"` for delivery status updates.
Example (`messaging`):
```json
{
"event": "messaging",
"channel": "waba",
"data": {},
"channelId": "channel-uuid"
}
```
Example (`message_status`):
```json
{
"event": "message_status",
"channel": "whatsapp",
"data": {
"messageId": "wamid.HBg...",
"status": "read",
"timestamp": "1713800010"
},
"channelId": "channel-uuid"
}
```
Common `data.status` values:
* `sent`
* `delivered`
* `read`
* `failed`
## Request contact sharing
[Request contact sharing](https://docs.sendeasy.app/en/integrations/waba/request-contact.md): Request a phone number through WABA/BSUID or ZuckZapGo/LID using the SendEasy public API.
---
# Webhooks (Server)
This page describes **what your application receives** in the configured
webhooks when Sendeasy processes channel/message events.
## Scopes: general and per-channel
Webhooks have **two possible scopes**:
* **General**: receives events from **every** channel of the company. Think of
it as the "global" webhook for the account.
* **Channel-specific**: receives events **only** from the channel it's bound
to.
The two scopes coexist. For each event, Sendeasy fires the **union**: all
active general webhooks of the company **plus** the per-channel webhook(s)
for that channel. Configure as many of each scope as you want.
Example: a company has 2 WhatsApp instances and 1 Email mailbox. You can set up:
* 1 webhook on URL A → only receives Sales WhatsApp events.
* 1 webhook on URL B → only receives Support WhatsApp events.
* 1 webhook on URL C → only receives Support Email events.
Configure under **Settings → Integrations**.
## Flow summary
1. Sendeasy processes a channel/message event.
2. The payload is normalized to the public contract.
3. Sendeasy looks up all `enabled=true` webhooks bound to the source channel.
4. For each webhook found, it `POST`s the URL with the payload as body. If a
bearer token was configured, it goes in the `Authorization` header.
## Base payload
| Field | Type | Description |
| ----------- | ------------------ | -------------------------------------------------------------- |
| `event` | `string` | event name |
| `channel` | `string` | channel type: `"whatsapp"`, `"email"`, or `"sms"` |
| `data` | `object` | event-specific payload |
| `channelId` | `string \| number` | channel identifier — UUID (WhatsApp) or numeric id (Email/SMS) |
```json
{
"event": "messages.upsert",
"channel": "whatsapp",
"data": {},
"channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
## Events per channel
### WhatsApp (`channel: "whatsapp"` or `"waba"`)
#### `connection.update`
```json
{ "state": "open" }
```
Common values: `open`, `close`.
#### `messages.upsert` / `messages.set` / `send.message`
```json
{
"key": {
"remoteJid": "5511999999999@s.whatsapp.net",
"fromMe": false,
"id": "3EB0XXXXXX"
},
"message": { "conversation": "Hi, I need help" },
"messageTimestamp": "1634567890",
"pushName": "Customer"
}
```
#### `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` and `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"`)
Fired when the bound mailbox receives an email.
```json
{
"event": "messaging",
"channel": "email",
"channelId": 7,
"data": {
"email": {
"direction": "inbound",
"mailbox": "support@company.com",
"from": { "email": "customer@domain.com", "name": "Customer" },
"to": ["support@company.com"],
"subject": "Question about order #1234",
"text": "Hello, I'd like to ask...",
"html": "...
",
"messageId": "",
"receivedAt": "2026-04-28T13:45:00.000Z"
}
}
}
```
### SMS (`channel: "sms"`)
Fired when the bound number receives an SMS.
```json
{
"event": "messaging",
"channel": "sms",
"channelId": 15,
"data": {
"sms": {
"direction": "inbound",
"from": "+5511999999999",
"body": "Confirm appointment",
"providerPayload": { "...": "raw provider data" }
}
}
}
```
## Consumption best practices
1. Treat processing as asynchronous and implement retry with backoff.
2. Use idempotency keyed on `event` + identifiers (`key.id`, `keyId`,
`data.email.messageId`, …).
3. Store the raw payload for troubleshooting.
4. Validate the `Authorization` header when configured on the webhook.
5. Keep timeouts short (≤ 5s) — if Sendeasy doesn't get a response in 5s,
the webhook is treated as failed and the event is dropped (no automatic
retry).
## Where to manage
Webhooks are configured and activated under **Settings → Integrations** on
the platform.
---
# Web Integration
This page covers browser-based integrations for Sendeasy.
## Typical flow
1. Activate API access for the desired channel.
2. Configure allowed origins.
3. Use bearer token in requests.
4. Send messages with JSON or multipart payloads.
For production-grade server-to-server integrations, prefer the Server API
guides in [/en/server](https://docs.sendeasy.app/en/server.md).
---
# Create Bot
In this page, you will find a detailed step-by-step guide to create and configure a bot in Sendeasy.
# Step-by-step to Create a Bot
## 1. Access your Project
* On the Sendeasy home page, **click the project** where you want to create the bot.
## 2. Go to the Bots Section
* Once inside the project, you will be redirected to the **project dashboard**.
* In the dashboard menu, **click "Bots"**.
## 3. Add a New Bot
* In the top-right corner of the Bots page, **click the "+ Add"** button.
* This opens a pop-up form to create the bot.
## 4. Fill in Bot Information
Fill in the form fields with the required information. Main fields:
### Sector
* **Select the sector** where this bot will operate (for example, "Bot Support Sector").
* The bot will automatically reply to all customer messages sent to the selected sector.
### Bot Name
* **Provide the bot name**. This field is required and must be unique.
* The name is used to identify the bot inside the platform.
### Real-time Data Fetch
* **Enable real-time data fetch** when you need the bot to query an external source.
* With this option enabled, the bot can fetch a specified URL in real time.
* **Supported formats**: XML, JSON, HTML.
⚠️ **Important**: Proxy is not supported. The customer is responsible for improper use of this feature. Make sure the URL is legitimate.
## 5. Save the Bot
* **Click "Save"** after filling all fields.
* Once saved, the bot becomes active for new chats associated with the selected sector.
## 6. Bot Behavior During Support
* When a new chat is associated with the bot sector, it starts pre-support automatically.
* **Bot Auto-disable**: if a human agent opens the ticket while the bot is active, it is automatically disabled to prevent overlap.
* **Automatic Replies**: otherwise, the bot replies to all customer messages every 10 seconds.
**Example**: if the customer sends three messages in sequence ("Hi", "How are you?", "I would like pricing"), and there is no interval longer than 10 seconds between them, the bot replies in sequence, respecting the 10-second interval.
***
Follow these steps to configure support bots efficiently and with automation in Sendeasy. For questions or extra support, contact our team through the platform chat.
---
# Chat Widget (legacy)
The Chat Widget based on integration tokens (`sendeasy-widget-chat-dev.js`, `window.sendeasyConfig`) was replaced by the [Website chat](https://docs.sendeasy.app/widgets/live-chat.md). It is no longer maintained and no longer appears in the panel.
Websites still using it keep working with the code already installed. To migrate, create a new website chat in **Website chat > New widget**, paste the generated code and remove the old one.
---
# Lead form
A form with the fields you choose. Every submission becomes a contact (by phone, by email or new) and a pending ticket in the chosen department, with a message summarizing the answers.
## Installation
Create it in **Website chat > New widget > Lead form** and paste the code:
```html
```
## Modes
* **Floating button**: a button in the corner opens the form.
* **Automatic pop-up**: opens by itself after the delay, once per visit.
* **Inside the page**: the form appears where you place ``. You can also point to an element with `data-target="#my-element"` on the script tag. Without the element, it falls back to the floating mode.
## Fields
Available types: text, email, WhatsApp/phone, long text, option list and checkbox. Each field can be required. Name, email and WhatsApp become the contact details; the others go to the extra information.
## Other settings
* Submit button text, message after submit and optional redirect.
* Consent (required checkbox with your text).
* Labels above the fields and brand in the footer.
* Appearance: main color, text color, background color, title, subtitle and position.
## Limits
Per token: 10 submissions per minute. Per IP address: 20 submissions every 10 minutes.
---
# Website chat
Online chat on the website, with bot and agents in real time. The visitor enters a name (and an optional email), the conversation becomes a pending ticket in the chosen department and the history stays in the browser for 7 days.
## Installation
Create the widget in **Website chat > New widget > Website chat** and paste the generated code before `