Envío masivo - Jelou AI Docs

Send Bulk HSM

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaignName": "<string>",
  "elementName": "<string>",
  "botId": "<string>",
  "params": [
    {
      "param": 123,
      "column": "<string>"
    }
  ],
  "type": "text",
  "mediaUrl": "<string>",
  "fileUrl": "<string>",
  "buttonPayloads": [
    {}
  ],
  "actions": {},
  "scheduledAt": "2023-11-07T05:31:56Z"
}
'

{
  "message": [
    "<string>"
  ],
  "status": "<string>"
}

POST

hsm

file

Send Bulk HSM

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaignName": "<string>",
  "elementName": "<string>",
  "botId": "<string>",
  "params": [
    {
      "param": 123,
      "column": "<string>"
    }
  ],
  "type": "text",
  "mediaUrl": "<string>",
  "fileUrl": "<string>",
  "buttonPayloads": [
    {}
  ],
  "actions": {},
  "scheduledAt": "2023-11-07T05:31:56Z"
}
'

{
  "message": [
    "<string>"
  ],
  "status": "<string>"
}

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_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 bot 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: `text`, `image`, `document`, `video`. Por defecto es `text`.	No
mediaUrl	string	URL pública del archivo multimedia. 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
buttonPayloads	array	Arreglo de objetos para botones de respuesta rápida con workflows.	No
actions	object	Acciones relacionadas con la plantilla.	No
scheduledAt	date	Fecha y hora en UTC cuando se enviará la campaña.	No

Ejemplos de solicitud

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",
    "buttonPayloads": [
      {"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 '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

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.

Estructura de buttonPayloads

Para plantillas con botones de respuesta rápida que activan workflows:

[
  {"type": "edge", "action": "Yes", "skillId": "1"},
  {"type": "edge", "action": "Reschedule", "skillId": "2"},
  {"type": "edge", "action": "Cancel", "skillId": "3"}
]

Autorizaciones

Authorization

string

header

requerido

Basic authentication using Base64 encoded clientId:clientSecret

Cuerpo

campaignName

string

requerido

elementName

string

requerido

botId

string

requerido

params

object[]

requerido

Show child attributes

type

enum<string>

predeterminado:text

Opciones disponibles:

text,

image,

document,

video

mediaUrl

string<uri>

fileUrl

string<uri>

buttonPayloads

object[]

actions

object

scheduledAt

string<date-time>

Respuesta

Campaign created successfully

message

string[]

status

string

Envío individual (1-1)

Notificaciones

⌘I

​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

​Respuestas del envío

​Estructura de params

​Estructura de buttonPayloads

Autorizaciones

Cuerpo

Respuesta

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

Respuestas del envío

Estructura de params

Estructura de buttonPayloads