Envío individual (1-1) - Jelou AI Docs

Send Individual HSM

curl --request POST \
  --url https://api.jelou.ai/v2/whatsapp/{botId}/hsm \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "elementName": "<string>",
  "destinations": [
    "<string>"
  ],
  "mediaUrl": "<string>",
  "filename": "<string>",
  "type": "text",
  "parameters": [
    "<string>"
  ],
  "buttonPayloads": [
    {}
  ],
  "actions": {},
  "headerParameters": [
    "<string>"
  ],
  "buttonParameters": [
    {
      "payload": {},
      "param": 123
    }
  ],
  "ltoParams": {
    "expirationTime": 123
  },
  "cards": [
    {
      "mediaUrl": "<string>",
      "params": [
        "<string>"
      ],
      "buttonParameters": [
        {
          "payload": {},
          "param": 123
        }
      ]
    }
  ],
  "expirationTime": "<string>",
  "campaignId": "<string>"
}
'

[
  {
    "id": "<string>",
    "destination": "<string>"
  }
]

POST

{botId}

hsm

Send Individual HSM

curl --request POST \
  --url https://api.jelou.ai/v2/whatsapp/{botId}/hsm \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "elementName": "<string>",
  "destinations": [
    "<string>"
  ],
  "mediaUrl": "<string>",
  "filename": "<string>",
  "type": "text",
  "parameters": [
    "<string>"
  ],
  "buttonPayloads": [
    {}
  ],
  "actions": {},
  "headerParameters": [
    "<string>"
  ],
  "buttonParameters": [
    {
      "payload": {},
      "param": 123
    }
  ],
  "ltoParams": {
    "expirationTime": 123
  },
  "cards": [
    {
      "mediaUrl": "<string>",
      "params": [
        "<string>"
      ],
      "buttonParameters": [
        {
          "payload": {},
          "param": 123
        }
      ]
    }
  ],
  "expirationTime": "<string>",
  "campaignId": "<string>"
}
'

[
  {
    "id": "<string>",
    "destination": "<string>"
  }
]

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.

Mensaje de texto

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"
  }'

Mensaje con imagen

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"
  }'

Mensaje con video

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"
  }'

Mensaje con documento adjunto

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"
  }'

Mensaje de texto con botones de acción de URL estática

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"
  }'

Mensaje de texto con botones de acción de URL dinámica

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"}
      }
    ]
  }'

Mensaje de texto con botones de Quick Reply

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"}
      }
    ]
  }'

Mensaje de texto personalizado con parámetros en el encabezado

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"]
  }'

Catálogo completo

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"}
      }
    ]
  }'

LTO con botón de copiar código

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"}
      }
    ]
  }'

Autenticación

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"
  }'

Carrusel con 2 tarjetas

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

Button Payload

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.

[
  {"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á.

Actions Payload

Redirigen a los usuarios a workflows específicos según su elección o interacción.Las plantillas permiten las siguientes configuraciones:

{
  "actions": {
    "setSkill": {"id": 2222}
  }
}

{
  "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.

{
  "actions": {
    "setMemoryParams": {
      "url": "https://apps.jelou.ai"
    }
  }
}

Respuestas de la API

200 - Respuesta exitosa

[
  {
    "id": "msg-12345-67890-abcde-fghij-klmno",
    "destination": "PHONE_NUMBER"
  }
]

400 - Bad Request

{
  "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": {}
}

401 - Unauthorized

{
  "message": "Authentication failed"
}

404 - Not Found

{
  "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."
    }
  }
}

422 - Unprocessable Entity

{
  "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."
      }
    ]
  }
}

500 - Internal Server Error

{
  "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

¿Cuántos caracteres están permitidos?

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

¿Cómo se consume la API?

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:

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"
  }'

Autorizaciones

Authorization

string

header

requerido

Basic authentication using Base64 encoded clientId:clientSecret

Parámetros de ruta

botId

string

requerido

The unique identifier of the bot

Cuerpo

application/json

elementName

string

requerido

Approved template name

destinations

string[]

requerido

Phone numbers with country code, no + sign

mediaUrl

string<uri>

Public URL for media (required for image/video/document templates)

filename

string

Filename for document templates

type

enum<string>

predeterminado:text

Opciones disponibles:

text,

hsm,

image,

document,

video,

catalog,

carousel

language

enum<string>

Opciones disponibles:

en,

es,

pt

parameters

string[]

Template parameter values

buttonPayloads

object[]

actions

object

headerParameters

string[]

Maximum array length: 1

buttonParameters

object[]

Show child attributes

ltoParams

object

Show child attributes

cards

object[]

Show child attributes

expirationTime

string

Expiration timestamp in milliseconds

campaignId

string

Respuesta

HSM sent successfully

string

destination

string

Crear Plantilla

Envío masivo

⌘I

​Configuración del envío de mensajes

​Paso 1: Definir el Endpoint

​Paso 2: Parámetros de la solicitud

​Paso 3: Enviar la solicitud

​Restricciones de contenido

​Request Body

​Tipos de plantillas

​Casos de uso comunes

​1. Mensajes personalizados

​2. Automatización con Webhooks

​Configuración avanzada

​Número telefónico

​Parámetros específicos

​Personalización de mensajes

​Vinculación con Workflows

​Configuración de botones

​Parámetros Cache

​Respuestas de la API

​Herramientas recomendadas para pruebas

​Preguntas frecuentes

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Configuración del envío de mensajes

Paso 1: Definir el Endpoint

Paso 2: Parámetros de la solicitud

Paso 3: Enviar la solicitud

Restricciones de contenido

Request Body

Tipos de plantillas

Casos de uso comunes

1. Mensajes personalizados

2. Automatización con Webhooks

Configuración avanzada

Número telefónico

Parámetros específicos

Personalización de mensajes

Vinculación con Workflows

Configuración de botones

Parámetros Cache

Respuestas de la API

Herramientas recomendadas para pruebas

Preguntas frecuentes