> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Envio Individual (1-1)
> Envie mensagens HSM personalizadas para destinatários individuais usando a API WhatsApp
A API WhatsApp permite que empresas automatizem e personalizem a comunicação com seus clientes, possibilitando interações eficientes e escaláveis enriquecidas com conteúdo multimídia. É ideal para gerenciar consultas, enviar notificações e fornecer respostas imediatas por meio de Agentes de IA.
***
## Configuração do envio de mensagens
### Passo 1: Definir o Endpoint
Para enviar mensagens, use o seguinte endpoint da API:
```
POST https://api.jelou.ai/v2/whatsapp/{botId}/hsm
```
### Passo 2: Parâmetros da Requisição
Os principais parâmetros da requisição incluem:
* **Text**: O conteúdo da mensagem.
* **Tipo de mensagem (`type`)**: Define o tipo de template a ser enviado.
* **Propriedade do template**: Template previamente criado e aprovado pela META.
* **Arquivo de mídia**: Se o template exigir uma URL (imagem, documento, etc.).
* **Bot ID**: Identificador único do bot.
* **Parâmetros**: Dados específicos para cada envio (nome, número do pedido, etc.).
### Passo 3: Enviar a requisição
Envie a mensagem usando o método **POST**. Após concluir o envio, você receberá uma resposta que permite verificar o status de entrega.
Certifique-se de cumprir as políticas do WhatsApp para evitar restrições.
***
## Restrições de conteúdo
Lembre-se de que, para enviar mensagens pelo WhatsApp, você deve usar templates previamente aprovados pela META.
Cada template tem limitações específicas com base em seu formato e conteúdo, como o comprimento da mensagem ou o tipo de informação permitida. Certifique-se de revisar essas restrições antes de usá-los para garantir a entrega correta.
**Tenha em mente que**:
* URLs, emojis e arquivos multimídia não são permitidos em mensagens de autenticação.
* Os parâmetros devem ter no máximo 15 caracteres.
***
## Corpo da Requisição
| Propriedade | Tipo | Descrição | Obrigatório |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------ | ----------- |
| **mediaUrl** | string | URL pública do arquivo de mídia. Obrigatório se o seu template for do tipo vídeo, imagem ou documento. | Condicional |
| **filename** | string | Nome do arquivo para templates do tipo documento. | Condicional |
| **type** | string | Tipo de mensagem: `text`, `hsm`, `image`, `document`, `video`, `catalog`, `carousel`. Padrão é `text`. | Não |
| **language** | string | Idioma do template: `en`, `es`, `pt` | Não |
| **elementName** | string | Nome do template aprovado. | Sim |
| **parameters** | array | Conjunto de strings que substituem valores no template. | Sim |
| **destinations** | array | Lista de números de telefone. Formato numérico com código do país, sem `+` ou espaços. | Sim |
| **buttonPayloads** | array | Informações para botões de resposta rápida. | Não |
| **actions** | object | Configuração e ações do template em formato de payload. | Não |
| **headerParameters** | array | Parâmetro de cabeçalho, máximo 1 parâmetro. | Não |
| **thumbnailProduct** | string | URL da imagem em miniatura. Obrigatório para templates de catálogo. | Condicional |
| **expirationTime** | string | Tempo de expiração no formato timestamp (milissegundos). | Não |
| **campaignId** | string | Identificador único da campanha associada. | Não |
| **buttonParameters** | array | Configuração para todos os tipos de botão. | Não |
| **ltoParams** | object | Parâmetros de oferta por tempo limitado (LTO). | Não |
| **cards** | array | Cartões de conteúdo para templates de carrossel. | Não |
***
## Tipos de template
Nesta seção, compartilhamos exemplos de requisição para os diferentes tipos de template. Esses exemplos fornecem um guia claro para que você possa facilmente substituir os valores pelos seus próprios dados.
Se o nome de um template ou um botão dentro do JSON diferir do template já aprovado, mesmo por um acento, o envio falhará. **A precisão é fundamental para garantir a funcionalidade.**
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"parameters": ["PARAMETER_1", "PARAMETER_2"],
"destinations": ["PHONE_NUMBER"],
"elementName": "ELEMENT_NAME"
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"parameters": ["PARAMETER_1", "PARAMETER_2"],
"mediaUrl": "https://cdn.example.com/image.jpeg",
"type": "image",
"destinations": ["PHONE_NUMBER"],
"elementName": "ELEMENT_NAME"
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"parameters": ["PARAMETER_1", "PARAMETER_2"],
"mediaUrl": "https://cdn.example.com/video.mp4",
"type": "video",
"destinations": ["PHONE_NUMBER"],
"elementName": "ELEMENT_NAME"
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"parameters": ["PARAMETER_1"],
"mediaUrl": "https://cdn.example.com/document.pdf",
"type": "document",
"destinations": ["PHONE_NUMBER"],
"elementName": "ELEMENT_NAME"
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"parameters": ["PARAMETER_1"],
"destinations": ["PHONE_NUMBER"],
"elementName": "ELEMENT_NAME"
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Accept-Language: en' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"destinations": ["PHONE_NUMBER"],
"parameters": ["PARAMETER_1"],
"elementName": "ELEMENT_NAME",
"buttonParameters": [
{
"type": "URL",
"payload": {"param": "PARAM_URL"}
}
]
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"elementName": "ELEMENT_NAME",
"language": "en",
"type": "text",
"parameters": ["param1", "param2"],
"destinations": ["PHONE_NUMBER"],
"buttonParameters": [
{
"type": "QUICK_REPLY",
"payload": {"type": "edge", "action": "BTN1", "skillId": "1"}
},
{
"type": "QUICK_REPLY",
"payload": {"type": "edge", "action": "BTN2", "skillId": "2"}
},
{
"type": "QUICK_REPLY",
"payload": {"type": "edge", "action": "BTN3", "skillId": "3"}
}
]
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"elementName": "ELEMENT_NAME",
"destinations": ["PHONE_NUMBER"],
"parameters": ["PARAMETER_1", "PARAMETER_2"],
"headerParameters": ["PARAMETER_VALUE"]
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"elementName": "ELEMENT_NAME",
"destinations": ["PHONE_NUMBER"],
"parameters": ["PARAMETER_1"],
"type": "catalog",
"buttonParameters": [
{
"type": "CATALOG",
"payload": {"thumbnailProduct": "productId"}
}
]
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"buttonOptions": {},
"elementName": "ELEMENT_NAME",
"destinations": ["PHONE_NUMBER"],
"parameters": ["PARAMETER_1", "PARAMETER_2"],
"type": "image",
"mediaUrl": "https://cdn.example.com/image.jpeg",
"ltoParams": {"expirationTime": 1733260800000},
"buttonParameters": [
{
"type": "COPY_CODE",
"param": 1,
"payload": {"param": "20OFF"}
}
]
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"buttonOptions": {},
"elementName": "ELEMENT_NAME",
"destinations": ["PHONE_NUMBER"],
"parameters": ["PARAMETER_1"],
"type": "hsm"
}'
```
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"elementName": "ELEMENT_NAME",
"destinations": ["PHONE_NUMBER"],
"parameters": [],
"type": "carousel",
"cards": [
{
"mediaUrl": "https://cdn.example.com/product1.jpg",
"params": ["PARAMETER_VALUE"],
"buttonParameters": [
{
"type": "QUICK_REPLY",
"payload": {"action": "Button 1", "type": "edge", "skillId": "45515", "cardIndex": 0}
}
]
},
{
"mediaUrl": "https://cdn.example.com/product2.jpg",
"params": ["PARAMETER_VALUE_1", "PARAMETER_VALUE_2"],
"buttonParameters": [
{
"type": "QUICK_REPLY",
"payload": {"action": "Button 2", "type": "edge", "skillId": "10192", "cardIndex": 1}
}
]
}
]
}'
```
***
## Casos de uso comuns
### 1. Mensagens personalizadas
Use templates com variáveis para enviar mensagens adaptadas às necessidades de cada usuário (por exemplo, lembretes de pagamento ou atualizações de pedidos).
### 2. Automação com Webhooks
Interações personalizadas com base nas respostas dos usuários, permitindo uma conversa mais dinâmica e eficiente.
**Exemplos de campanhas**:
* **Promoções personalizadas**: Ofertas exclusivas baseadas nas preferências do cliente.
* **Lembretes de pagamento**: Notificações automáticas para datas de vencimento de faturas.
* **Cotações de serviço**: Consultas rápidas sobre seguros, empréstimos, etc.
***
## Configuração avançada
### Número de telefone
Como este é um envio individual, o número de telefone do destinatário deve estar no formato correto para que o envio seja bem-sucedido.
O sinal `+` deve ser omitido, o código do país deve ser incluído e apenas caracteres numéricos são permitidos. Traços ou espaços não são aceitos.
**Para usuários no Equador:** O sinal "+" e o primeiro 0 do número de telefone devem ser omitidos para que seja inserido corretamente.
| ✅ Formato correto | ❌ Formato incorreto | ❌ Formato incorreto |
| :---------------: | :-----------------: | :-----------------: |
| PHONE\_NUMBER | +PHONE\_NUMBER | 09XXXXXXXX |
### Parâmetros específicos
Dependendo da campanha, você pode usar dados personalizados como o tipo de mensagem ou informações adicionais do cliente.
***
## Personalização de mensagens
### Vinculação com Workflows
Cada mensagem pode ser associada a um fluxo específico que define como a resposta do usuário deve ser tratada. Isso é útil para criar interações mais complexas e direcionadas, como menus interativos ou pesquisas.
### Configuração de botões
Você pode usar a seguinte estrutura no campo `buttonPayloads` quando o seu template incluir botões de resposta rápida usando workflows; isso permitirá que você ative workflows adicionais dentro da conversa com base na ação selecionada pelo usuário.
```json theme={null}
[
{"type": "edge", "action": "Yes", "skillId": "1"},
{"type": "edge", "action": "Reschedule", "skillId": "2"},
{"type": "edge", "action": "Cancel", "skillId": "3"}
]
```
Neste caso, cada botão deve ter as chaves `type`, `action` e `skillId`. A chave `action` define o texto que aparecerá no botão, enquanto `skillId` indica o ID do fluxo que o botão ativará.
Para obter o `skillId` de um workflow, passe o cursor sobre o nome do workflow no Brain Studio. Um tooltip será exibido com o ID correspondente.
Redirecione usuários para workflows específicos com base em sua escolha ou interação.
Os templates permitem as seguintes configurações:
```json theme={null}
{
"actions": {
"setSkill": {"id": 2222}
}
}
```
Para obter o `skillId` do workflow, passe o cursor sobre o nome do workflow no Brain Studio. Um tooltip será exibido com o ID correspondente.
```json theme={null}
{
"actions": {
"setMemoryParams": {
"url": "https://apps.jelou.ai"
}
}
}
```
### Parâmetros de Cache
Esta função é usada para salvar informações adicionais no cache para uso posterior. Dependerá da configuração desejada para o template. Se uma URL for enviada, ela pode ser usada por um fluxo para redirecionar essa URL para fins de marketing.
Todos os parâmetros a serem armazenados em cache devem ir em `setMemoryParams` com seus respectivos campos chave-valor.
Esta configuração será válida por 3 meses.
```json theme={null}
{
"actions": {
"setMemoryParams": {
"url": "https://apps.jelou.ai"
}
}
}
```
***
## Respostas da API
```json theme={null}
[
{
"id": "msg-12345-67890-abcde-fghij-klmno",
"destination": "PHONE_NUMBER"
}
]
```
```json theme={null}
{
"message": ["Template does not exist"],
"status": "failed",
"_metadata": {
"error": {},
"body": {
"destinations": [{"destination": "PHONE_NUMBER"}],
"parameters": ["John", "example_value"],
"elementName": "sample_template",
"code": "en",
"type": "text",
"botId": "BOT_ID",
"botName": "Your Bot"
}
},
"error": {}
}
```
```json theme={null}
{
"message": "Authentication failed"
}
```
```json theme={null}
{
"message": ["The Bot could not be found at the moment."],
"statusMessage": "failed",
"status": 0,
"error": {
"code": "E1019",
"key": "BOT_NOT_FOUND",
"description": "Error to be thrown when trying to get a Bot.",
"developerMessages": {
"es": "El botId no se encuentra en la base de datos o ha sido eliminado.",
"en": "The botId is not found in the database or has been deleted."
},
"clientMessages": {
"es": "El Bot no se pudo encontrar por el momento.",
"en": "The Bot could not be found at the moment."
}
}
}
```
```json theme={null}
{
"message": ["The values entered are not correct."],
"statusMessage": "failed",
"status": 0,
"error": {
"code": "E0422",
"key": "VALIDATOR_ERROR",
"description": "Error to be thrown when cannot process request because of incoming values",
"developerMessages": {
"es": "Los valores del request no son correctos para ser procesados.",
"en": "The request values are not correct for processing."
},
"clientMessages": {
"es": "Los valores ingresados no son correctos.",
"en": "The values entered are not correct."
}
},
"validationError": {
"parameters": [
{
"en": "The number of parameters is incorrect.",
"es": "El número de parámetros es incorrecto."
}
]
}
}
```
```json theme={null}
{
"message": ["We are having trouble processing your request. Please try again later."],
"statusMessage": "failed",
"status": 0,
"error": {
"code": "E0000",
"key": "UNKNOWN_ERROR",
"description": "Error to be thrown when it couldn't be determined the reason of failure",
"developerMessages": {
"es": "Error inesperado occurido, revisar logs.",
"en": "Unexpected error occurred, check logs."
},
"clientMessages": {
"es": "Estamos teniendo problemas procesando la solicitud. Por favor intenta mas tarde.",
"en": "We are having trouble processing your request. Please try again later."
}
}
}
```
***
## Ferramentas recomendadas para testes
Para facilitar os testes e o envio de requisições, recomendamos o uso de ferramentas como:
* **Postman**
* **Insomnia**
Essas ferramentas permitem que você faça requisições HTTP facilmente, teste diferentes configurações e revise as respostas da API.
***
## Perguntas frequentes
Atualmente não há um limite de caracteres definido por mensagem; no entanto, você deve estar ciente do tamanho dos arquivos que fazem parte da mensagem, como: imagem, vídeo ou documento. Estes são compartilhados via mediaUrl.
Na Jelou, temos as seguintes limitações de tamanho e formato a seguir:
* **DOCUMENT:** Até 15MB - Formato: `.pdf`
* **VIDEO:** Até 15MB - Formato: `.mp4`
* **IMAGE:** Até 5MB - Formatos: `.jpg`, `.jpeg`, `.png`
Tanto os cURLs de envio em massa quanto os 1-1 podem ser consumidos em qualquer cliente HTTPS como Insomnia ou Postman. Basta criar uma requisição HTTPS usando o cURL (apenas cole-o), depois altere os dados e execute.
Aqui está um exemplo com basic-auth:
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Accept-Language: en' \
--header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
--header 'Content-Type: application/json' \
--data '{
"destinations": ["PHONE_NUMBER"],
"parameters": [],
"elementName": "your_template_name"
}'
```
## OpenAPI
````yaml POST /v2/whatsapp/{botId}/hsm
openapi: 3.1.0
info:
title: Jelou API
description: >-
API for the Jelou platform. Send messages, manage campaigns, handle
conversations, users, databases, and widgets.
version: 1.0.0
servers:
- url: https://api.jelou.ai
description: Production server
security:
- basicAuth: []
tags:
- name: Messages
description: Send messages to users
- name: Campaigns
description: HSM campaigns and templates
- name: Conversations
description: Chat history and metrics
- name: Users
description: User state and cache management
- name: Resources
description: Media resource management
- name: Datum
description: Database CRUD operations
- name: Widget
description: Widget and room management
- name: PMA Custom
description: External support panel integration
paths:
/v2/whatsapp/{botId}/hsm:
post:
tags:
- Campaigns
summary: Send Individual HSM
description: >-
Send a WhatsApp HSM template message to one or more recipients. Supports
text, image, video, document, catalog, and carousel templates.
operationId: sendIndividualHSM
parameters:
- name: botId
in: path
required: true
description: The unique identifier of the bot
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HSMRequest'
responses:
'200':
description: HSM sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/HSMResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
schemas:
HSMRequest:
type: object
required:
- elementName
- destinations
properties:
mediaUrl:
type: string
format: uri
description: Public URL for media (required for image/video/document templates)
filename:
type: string
description: Filename for document templates
type:
type: string
enum:
- text
- hsm
- image
- document
- video
- catalog
- carousel
default: text
language:
type: string
enum:
- en
- es
- pt
elementName:
type: string
description: Approved template name
parameters:
type: array
items:
type: string
description: Template parameter values
destinations:
type: array
items:
type: string
description: Phone numbers with country code, no + sign
buttonPayloads:
type: array
items:
type: object
actions:
type: object
headerParameters:
type: array
items:
type: string
maxItems: 1
buttonParameters:
type: array
items:
$ref: '#/components/schemas/ButtonParameter'
ltoParams:
$ref: '#/components/schemas/LTOParams'
cards:
type: array
items:
$ref: '#/components/schemas/CarouselCard'
expirationTime:
type: string
description: Expiration timestamp in milliseconds
campaignId:
type: string
HSMResponse:
type: array
items:
type: object
properties:
id:
type: string
destination:
type: string
ButtonParameter:
type: object
properties:
type:
type: string
enum:
- URL
- QUICK_REPLY
- CATALOG
- COPY_CODE
payload:
type: object
param:
type: integer
LTOParams:
type: object
properties:
expirationTime:
type: integer
description: Expiration timestamp in milliseconds
CarouselCard:
type: object
properties:
mediaUrl:
type: string
format: uri
params:
type: array
items:
type: string
buttonParameters:
type: array
items:
$ref: '#/components/schemas/ButtonParameter'
Error:
type: object
properties:
message:
oneOf:
- type: string
- type: array
items:
type: string
statusMessage:
type: string
status:
type: integer
error:
type: object
properties:
code:
type: string
key:
type: string
description:
type: string
developerMessages:
type: object
clientMessages:
type: object
validationError:
type: object
responses:
BadRequest:
description: Bad request - Invalid format or missing required fields
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized - Invalid authentication credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Not found - Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
UnprocessableEntity:
description: Unprocessable entity - Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Basic authentication using Base64 encoded clientId:clientSecret
````