Envío masivo

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 el identificador de cada destinatario: un número de teléfono o un BSUID. Para números de teléfono, es obligatorio incluir el código internacional sin el símbolo + (por ejemplo, para un número en Ecuador, escribe PHONE_NUMBER).

Para el envío de plantillas de categoría AUTHENTICATION (OTP) no se puede utilizar BSUID; ese destinatario debe ir como número de teléfono. Si una fila con BSUID apunta a una plantilla AUTHENTICATION, esa fila se omite del envío sin afectar al resto del archivo.

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_number	param_1	param_2	param_3
PHONE_NUMBER	A12345	$250.00	1 de diciembre
PHONE_NUMBER_2	B67890	$100.50	2 de diciembre
PHONE_NUMBER_3	C22345	$50.00	3 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:

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

Propiedad	Tipo	Descripción	Requerido
campaignName	string	Nombre asignado a la campaña que se está enviando.	Sí
elementName	string	Nombre de la plantilla. Debe tener estado aprobado por WhatsApp.	Sí
botId	string	Identificador único del canal que envía la plantilla.	Sí
params	array	Arreglo 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í
type	string	Tipo de plantilla: `hsm` (solo texto), `image`, `video`, `document` o `carousel`. Si lo omites, se envía como plantilla de texto.	No
language	string	Código de idioma de la plantilla, por ejemplo `es`, `en` o `pt_BR`.	No
mediaUrl	string	URL pública del archivo multimedia del encabezado. Necesario para plantillas de imagen, video o documento.	Condicional
fileUrl	string	URL pública del archivo CSV. Requerido si no se sube el archivo directamente.	Condicional
file	file	Archivo CSV adjunto. Requerido si no se usa `fileUrl`.	Condicional
headerParameters	array	Parámetro variable del encabezado de texto, tomado de una columna del CSV. Máximo 1 parámetro.	No
buttonParameters	array	Configuración de los botones de la plantilla: respuesta rápida (`QUICK_REPLY`) o URL dinámica (`URL`).	No
cards	array	Tarjetas del carrusel. Requerido cuando `type` es `carousel`.	Condicional
actions	object	Acciones que se ejecutan cuando el destinatario responde: workflow de destino, memoria y CRM.	No
date	string	Fecha y hora en UTC (ISO 8601) en la que se enviará la campaña. Si lo omites, la campaña se envía de inmediato.	No

Ejemplos de solicitud

Por método de carga del archivo

Envío desde URL pública (JSON)

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",
    "buttonParameters": [
      {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Yes", "skillId": "1"}}
    ]
  }'

Envío con archivo adjunto (multipart/form-data)

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 'buttonParameters=[{"type":"QUICK_REPLY","payload":{"type":"edge","action":"Yes","skillId":"1"}},{"type":"QUICK_REPLY","payload":{"type":"edge","action":"Reschedule","skillId":"2"}},{"type":"QUICK_REPLY","payload":{"type":"edge","action":"Cancel","skillId":"3"}}]' \
  --form file=@/ruta/local/campana.csv \
  --form 'params=[]'

Por tipo de plantilla

Cada ejemplo usa un archivo CSV publicado en fileUrl cuyas columnas coinciden con las indicadas en params.

Texto

Plantilla: Hola {{1}}, tu pedido {{2}} ya está en camino.

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "pedidos_en_camino",
    "botId": "BOT_ID",
    "elementName": "pedido_en_camino",
    "language": "es",
    "type": "hsm",
    "params": [
      {"param": 1, "column": "nombre"},
      {"param": 2, "column": "numero_pedido"}
    ],
    "fileUrl": "https://cdn.ejemplo.com/campanas/pedidos.csv"
  }'

Imagen

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "promo_fin_de_mes",
    "botId": "BOT_ID",
    "elementName": "promo_fin_de_mes",
    "language": "es",
    "type": "image",
    "params": [
      {"param": 1, "column": "nombre"}
    ],
    "mediaUrl": "https://cdn.ejemplo.com/media/promo-fin-de-mes.jpg",
    "fileUrl": "https://cdn.ejemplo.com/campanas/clientes-promo.csv"
  }'

Video

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "lanzamiento_app",
    "botId": "BOT_ID",
    "elementName": "lanzamiento_app_video",
    "language": "es",
    "type": "video",
    "params": [],
    "mediaUrl": "https://cdn.ejemplo.com/media/lanzamiento-app.mp4",
    "fileUrl": "https://cdn.ejemplo.com/campanas/usuarios-app.csv"
  }'

