Skip to main content

Working with message batches

Sometimes, businesses with high message volumes or time constraints need to send a message to several recipients at once i.e. in a batch.

To facilitate this, Falu provides a message-batches endpoint that allows you to send up to 1,000 messages in one API call.

You can use message batches to satisfy the following use-cases:

  • Announce a new product or service.
  • Generate alerts.
  • Send confirmation messages or reminders for appointments, reservations, and purchases at scale.
  • Recommend products to customers.
note

At the moment, message batches are only available through the API. You cannot, therefore, create or send a message batch from the dashboard.

How do message batches work?

Generally, a batch comprises a message that is meant for a group of related recipients. For example, if you have a product announcement that you wish to blast to your customers, you would compose a message body and send it to these clients collectively through Falu's message-batches endpoint. You can compose the message body from scratch or use an existing template.

The general syntax of a POST request to send a message batch is:

curl -X POST 'https://api.falu.io/v1/message_batches' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'X-Falu-Version: 2022-09-01' \
--header 'Content-Type: application/json' \
--data '{
"stream": "transactional",
"messages": [
{
"tos": [ "+254recipient1", "+254recipient2" ],
"body": "YOUR_MESSAGE_BODY"
}
]
}'

Alternatively, if you wish to use an existing template, you would do so as follows:

curl -X POST 'https://api.falu.io/v1/message_batches' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'X-Falu-Version: 2022-09-01' \
--header 'Content-Type: application/json' \
--data '{
"stream": "transactional",
"messages": [
{
"tos": [ "+254recipient1", "+254recipient2" ],
"template": {
"id": "TEMPLATE_ID",
"model": {
"key": "value"
}
}
}
]
}'

Message batches are best used for marketing purposes. Check Sending marketing messages for more details.