Skip to main content

Sending messages using the API

Besides using the Dashboard, you can also send messages directly through API calls to the endpoint Below, we will detail how you can send a message to a mobile number in Kenya using Postman as our API client.


Your workspace needs to be in Live mode for you to send messages using the Messages API. As such, make sure that your workspace is completely activated before proceeding with the steps below.

Sending a message using the Falu Messaging API

The following steps represent a typical workflow of sending a message using the API.

Get your secret key

Log into your Dashboard and head over to the Developers menu and copy your secret key.



Keep your keys secure by rolling them periodically. To do so, click on Roll/update secret under Actions in the API Keys section of your dashboard.

Configure your message

In this guide, we will be using Postman as our API client through which we will be sending the message. You can also use other platforms such as the terminal/ command prompt, ReqBin, or Restfox.

As covered in the Messaging API Docs, the top level messaging endpoint is

A sample cURL POST request to send a message is therefore:

$ curl -X POST '' \
--header 'X-Falu-Version: 2022-09-01' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
"body": "Hello World, from Falu Messaging",
"to": "+254somenumber",
"stream": "transactional"

In Postman, our request looks as follows: img-docs-messages-send-message-api-postman

Send your message

Confirm the details provided in your message and hit send!


A successful API call must have the following parameters:

  1. To - the recipient of the message.
  2. Body - the message's contents.
  3. Stream - the stream Falu should use to send the message. Refer to streams docs for more information.

Optionally, you can use a template to compose your message. You must then include the template ID or its alias in your parameters. Check out templates docs for more details.

Monitor the status of your message

You should get a 200 OK status response if your request was successfully sent.