Documento

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "estado_de_cuenta_septiembre",
    "botId": "BOT_ID",
    "elementName": "estado_de_cuenta",
    "language": "es",
    "type": "document",
    "params": [
      {"param": 1, "column": "nombre"},
      {"param": 2, "column": "producto"}
    ],
    "mediaUrl": "https://cdn.ejemplo.com/media/estado-de-cuenta.pdf",
    "fileUrl": "https://cdn.ejemplo.com/campanas/estados-de-cuenta.csv"
  }'

Carrusel

Cada tarjeta define su propio recurso de media en mediaUrl y sus botones en buttonParameters. El campo cardIndex indica a qué tarjeta pertenece cada botón, empezando en 0.

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "catalogo_temporada",
    "botId": "BOT_ID",
    "elementName": "catalogo_temporada",
    "language": "es",
    "type": "carousel",
    "params": [],
    "fileUrl": "https://cdn.ejemplo.com/campanas/clientes-catalogo.csv",
    "cards": [
      {
        "mediaUrl": "https://cdn.ejemplo.com/media/producto-1.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Ver producto 1", "skillId": "1", "cardIndex": 0}}
        ]
      },
      {
        "mediaUrl": "https://cdn.ejemplo.com/media/producto-2.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Ver producto 2", "skillId": "2", "cardIndex": 1}}
        ]
      },
      {
        "mediaUrl": "https://cdn.ejemplo.com/media/producto-3.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Ver producto 3", "skillId": "3", "cardIndex": 2}}
        ]
      }
    ]
  }'

Por escenario

Estos ejemplos muestran el cuerpo JSON de la solicitud. Envíalo al mismo endpoint con el encabezado Content-Type: application/json.

Botones de respuesta rápida que activan un workflow

Cada botón con payload.type igual a edge lleva al destinatario al workflow indicado en skillId. El texto de action debe coincidir con el texto del botón en la plantilla.

{
  "campaignName": "confirmacion_citas",
  "botId": "BOT_ID",
  "elementName": "confirmar_cita",
  "language": "es",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "nombre"},
    {"param": 2, "column": "fecha_cita"}
  ],
  "fileUrl": "https://cdn.ejemplo.com/campanas/citas.csv",
  "buttonParameters": [
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Confirmar", "skillId": "1"}},
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Reagendar", "skillId": "2"}},
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Cancelar", "skillId": "3"}}
  ]
}

Botón de URL dinámica

El sufijo de la URL se toma de la columna del CSV indicada en payload.param. Por ejemplo, si la plantilla define la URL https://tramites.ejemplo.com/{{1}}, cada destinatario recibe su propio enlace.

{
  "campaignName": "seguimiento_tramites",
  "botId": "BOT_ID",
  "elementName": "seguimiento_tramite",
  "language": "es",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "nombre"},
    {"param": 2, "column": "numero_tramite"}
  ],
  "fileUrl": "https://cdn.ejemplo.com/campanas/tramites.csv",
  "buttonParameters": [
    {"type": "URL", "param": 1, "payload": {"param": "url_tramite"}}
  ]
}

Parámetro en el encabezado

Para plantillas con una variable en el encabezado de texto, indica la columna del CSV en headerParameters.

{
  "campaignName": "bienvenida_clientes",
  "botId": "BOT_ID",
  "elementName": "bienvenida_personalizada",
  "language": "es",
  "type": "hsm",
  "headerParameters": [
    {"param": "1", "column": "nombre"}
  ],
  "params": [
    {"param": 1, "column": "codigo_cliente"}
  ],
  "fileUrl": "https://cdn.ejemplo.com/campanas/nuevos-clientes.csv"
}

Dirigir la respuesta a un workflow

Con actions.setSkill, la respuesta del destinatario se deriva al workflow indicado.

{
  "campaignName": "recordatorio_pago",
  "botId": "BOT_ID",
  "elementName": "recordatorio_pago",
  "language": "es",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "nombre"},
    {"param": 2, "column": "monto"},
    {"param": 3, "column": "fecha_vencimiento"}
  ],
  "fileUrl": "https://cdn.ejemplo.com/campanas/pagos-pendientes.csv",
  "actions": {
    "setSkill": {"id": 5001}
  }
}

Guardar datos del CSV en memoria y CRM

Usa {nombre_columna} como valor para tomar el dato de esa columna del CSV. setMemoryParams guarda los valores en la memoria del usuario, y crmParams los guarda en los campos del CRM.

