> ## 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.
# Envío individual (1-1)
> Envía mensajes HSM personalizados a destinatarios individuales usando la API de WhatsApp
WhatsApp API permite a las compañías automatizar y personalizar la comunicación con sus clientes, facilitando interacciones eficientes, escalables y enriquecidas con contenido multimedia. Es ideal para gestionar consultas, enviar notificaciones y ofrecer respuestas inmediatas a través de AI Agents.
***
## Configuración del envío de mensajes
### Paso 1: Definir el Endpoint
Para enviar mensajes, debes utilizar el siguiente endpoint de la API:
```
POST https://api.jelou.ai/v2/whatsapp/{botId}/hsm
```
### Paso 2: Parámetros de la solicitud
Los parámetros clave para la solicitud incluyen:
* **Texto**: El contenido del mensaje.
* **Tipo de mensaje (`type`)**: Define el tipo de plantilla que se va a enviar.
* **Propiedad de plantilla**: Plantilla previamente creada y aprobada por META.
* **Archivo multimedia**: Si la plantilla requiere alguna URL (imagen, documento, etc.).
* **Bot ID**: Identificador único del bot.
* **Parámetros**: Datos específicos para cada envío (nombre, número de pedido, etc.).
### Paso 3: Enviar la solicitud
Envía el mensaje usando el método **POST**. Al completar el envío, recibirás una respuesta que te permitirá verificar el estado de la entrega.
Asegúrate de cumplir con las políticas de WhatsApp para evitar restricciones.
***
## Restricciones de contenido
Recuerda que, para enviar mensajes a través de WhatsApp, debes usar plantillas previamente aprobadas por META.
Cada plantilla tiene limitaciones específicas según su formato y contenido, como la longitud del mensaje o el tipo de información permitida. Asegúrate de revisar estas restricciones antes de utilizarlas para garantizar su correcto envío.
**Considera que**:
* No se permiten URLs, emojis ni archivos multimedia dentro de los mensajes de autenticación.
* Los parámetros deben tener un máximo de 15 caracteres.
***
## Request Body
| Propiedad | Tipo | Descripción | Obligatorio |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------------------- | ----------- |
| **mediaUrl** | string | URL pública del archivo multimedia. Obligatoria si tu plantilla es de tipo video, imagen o documento. | Condicional |
| **filename** | string | Nombre del archivo para plantillas de tipo documento. | Condicional |
| **type** | string | Tipo de mensaje: `text`, `hsm`, `image`, `document`, `video`, `catalog`, `carousel`. Por defecto es `text`. | No |
| **language** | string | Idioma de la plantilla: `en`, `es`, `pt` | No |
| **elementName** | string | Nombre de la plantilla aprobada. | Sí |
| **parameters** | array | Conjunto de strings que reemplazan valores en la plantilla. | Sí |
| **destinations** | array | Lista de números de teléfono. Formato numérico con código de país, sin `+` ni espacios. | Sí |
| **buttonPayloads** | array | Información para los botones de respuesta rápida. | No |
| **actions** | object | Configuración y acciones de la plantilla en formato payload. | No |
| **headerParameters** | array | Parámetro del encabezado, máximo 1 parámetro. | No |
| **thumbnailProduct** | string | URL de imagen en miniatura. Obligatoria para plantillas de catálogo. | Condicional |
| **expirationTime** | string | Tiempo de expiración en formato timestamp (milisegundos). | No |
| **campaignId** | string | Identificador único de la campaña asociada. | No |
| **buttonParameters** | array | Configuración de todos los tipos de botones. | No |
| **ltoParams** | object | Parámetros de tiempo limitado (LTO). | No |
| **cards** | array | Tarjetas de contenido para plantillas de carrusel. | No |
***
## Tipos de plantillas
En esta sección, compartimos ejemplos de solicitudes para los diferentes tipos de plantillas. Estos ejemplos proporcionan una guía clara para que puedas sustituir fácilmente los valores con tus propios datos.
Si el nombre de una plantilla o un botón dentro del JSON es distinto a la plantilla ya aprobada, incluso por una tilde, el envío fallará. **La precisión es clave para garantizar la funcionalidad.**
```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.ejemplo.com/imagen.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.ejemplo.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.ejemplo.com/documento.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: es' \
--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": "es",
"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.ejemplo.com/imagen.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.ejemplo.com/producto1.jpg",
"params": ["VALOR_PARAMETRO"],
"buttonParameters": [
{
"type": "QUICK_REPLY",
"payload": {"action": "Boton 1", "type": "edge", "skillId": "45515", "cardIndex": 0}
}
]
},
{
"mediaUrl": "https://cdn.ejemplo.com/producto2.jpg",
"params": ["VALOR_PARAMETRO_1", "VALOR_PARAMETRO_2"],
"buttonParameters": [
{
"type": "QUICK_REPLY",
"payload": {"action": "Boton 2", "type": "edge", "skillId": "10192", "cardIndex": 1}
}
]
}
]
}'
```
***
## Casos de uso comunes
### 1. Mensajes personalizados
Usa plantillas con variables para enviar mensajes adaptados a las necesidades de cada usuario (por ejemplo, recordatorios de pagos o actualizaciones de pedidos).
### 2. Automatización con Webhooks
Interacciones personalizadas según las respuestas de los usuarios, permitiendo una conversación más dinámica y eficiente.
**Ejemplos de campañas**:
* **Promociones personalizadas**: Ofertas exclusivas según preferencias del cliente.
* **Recordatorios de pagos**: Notificaciones automáticas para vencimientos de facturas.
* **Cotizaciones de servicios**: Consultas rápidas sobre seguros, préstamos, etc.
***
## Configuración avanzada
### Número telefónico
Al ser un envío individual, el número de teléfono a quien le llegará el mensaje deberá estar en el formato correcto para que el envío sea exitoso.
Se debe omitir el signo `+`, incluir el código de país, solo pueden ingresar caracteres numéricos. Los guiones o espacios no son aceptados.
**Para usuarios de Ecuador:** Se debe omitir el signo "+" y el primer 0 del número telefónico para poder ser ingresado de manera correcta.
| ✅ Forma correcta | ❌ Forma incorrecta | ❌ Forma incorrecta |
| :--------------: | :----------------: | :----------------: |
| PHONE\_NUMBER | +PHONE\_NUMBER | 09XXXXXXXX |
### Parámetros específicos
Dependiendo de la campaña, puedes usar datos personalizados como el tipo de mensaje o información adicional de los clientes.
***
## Personalización de mensajes
### Vinculación con Workflows
Cada mensaje puede estar asociado a un flujo específico que define cómo se debe manejar la respuesta del usuario. Esto es útil para crear interacciones más complejas y dirigidas, como menús interactivos o encuestas.
### Configuración de botones
Puedes usar la siguiente estructura en el campo `buttonPayloads` cuando tu plantilla incluya botones de respuesta rápida usando workflows; esto te permitirá activar workflows adicionales dentro de la conversación según la acción seleccionada por el usuario.
```json theme={null}
[
{"type": "edge", "action": "Yes", "skillId": "1"},
{"type": "edge", "action": "Reschedule", "skillId": "2"},
{"type": "edge", "action": "Cancel", "skillId": "3"}
]
```
En este caso, cada botón debe tener las claves `type`, `action` y `skillId`. La clave `action` define el texto que aparecerá en el botón, mientras que `skillId` indica el ID del flujo que el botón activará.
Para obtener el `skillId` de un workflow, pasa el cursor sobre el nombre del workflow en Brain Studio. Se mostrará un tooltip con el ID correspondiente.
Redirigen a los usuarios a workflows específicos según su elección o interacción.
Las plantillas permiten las siguientes configuraciones:
```json theme={null}
{
"actions": {
"setSkill": {"id": 2222}
}
}
```
Para obtener el `skillId` del workflow, pasa el cursor sobre el nombre del workflow en Brain Studio. Se mostrará un tooltip con el ID correspondiente.
```json theme={null}
{
"actions": {
"setMemoryParams": {
"url": "https://apps.jelou.ai"
}
}
}
```
### Parámetros Cache
Esta función se utiliza para guardar información adicional en la caché para utilizarla posteriormente. Dependerá de la configuración deseada para la plantilla. Si se envía una URL, puede ser utilizada por un flujo para redirigir esa URL con fines de marketing.
Todos los parámetros a almacenar en caché deben ir en `setMemoryParams` con sus respectivos campos clave-valor.
Esta configuración será válida durante 3 meses.
```json theme={null}
{
"actions": {
"setMemoryParams": {
"url": "https://apps.jelou.ai"
}
}
}
```
***
## Respuestas de la 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": "es",
"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": ["Los valores ingresados no son correctos."],
"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."
}
}
}
```
***
## Herramientas recomendadas para pruebas
Para facilitar las pruebas y envío de solicitudes, te recomendamos usar herramientas como:
* **Postman**
* **Insomnia**
Estas herramientas permiten realizar solicitudes HTTP de manera sencilla, probar diferentes configuraciones y revisar las respuestas de la API.
***
## Preguntas frecuentes
No existe un límite actual definido para el número de caracteres por mensaje; sin embargo hay que estar pendientes sobre el tamaño de los archivos que forman parte del mensaje; tales como: imagen, video o documento. Estos se comparten en mediaUrl.
En Jelou, tenemos las siguientes limitaciones de tamaño y formato a seguir:
* **DOCUMENTO:** Hasta 15MB - Formato: `.pdf`
* **VIDEO:** Hasta 15MB - Formato: `.mp4`
* **IMAGEN:** Hasta 5MB - Formatos: `.jpg`, `.jpeg`, `.png`
Los cURLs tanto de envío masivo como de envío 1-1 pueden ser consumidos en cualquier cliente HTTPS como Insomnia o Postman. Basta con crear una petición HTTPS a través del cURL (simplemente pegándolo), luego cambiamos los datos y ejecutamos.
Este es un ejemplo con basic-auth:
```bash theme={null}
curl --request POST \
--url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
--header 'Accept-Language: es' \
--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
````