Bulk Send

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: `hsm` (text only), `image`, `video`, `document`, or `carousel`. If omitted, it is sent as a text template.	No
language	string	Template language code, for example `es`, `en`, or `pt_BR`.	No
mediaUrl	string	Public URL of the header 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
headerParameters	array	Variable parameter for the text header, taken from a CSV column. Maximum 1 parameter.	No
buttonParameters	array	Configuration of the template buttons: quick reply (`QUICK_REPLY`) or dynamic URL (`URL`).	No
cards	array	Carousel cards. Required when `type` is `carousel`.	Conditional
actions	object	Actions that run when the recipient replies: target workflow, memory, and CRM.	No
date	string	Date and time in UTC (ISO 8601) when the campaign will be sent. If omitted, the campaign is sent immediately.	No

Request examples

By file upload method

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",
    "buttonParameters": [
      {"type": "QUICK_REPLY", "payload": {"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 '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=@/local/path/campaign.csv \
  --form 'params=[]'

By template type

Each example uses a CSV file published at fileUrl whose columns match the ones listed in params.

Text

Template: Hi {{1}}, your order {{2}} is on its way.

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "orders_on_the_way",
    "botId": "BOT_ID",
    "elementName": "order_on_the_way",
    "language": "en",
    "type": "hsm",
    "params": [
      {"param": 1, "column": "name"},
      {"param": 2, "column": "order_number"}
    ],
    "fileUrl": "https://cdn.example.com/campaigns/orders.csv"
  }'

Image

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "end_of_month_promo",
    "botId": "BOT_ID",
    "elementName": "end_of_month_promo",
    "language": "en",
    "type": "image",
    "params": [
      {"param": 1, "column": "name"}
    ],
    "mediaUrl": "https://cdn.example.com/media/end-of-month-promo.jpg",
    "fileUrl": "https://cdn.example.com/campaigns/promo-customers.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": "app_launch",
    "botId": "BOT_ID",
    "elementName": "app_launch_video",
    "language": "en",
    "type": "video",
    "params": [],
    "mediaUrl": "https://cdn.example.com/media/app-launch.mp4",
    "fileUrl": "https://cdn.example.com/campaigns/app-users.csv"
  }'

Document

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "september_statement",
    "botId": "BOT_ID",
    "elementName": "account_statement",
    "language": "en",
    "type": "document",
    "params": [
      {"param": 1, "column": "name"},
      {"param": 2, "column": "product"}
    ],
    "mediaUrl": "https://cdn.example.com/media/account-statement.pdf",
    "fileUrl": "https://cdn.example.com/campaigns/statements.csv"
  }'

Carousel

Each card defines its own media asset in mediaUrl and its buttons in buttonParameters. The cardIndex field indicates which card each button belongs to, starting at 0.

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "seasonal_catalog",
    "botId": "BOT_ID",
    "elementName": "seasonal_catalog",
    "language": "en",
    "type": "carousel",
    "params": [],
    "fileUrl": "https://cdn.example.com/campaigns/catalog-customers.csv",
    "cards": [
      {
        "mediaUrl": "https://cdn.example.com/media/product-1.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "View product 1", "skillId": "1", "cardIndex": 0}}
        ]
      },
      {
        "mediaUrl": "https://cdn.example.com/media/product-2.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "View product 2", "skillId": "2", "cardIndex": 1}}
        ]
      },
      {
        "mediaUrl": "https://cdn.example.com/media/product-3.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "View product 3", "skillId": "3", "cardIndex": 2}}
        ]
      }
    ]
  }'

By scenario

These examples show the JSON request body. Send it to the same endpoint with the Content-Type: application/json header.

Quick reply buttons that trigger a workflow

Each button whose payload.type is edge takes the recipient to the workflow set in skillId. The action text must match the button text in the template.

{
  "campaignName": "appointment_confirmation",
  "botId": "BOT_ID",
  "elementName": "confirm_appointment",
  "language": "en",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "name"},
    {"param": 2, "column": "appointment_date"}
  ],
  "fileUrl": "https://cdn.example.com/campaigns/appointments.csv",
  "buttonParameters": [
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Confirm", "skillId": "1"}},
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Reschedule", "skillId": "2"}},
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Cancel", "skillId": "3"}}
  ]
}

Dynamic URL button

The URL suffix is taken from the CSV column set in payload.param. For example, if the template defines the URL https://requests.example.com/{{1}}, each recipient gets their own link.

