Bulk Send

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

import requests

url = "https://api.jelou.ai/v1/hsm/file"

payload = {
    "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"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.jelou.ai/v1/hsm/file', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.jelou.ai/v1/hsm/file",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.jelou.ai/v1/hsm/file"

	payload := strings.NewReader("{\n  \"campaignName\": \"<string>\",\n  \"elementName\": \"<string>\",\n  \"botId\": \"<string>\",\n  \"params\": [\n    {\n      \"param\": 123,\n      \"column\": \"<string>\"\n    }\n  ],\n  \"type\": \"text\",\n  \"mediaUrl\": \"<string>\",\n  \"fileUrl\": \"<string>\",\n  \"buttonPayloads\": [\n    {}\n  ],\n  \"actions\": {},\n  \"scheduledAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.jelou.ai/v1/hsm/file")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"campaignName\": \"<string>\",\n  \"elementName\": \"<string>\",\n  \"botId\": \"<string>\",\n  \"params\": [\n    {\n      \"param\": 123,\n      \"column\": \"<string>\"\n    }\n  ],\n  \"type\": \"text\",\n  \"mediaUrl\": \"<string>\",\n  \"fileUrl\": \"<string>\",\n  \"buttonPayloads\": [\n    {}\n  ],\n  \"actions\": {},\n  \"scheduledAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.jelou.ai/v1/hsm/file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"campaignName\": \"<string>\",\n  \"elementName\": \"<string>\",\n  \"botId\": \"<string>\",\n  \"params\": [\n    {\n      \"param\": 123,\n      \"column\": \"<string>\"\n    }\n  ],\n  \"type\": \"text\",\n  \"mediaUrl\": \"<string>\",\n  \"fileUrl\": \"<string>\",\n  \"buttonPayloads\": [\n    {}\n  ],\n  \"actions\": {},\n  \"scheduledAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "message": "<string>",
  "statusMessage": "<string>",
  "status": 123,
  "error": {
    "code": "<string>",
    "key": "<string>",
    "description": "<string>",
    "developerMessages": {},
    "clientMessages": {}
  },
  "validationError": {}
}

{
  "message": "<string>",
  "statusMessage": "<string>",
  "status": 123,
  "error": {
    "code": "<string>",
    "key": "<string>",
    "description": "<string>",
    "developerMessages": {},
    "clientMessages": {}
  },
  "validationError": {}
}

{
  "message": "<string>",
  "statusMessage": "<string>",
  "status": 123,
  "error": {
    "code": "<string>",
    "key": "<string>",
    "description": "<string>",
    "developerMessages": {},
    "clientMessages": {}
  },
  "validationError": {}
}

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

import requests

url = "https://api.jelou.ai/v1/hsm/file"

payload = {
    "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"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.jelou.ai/v1/hsm/file', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.jelou.ai/v1/hsm/file",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.jelou.ai/v1/hsm/file"

	payload := strings.NewReader("{\n  \"campaignName\": \"<string>\",\n  \"elementName\": \"<string>\",\n  \"botId\": \"<string>\",\n  \"params\": [\n    {\n      \"param\": 123,\n      \"column\": \"<string>\"\n    }\n  ],\n  \"type\": \"text\",\n  \"mediaUrl\": \"<string>\",\n  \"fileUrl\": \"<string>\",\n  \"buttonPayloads\": [\n    {}\n  ],\n  \"actions\": {},\n  \"scheduledAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.jelou.ai/v1/hsm/file")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"campaignName\": \"<string>\",\n  \"elementName\": \"<string>\",\n  \"botId\": \"<string>\",\n  \"params\": [\n    {\n      \"param\": 123,\n      \"column\": \"<string>\"\n    }\n  ],\n  \"type\": \"text\",\n  \"mediaUrl\": \"<string>\",\n  \"fileUrl\": \"<string>\",\n  \"buttonPayloads\": [\n    {}\n  ],\n  \"actions\": {},\n  \"scheduledAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.jelou.ai/v1/hsm/file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"campaignName\": \"<string>\",\n  \"elementName\": \"<string>\",\n  \"botId\": \"<string>\",\n  \"params\": [\n    {\n      \"param\": 123,\n      \"column\": \"<string>\"\n    }\n  ],\n  \"type\": \"text\",\n  \"mediaUrl\": \"<string>\",\n  \"fileUrl\": \"<string>\",\n  \"buttonPayloads\": [\n    {}\n  ],\n  \"actions\": {},\n  \"scheduledAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "message": "<string>",
  "statusMessage": "<string>",
  "status": 123,
  "error": {
    "code": "<string>",
    "key": "<string>",
    "description": "<string>",
    "developerMessages": {},
    "clientMessages": {}
  },
  "validationError": {}
}

