Skip to main content

​
Enviar mensajes usando plantillas HSM

Usa plantillas de mensajes (HSM) en WhatsApp para enviar contenido estructurado, personalizado y aprobado, ideal para mensajes masivos y automáticos desde tu bot en Jelou.
Las plantillas (HSM) son mensajes preaprobados por WhatsApp, lo que te permite enviar notificaciones proactivas a usuarios sin restricciones de sesión.

​
Prerrequisitos

  • Debes tener la plantilla aprobada y activada en Jelou.
  • Conocer los parámetros dinámicos requeridos por la plantilla.
  • Contar con tu botId y las credenciales de API configuradas.
  • Saber el userId del destinatario de la notificación.

​
Endpoint

POST https://api.jelou.ai/v1/bots/{botId}/messages

​
Autenticación

​
Authorization
string
required
Cabecera de autenticación en formato Basic <base64(clientId:clientSecret)>.

​
Parámetros de Ruta

​
botId
string
required
Identificador único de tu bot configurado en Jelou.

​
Cuerpo de la solicitud

​
type
string
required
Debe ser “template”. Indica que enviarás un mensaje usando plantilla.
​
templateId
string
required
Identificador de la plantilla HSM que desees utilizar (debe estar previamente aprobada).
​
userId
string
required
Identificador único del usuario receptor del mensaje.
​
parameters
object
Objeto {"variable1": "valor1", ...} con valores para los campos.
​
botId
string
Opcional. Inclúyelo solo si deseas sobreescribir el bot especificado en la ruta (debe coincidir).

​
Ejemplo de solicitud

cURL
curl --request POST \
  --url https://api.jelou.ai/v1/bots/BOT_ID/messages \
  --header 'Authorization: Basic <Base64Encoded clientId:clientSecret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "template",
    "templateId": "tpl_promocion_2024",
    "userId": "user_abc123",
    "parameters": {
      "nombre": "Carlos",
      "descuento": "25%"
    }
  }'

​
Campos de respuesta

​
success
boolean
Indica si el mensaje fue enviado correctamente.
​
messageId
string
Identificador único del mensaje enviado. Úsalo para realizar seguimiento.

​
Ejemplo de respuesta exitosa

Success
{
  "success": true,
  "messageId": "msg_654321123"
}

​
Manejo de errores

​
error
string
Código del error encontrado durante el envío.
​
message
string
Descripción breve y legible del error.

​
Códigos de error comunes

  • INVALID_TEMPLATE — La plantilla indicada no existe, no fue aprobada, o está inactiva.
  • INVALID_PARAMETERS — Hay un desajuste en los parámetros que espera la plantilla.
  • BOT_NOT_FOUND — El identificador de bot no existe en tu cuenta.
  • USER_NOT_FOUND — El usuario receptor no se encuentra registrado.
  • UNAUTHORIZED — Las credenciales de acceso no son válidas.
Verifica que los parámetros enviados coincidan en nombre y cantidad con lo que espera la plantilla aprobada.

​
Pasos para crear y gestionar plantillas

1

Accede al módulo de Plantillas en Jelou

Ve al menú lateral y haz clic en Plantillaspara ver, crear o editar tus plantillas HSM.
2

Solicita la aprobación de una nueva plantilla

Sigue el formulario para describir la plantilla y sus variables dinámicas. Envía tu solicitud para que WhatsApp la apruebe.
La aprobación suele demorar entre minutos y 24 horas, según los lineamientos de WhatsApp.
3

Obtén el ID de la plantilla aprobada

Copia el templateIdque aparece en el listado. Lo necesitarás al enviar mensajes.
4

Envía mensajes usando la API y el <code>templateId</code>

Sigue el ejemplo de llamado al endpoint presentado más arriba.
Si el mensaje es enviado exitosamente, recibirás un messageIdúnico en la respuesta.

​
Casos de uso recomendados

  • Notificaciones y recordatorios proactivos (citas, pagos, promociones).
  • Confirmaciones automáticas de reservas, pedidos o registros.
  • Mensajes de bienvenida personalizados al adquirir un servicio.
  • Informar de actualizaciones o cambios importantes.
Aprovecha las plantillas para automatizar procesos recurrentes y asegurar que tus mensajes cumplan con los lineamientos de WhatsApp.