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 https://api.falu.io/v1/messages. Below, we will detail how you can send a message to a mobile number in Kenya using Postman as our API client.

info

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.

img-docs-messages-send-message-api-get-key

tip

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 https://api.falu.io/v1/messages.

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

$ curl -X POST 'https://api.falu.io/v1/messages' \
    --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!

note

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.

img-docs-messages-send-message-api-response-postman

Last updated on