{
  "campaignName": "request_tracking",
  "botId": "BOT_ID",
  "elementName": "request_tracking",
  "language": "en",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "name"},
    {"param": 2, "column": "request_number"}
  ],
  "fileUrl": "https://cdn.example.com/campaigns/requests.csv",
  "buttonParameters": [
    {"type": "URL", "param": 1, "payload": {"param": "request_url"}}
  ]
}

Header parameter

For templates with a variable in the text header, set the CSV column in headerParameters.

{
  "campaignName": "customer_welcome",
  "botId": "BOT_ID",
  "elementName": "personalized_welcome",
  "language": "en",
  "type": "hsm",
  "headerParameters": [
    {"param": "1", "column": "name"}
  ],
  "params": [
    {"param": 1, "column": "customer_code"}
  ],
  "fileUrl": "https://cdn.example.com/campaigns/new-customers.csv"
}

Route the reply to a workflow

With actions.setSkill, the recipient’s reply is routed to the specified workflow.

{
  "campaignName": "payment_reminder",
  "botId": "BOT_ID",
  "elementName": "payment_reminder",
  "language": "en",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "name"},
    {"param": 2, "column": "amount"},
    {"param": 3, "column": "due_date"}
  ],
  "fileUrl": "https://cdn.example.com/campaigns/pending-payments.csv",
  "actions": {
    "setSkill": {"id": 5001}
  }
}

Save CSV data to memory and CRM

Use {column_name} as the value to take the data from that CSV column. setMemoryParams saves the values in the user memory, and crmParams saves them in CRM fields.

{
  "campaignName": "insurance_renewal",
  "botId": "BOT_ID",
  "elementName": "policy_renewal",
  "language": "en",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "name"},
    {"param": 2, "column": "product"}
  ],
  "fileUrl": "https://cdn.example.com/campaigns/renewals.csv",
  "actions": {
    "setMemoryParams": {
      "customer_name": "{name}",
      "product": "{product}"
    },
    "crmParams": {
      "name": "{name}",
      "city": "{city}"
    }
  }
}

Scheduled send

Use date to schedule the campaign for a date and time in UTC.

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

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.

headerParameters uses the same structure, but accepts only one element.

buttonParameters structure

Each element in the array configures one template button. Quick reply (QUICK_REPLY):

[
  {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Confirm", "skillId": "1"}},
  {"type": "QUICK_REPLY", "payload": {"type": "flow", "action": "View offer", "flowId": "2"}}
]

payload.type: Button target. edge triggers a workflow and flow triggers a flow.
payload.action: Button text. Must match the text defined in the template.
payload.skillId: ID of the workflow to trigger. Required when payload.type is edge.
payload.flowId: ID of the flow to trigger. Required when payload.type is flow.
payload.cardIndex: Position of the card the button belongs to, starting at 0. Carousels only.

To get the skillId of a workflow, hover over the workflow name in Brain Studio. A tooltip will appear showing the corresponding ID.

Dynamic URL (URL):

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

param: Number of the URL parameter in the template.
payload.param: CSV column with the value that completes the URL.

cards structure

Each carousel card is an object with:

mediaUrl: Public URL of the card image or video.
params: Card body parameters, with the same structure as params. Use an empty array if the card has no parameters.
buttonParameters: Card buttons. Each payload must include cardIndex.

actions structure

Property	Description	Example
setSkill	Workflow that handles the recipient’s reply.	`{"id": 1}`
setMemoryParams	Values saved in the user memory. Use `{column}` to take the value from the CSV.	`{"product": "{product}"}`
crmParams	Values saved in CRM fields. Use `{column}` to take the value from the CSV.	`{"city": "{city}"}`

API reference

Send Messages

Campaigns

Conversations

Tags

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

By file upload method

By template type

By scenario

Send responses

params structure

buttonParameters structure

cards structure

actions structure

​Template guidelines

​File format

​Header

​First column

​Remaining columns

​Example

​Send HSM from file

​File upload options

​Body parameters

​Request examples

​By file upload method

​By template type

​By scenario

​Send responses

​params structure

​buttonParameters structure

​cards structure

​actions structure

Template guidelines

File format

Header

First column

Remaining columns

Example

Send HSM from file

File upload options

Body parameters

Request examples

By file upload method

By template type

By scenario

Send responses

params structure

buttonParameters structure

cards structure

actions structure