Skip to main content
POST
/
v1
/
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_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"}
]

Authorizations

​
Authorization
string
header
required

Basic authentication using Base64 encoded clientId:clientSecret

Body

​
campaignName
string
required
​
elementName
string
required
​
botId
string
required
​
params
object[]
required
​
type
enum<string>
default:text
Available options:
text,
image,
document,
video
​
mediaUrl
string<uri>
​
fileUrl
string<uri>
​
buttonPayloads
object[]
​
actions
object
​
scheduledAt
string<date-time>

Response

Campaign created successfully

​
message
string[]
​
status
string