{
  "message": "<string>",
  "statusMessage": "<string>",
  "status": 123,
  "error": {
    "code": "<string>",
    "key": "<string>",
    "description": "<string>",
    "developerMessages": {},
    "clientMessages": {}
  },
  "validationError": {}
}

{
  "message": "<string>",
  "statusMessage": "<string>",
  "status": 123,
  "error": {
    "code": "<string>",
    "key": "<string>",
    "description": "<string>",
    "developerMessages": {},
    "clientMessages": {}
  },
  "validationError": {}
}

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 each recipient’s identifier: a phone number or a BSUID. For phone numbers, it is mandatory to include the international code without the + symbol (for example, for a number in Ecuador, write PHONE_NUMBER).

BSUID cannot be used to send AUTHENTICATION (OTP) templates; that recipient must be sent as a phone number. If a row with a BSUID targets an AUTHENTICATION template, that row is skipped from the send without affecting the rest of the file.

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

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

Property	Type	Description	Required
campaignName	string	Name assigned to the campaign being sent.	Yes
elementName	string	Template name. Must have approved status by WhatsApp.	Yes
botId	string	Unique identifier of the channel sending the template.	Yes
params	array	Array of objects with the parameter number and the corresponding CSV column. If the template has no parameters, the array must be empty.	Yes
type	string	Template type: `text`, `image`, `document`, `video`. Defaults to `text`.	No
mediaUrl	string	Public URL of the media file. Required for image, video, or document templates.	Conditional
fileUrl	string	Public URL of the CSV file. Required if the file is not uploaded directly.	Conditional
file	file	Attached CSV file. Required if `fileUrl` is not used.	Conditional
buttonPayloads	array	Array of objects for quick reply buttons with workflows.	No
actions	object	Actions related to the template.	No
scheduledAt	date	Date and time in UTC when the campaign will be sent.	No

Request examples

Send from public URL (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.example.com/image.png",
    "type": "image",
    "fileUrl": "https://cdn.example.com/campaign.csv",
    "buttonPayloads": [
      {"type": "edge", "action": "Yes", "skillId": "1"}
    ]
  }'

Send with attached file (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=@/local/path/campaign.csv \
  --form 'params=[]'

Send responses

200 - Successful response

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

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 workflows:

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

Show child attributes

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

⌘I

API reference

Send Messages

Campaigns

Conversations

Metrics

Users

Resources

Widget

Datum

External Support Panel

Custom Channel

Memory Management

Template guidelines

File format

Header

First column

Remaining columns

Example

Send HSM from file

File upload options

Body parameters

Request examples

Send responses

params structure

buttonPayloads structure

Authorizations

Body

Response

​Template guidelines

​File format

​Header

​First column

​Remaining columns

​Example

​Send HSM from file

​File upload options

​Body parameters

​Request examples

​Send responses

​params structure

​buttonPayloads structure

Authorizations

Body

Response

Template guidelines

File format

Header

First column

Remaining columns

Example

Send HSM from file

File upload options

Body parameters

Request examples

Send responses

params structure

buttonPayloads structure