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>"
}
Use this function to send templates in bulk to your customers. The API will handle delivery to recipients from a column-based file. Sending templates in bulk allows you to send a predefined template with different values related to each customer, so you can select dynamic information from a source such as a file, to automate and send your campaign easily.

​
Template guidelines

The source file must be created following these specifications:

​
File format

Only files with the .CSV extension are supported. The first row of the file must define the column names (header). Follow these rules for the header:
  • Avoid blank spaces in column names.
  • Do not use special characters or punctuation marks (e.g., !, $, %, &, *, etc.).
  • Use only letters, numbers, and underscores (_) if necessary.
Correct: phone_number, customer_name, order_amount Incorrect: phone number, customer-name!, order#amount

​
First column

The first column must contain the phone numbers of the recipients. It is mandatory to include the international code without the + symbol (for example, for a number in Ecuador, write PHONE_NUMBER).

​
Remaining columns

The other columns will be used for the dynamic values of the parameters (template personalization).

​
Example

If your template contains the following content: 
Your order {{1}} for a total of {{2}} is confirmed. The expected delivery is {{3}}.
The CSV file would be:
phone_numberparam_1param_2param_3
PHONE_NUMBERA12345$250.00December 1
PHONE_NUMBER_2B67890$100.50December 2
PHONE_NUMBER_3C22345$50.00December 3
The CSV file must be encoded in UTF-8.

​
Send HSM from file

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

​
File upload options

There are two ways to provide the CSV file with recipient information:
  1. Using a public URL: You can provide the URL to the CSV file that is publicly available. In this case, the request body must be in JSON format.
  2. Uploading the file: Alternatively, you can attach the CSV file directly to the request. In this case, the request body must be in multipart/form-data format.

​
Body parameters

PropertyTypeDescriptionRequired
campaignNamestringName assigned to the campaign being sent.Yes
elementNamestringTemplate name. Must have approved status by WhatsApp.Yes
botIdstringUnique identifier of the bot sending the template.Yes
paramsarrayArray of objects with the parameter number and the corresponding CSV column. If the template has no parameters, the array must be empty.Yes
typestringTemplate type: text, image, document, video. Defaults to text.No
mediaUrlstringPublic URL of the media file. Required for image, video, or document templates.Conditional
fileUrlstringPublic URL of the CSV file. Required if the file is not uploaded directly.Conditional
filefileAttached CSV file. Required if fileUrl is not used.Conditional
buttonPayloadsarrayArray of objects for quick reply buttons with skills.No
actionsobjectActions related to the template.No
scheduledAtdateDate and time in UTC when the campaign will be sent.No

​
Request examples

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.example.com/image.png",
    "type": "image",
    "fileUrl": "https://cdn.example.com/campaign.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=@/local/path/campaign.csv \
  --form 'params=[]'

​
Send responses

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

​
params structure

Each element in the params array is an object that contains: 
[
  {"param": 1, "column": "customer_name"},
  {"param": 2, "column": "order_amount"}
]
  • param: Parameter number in the template (1, 2, 3…).
  • column: Name of the column in the CSV file from which values will be extracted.

​
buttonPayloads structure

For templates with quick reply buttons that activate 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