Send Bulk

Use this feature to send templates in bulk to your customers. The API will handle the delivery to the recipients from a column-based file.

Sending bulk templates allows you to send a preset template with different values related to each customer so that you can select dynamic information from a source like a file in order to automate and send your campaign easily.

Template guidelines

The source (file) must be created following the next specification:

  • File Format: Only files with the .CSV extension are supported.

  • Header: 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 needed.

    • Correct example: phone_number, customer_name, order_amount.

    • Incorrect example: 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 593XXXXXXXXX.

  • Remaining Columns: The other columns will be used for the dynamic parameter values (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}}.
phone_number
param_1
param_2
param_3

593XXXXXXXXX

A12345

$250.00

December 1st

593XXXXXXXXX

B67890

$100.50

December 2nd

593XXXXXXXXX

C22345

$50.00

December 3rd

The CSV file must be UTF-8 encoded

Send HSM from file

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

File Upload Options for Bulk Send

There are two ways to provide the source 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 body of the request should be formatted as JSON.

  2. Uploading the File: Alternatively, you can attach the CSV file directly to the request. In this case, the body of the request should be formatted as multipart/form-data.

Depending on your choice, the request body format will differ:

  • If using a public URL, the request body will be in JSON format.

  • If uploading a file directly, the request body will be in multipart/form-data format.

Request Body

Name
Type
Description
Required

file

string

The file must have a .CSV extension. This file contains the recipient data used in the bulk send process.

Y

fileUrl

string

The file must have a .CSV extension and be publicly available during the bulk send campaign.

Y

campaignName

string

The name assigned to the campaign being sent.

Y

elementName

string

The name of the template being sent. The template must have an approved status from WhatsApp at the time of sending.

Y

params

Array[Object]

Each element in the array is an object containing the parameter number and the corresponding CSV column from which the parameter values will be extracted. If the template has no parameters, the array must be empty.

Y

botId

string

The unique identifier of the bot sending the template.

Y

type

string

Defines the type of template. It could be text, image, document, or video. This field is required when sending image, video, or document templates. If not specified, the default value is text.

Y

mediaUrl

string

A publicly accessible URL that points to the media file (image, video, or document). This is required when sending image, video, or document templates; otherwise, it is not needed.

Y

actions

object

This object defines the actions or configurations related to the template being sent.

N

buttonPayloads

Array[Object]

This field contains an array of objects, each representing a skill/flow that the template will redirect to in case quickreply buttons are used.

N

date

string

The date and time in UTC when the campaign will be sent.

N

Sample API request

Sending the File as a Public URL (JSON Body)

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": "12345-XXX-XXX-XXX-78910",
    "elementName": "test_template",
    "params": [
      {
        "param": 1,
        "column": "customer_name"
      }
    ],
    "mediaUrl": "https://cdn.test.com/public_image.png",
    "type": "image",
    "fileUrl": "https://cdn.test.com/TestCampaign.csv",
    "buttonPayloads": [
      {
        "type": "flow",
        "action": "Yes",
        "flowId": "1"
      }
    ]
  }'

Sending the File as an Attachment (Multipart/Form-Data Body)

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'content-type: multipart/form-data' \
  --form campaignName=campaign_name \
  --form botId=12345-XXX-XXX-XXX-78910 \
  --form elementName=test_template \
  --form 'buttonPayloads=[{"type":"edge","action":"Yes","skillId":"1"},{"type":"edge","action":"Reschedule","skillId":"2"},{"type":"edge","action":"Cancel","skillId":"3"}]' \
  --form file=@/local/path/TestCampaign.csv \
  --form 'params=[]'

Response

{
  "message": [
    "Campaign has been created."
  ],
  "status": "success"
}

PreviousSendNextCampaigns

Last updated