{
  "campaignName": "renovacion_seguros",
  "botId": "BOT_ID",
  "elementName": "renovacion_poliza",
  "language": "es",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "nombre"},
    {"param": 2, "column": "producto"}
  ],
  "fileUrl": "https://cdn.ejemplo.com/campanas/renovaciones.csv",
  "actions": {
    "setMemoryParams": {
      "nombre_cliente": "{nombre}",
      "producto": "{producto}"
    },
    "crmParams": {
      "nombre": "{nombre}",
      "ciudad": "{ciudad}"
    }
  }
}

Envío programado

Con date programas la campaña para una fecha y hora en UTC.

{
  "campaignName": "black_friday",
  "botId": "BOT_ID",
  "elementName": "black_friday_2026",
  "language": "es",
  "type": "image",
  "params": [
    {"param": 1, "column": "nombre"}
  ],
  "mediaUrl": "https://cdn.ejemplo.com/media/black-friday.jpg",
  "fileUrl": "https://cdn.ejemplo.com/campanas/clientes-black-friday.csv",
  "date": "2026-11-27T14:00:00Z"
}

Respuestas del envío

200 - Respuesta exitosa

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

400 - Bad Request

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

401 - Unauthorized

{
  "message": "Authentication failed"
}

422 - Unprocessable Entity

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

headerParameters usa la misma estructura, pero admite un solo elemento.

Estructura de buttonParameters

Cada elemento del arreglo configura un botón de la plantilla. Respuesta rápida (QUICK_REPLY):

[
  {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Confirmar", "skillId": "1"}},
  {"type": "QUICK_REPLY", "payload": {"type": "flow", "action": "Ver oferta", "flowId": "2"}}
]

payload.type: Destino del botón. edge activa un workflow y flow activa un flow.
payload.action: Texto del botón. Debe coincidir con el texto definido en la plantilla.
payload.skillId: ID del workflow que se activa. Requerido cuando payload.type es edge.
payload.flowId: ID del flow que se activa. Requerido cuando payload.type es flow.
payload.cardIndex: Posición de la tarjeta a la que pertenece el botón, empezando en 0. Solo para carruseles.

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.

URL dinámica (URL):

[
  {"type": "URL", "param": 1, "payload": {"param": "url_tramite"}}
]

param: Número del parámetro de la URL en la plantilla.
payload.param: Columna del CSV con el valor que completa la URL.

Estructura de cards

Cada tarjeta del carrusel es un objeto con:

mediaUrl: URL pública de la imagen o el video de la tarjeta.
params: Parámetros del cuerpo de la tarjeta, con la misma estructura que params. Usa un arreglo vacío si la tarjeta no tiene parámetros.
buttonParameters: Botones de la tarjeta. Cada payload debe incluir cardIndex.

Estructura de actions

Propiedad	Descripción	Ejemplo
setSkill	Workflow que atiende la respuesta del destinatario.	`{"id": 1}`
setMemoryParams	Valores que se guardan en la memoria del usuario. Usa `{columna}` para tomar el valor del CSV.	`{"producto": "{producto}"}`
crmParams	Valores que se guardan en los campos del CRM. Usa `{columna}` para tomar el valor del CSV.	`{"ciudad": "{ciudad}"}`

API reference

Envío de mensajes

Campañas

Conversaciones

Etiquetas

Métricas

Usuarios

Recursos

Widget

Datum

Panel de Atención Externo

Canal Personalizado

Gestión de Memoria

Directrices para las plantillas

Formato de archivo

Encabezado

Primera columna

Columnas restantes

Ejemplo

Enviar HSM desde archivo

Opciones de carga de archivo

Parámetros del cuerpo

Ejemplos de solicitud

Por método de carga del archivo

Por tipo de plantilla

Por escenario

Respuestas del envío

Estructura de params

Estructura de buttonParameters

Estructura de cards

Estructura de actions

​Directrices para las plantillas

​Formato de archivo

​Encabezado

​Primera columna

​Columnas restantes

​Ejemplo

​Enviar HSM desde archivo

​Opciones de carga de archivo

​Parámetros del cuerpo

​Ejemplos de solicitud

​Por método de carga del archivo

​Por tipo de plantilla

​Por escenario

​Respuestas del envío

​Estructura de params

​Estructura de buttonParameters

​Estructura de cards

​Estructura de actions

Directrices para las plantillas

Formato de archivo

Encabezado

Primera columna

Columnas restantes

Ejemplo

Enviar HSM desde archivo

Opciones de carga de archivo

Parámetros del cuerpo

Ejemplos de solicitud

Por método de carga del archivo

Por tipo de plantilla

Por escenario

Respuestas del envío

Estructura de params

Estructura de buttonParameters

Estructura de cards

Estructura de actions