Skip to main content
Utiliza esta función para enviar plantillas de forma masiva a tus clientes. La API se encargará de la entrega a los destinatarios desde un archivo basado en columnas. Enviar plantillas de forma masiva te permite enviar una plantilla predefinida con diferentes valores relacionados con cada cliente, de manera que puedas seleccionar información dinámica desde una fuente como un archivo, para automatizar y enviar tu campaña fácilmente.

​
Directrices para las plantillas

El archivo fuente debe ser creado siguiendo las siguientes especificaciones:

​
Formato de archivo

Solo se admiten archivos con la extensión .CSV.

​
Encabezado

La primera fila del archivo debe definir los nombres de las columnas (encabezado). Sigue estas reglas para el encabezado:
  • Evita los espacios en blanco en los nombres de las columnas.
  • No uses caracteres especiales ni signos de puntuación (por ejemplo, !, $, %, &, *, etc.).
  • Usa solo letras, números y guiones bajos (_) si es necesario.
Correcto: phone_number, customer_name, order_amount Incorrecto: phone number, customer-name!, order#amount

​
Primera columna

La primera columna debe contener los números de teléfono de los destinatarios. Es obligatorio incluir el código internacional sin el símbolo + (por ejemplo, para un número en Ecuador, escribe PHONE_NUMBER).

​
Columnas restantes

Las otras columnas se usarán para los valores dinámicos de los parámetros (personalización de la plantilla).

​
Ejemplo

Si tu plantilla contiene el siguiente contenido: 
Tu pedido {{1}} por un total de {{2}} está confirmado. La entrega esperada es {{3}}.
El archivo CSV sería:
phone_numberparam_1param_2param_3
PHONE_NUMBERA12345$250.001 de diciembre
PHONE_NUMBER_2B67890$100.502 de diciembre
PHONE_NUMBER_3C22345$50.003 de diciembre
El archivo CSV debe estar codificado en UTF-8.

​
Enviar HSM desde archivo

POST https://api.jelou.ai/v1/hsm/file

​
Opciones de carga de archivo

Existen dos formas de proporcionar el archivo CSV con la información de los destinatarios:
  1. Usando una URL pública: Puedes proporcionar la URL al archivo CSV que esté disponible públicamente. En este caso, el cuerpo de la solicitud debe estar en formato JSON.
  2. Subiendo el archivo: Alternativamente, puedes adjuntar el archivo CSV directamente a la solicitud. En este caso, el cuerpo de la solicitud debe estar en formato multipart/form-data.

​
Parámetros del cuerpo

PropiedadTipoDescripciónRequerido
campaignNamestringNombre asignado a la campaña que se está enviando.Sí
elementNamestringNombre de la plantilla. Debe tener estado aprobado por WhatsApp.Sí
botIdstringIdentificador único del bot que envía la plantilla.Sí
paramsarrayArreglo de objetos con el número de parámetro y la columna correspondiente del CSV. Si la plantilla no tiene parámetros, el arreglo debe estar vacío.Sí
typestringTipo de plantilla: text, image, document, video. Por defecto es text.No
mediaUrlstringURL pública del archivo multimedia. Necesario para plantillas de imagen, video o documento.Condicional
fileUrlstringURL pública del archivo CSV. Requerido si no se sube el archivo directamente.Condicional
filefileArchivo CSV adjunto. Requerido si no se usa fileUrl.Condicional
buttonPayloadsarrayArreglo de objetos para botones de respuesta rápida con skills.No
actionsobjectAcciones relacionadas con la plantilla.No
scheduledAtdateFecha y hora en UTC cuando se enviará la campaña.No

​
Ejemplos de solicitud

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "campaign_name",
    "botId": "BOT_ID",
    "elementName": "ELEMENT_NAME",
    "params": [
      {"param": 1, "column": "customer_name"}
    ],
    "mediaUrl": "https://cdn.ejemplo.com/imagen.png",
    "type": "image",
    "fileUrl": "https://cdn.ejemplo.com/campana.csv",
    "buttonPayloads": [
      {"type": "edge", "action": "Yes", "skillId": "1"}
    ]
  }'

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --form campaignName=campaign_name \
  --form botId=BOT_ID \
  --form elementName=ELEMENT_NAME \
  --form 'buttonPayloads=[{"type":"edge","action":"Yes","skillId":"1"},{"type":"edge","action":"Reschedule","skillId":"2"},{"type":"edge","action":"Cancel","skillId":"3"}]' \
  --form file=@/ruta/local/campana.csv \
  --form 'params=[]'

​
Respuestas del envío

{
  "message": ["Campaign has been created."],
  "status": "success"
}

{
  "message": ["Invalid CSV format"],
  "status": "failed"
}

{
  "message": "Authentication failed"
}

{
  "message": ["Template not found or not approved"],
  "status": "failed"
}

​
Estructura de params

Cada elemento en el arreglo params es un objeto que contiene: 
[
  {"param": 1, "column": "customer_name"},
  {"param": 2, "column": "order_amount"}
]
  • param: Número del parámetro en la plantilla (1, 2, 3…).
  • column: Nombre de la columna en el archivo CSV de donde se extraerán los valores.

​
Estructura de buttonPayloads

Para plantillas con botones de respuesta rápida que activan skills: 
[
  {"type": "edge", "action": "Yes", "skillId": "1"},
  {"type": "edge", "action": "Reschedule", "skillId": "2"},
  {"type": "edge", "action": "Cancel", "skillId": "3"}
]

​
Obtener Campañas

Consulta la información de todas las campañas que se han enviado de manera masiva. 
GET https://api.jelou.ai/v1/campaigns

​
Parámetros de consulta

PropiedadTipoDescripciónRequerido
pagenumberNúmero de página. Por defecto 1.No
limitnumberNúmero de registros. Por defecto 10, máximo 50.No
botIdstringID del bot.Sí
startAtdateFecha de inicio.Sí
endAtdateFecha de finalización.Sí
elementNamestringNombre de la plantilla.No
statusstringEstado de la campaña. Valores: COMPLETED, PENDING, IN_PROGRESS, SCHEDULEDNo

​
Ejemplo de solicitud

curl --request GET \
  --url 'https://api.jelou.ai/v1/campaigns?page=1&limit=20&botId=BOT_ID&startAt=2024-01-01&endAt=2024-12-31' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}'

​
Respuestas de consulta

{
  "message": ["Campaigns retrieved successfully"],
  "status": "success",
  "data": {
    "results": [
      {
        "id": "campaign_123",
        "name": "Promoción Navidad",
        "elementName": "promo_navidad",
        "botId": "BOT_ID",
        "status": "COMPLETED",
        "totalMessages": 1500,
        "deliveredMessages": 1485,
        "failedMessages": 15,
        "createdAt": "2024-12-01T10:00:00.000Z",
        "completedAt": "2024-12-01T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45
    }
  }
}

{
  "message": ["Missing required parameters"],
  "status": "failed"
}

{
  "message": "Authentication failed"
}

​
Estados de campaña

EstadoDescripción
PENDINGLa campaña está pendiente de envío.
SCHEDULEDLa campaña está programada para una fecha futura.
IN_PROGRESSLa campaña se está enviando actualmente.
COMPLETEDLa campaña ha finalizado su envío.