Using message streams

Message Streams in Falu allow you to categorize messages and, in doing so, send all of your application messages through Falu. Falu provides three main message streams: Transactional, Inbound, and Marketing.

Transactional Message Streams are for transactional messages, which are triggered by a user action, for instance a request for a one time password (OTP) or dispatch notification. Marketing Message Streams are for promotional messages, which your application sends to many recipients at once, for instance, a notification of change in business working hours. Inbound message streams are for two-way communications between you and your customers as they allow users to send messages back to you.

Marketing Message Streams mostly use separate infrastructure (depending on the mobile network provider) from transactional ones, and this separation ensures a high deliverability of transactional messages.

Adding additional Message Streams in your Falu workspace, alongside the default ones, allow you to further categorize and monitor messages according to your business needs.

Creating a message stream

Message Streams can be created or updated using either the Falu dashboard or the Message Streams API.

Creating a Message Stream using the Falu dashboard

1. Select the workspace to which you'd like to add a new Message Stream.
2. On the left navigation, under the Messaging section, choose Streams.
3. To the right side click on Create Stream.
4. On the form, fill out the name, add a description, and select the type - whether Transactional, Marketing, or Inbound.
5. Under Additional Information, provide an optional key-value pair to be attached to the object's metadata.

The name of the message stream must be unique across your workspace.

Creating a Message Stream using the Message Streams API

You can also create or update a Message Stream using the Message Streams API.

A message stream name only allows alphanumeric characters, hyphens (-) or underscores (_). For example, promotional-G3 is allowed but promotional:G3 or Promotional G3 are not allowed.

Sending a message

To send a message using a specific Message Stream, you can specify the Message Stream id or name. These are labeled as 1 and 2 respectively in the image below and can be found on the detailed view of the specific Message Stream.

Use either of these values when sending a message in the stream property using the Send a message API or the Send bulk messages API.

Example (using stream name):

{
  "to": "+254722000000",
  "body": "John, your account has been debited USD 12.00 at CBK on 2020-Dec-12",
  "stream": "transactional"
}

Example (using stream id):

{
  "to": "+254722000000",
  "body": "John, your account has been debited USD 12.00 at CBK on 2020-Dec-12",
  "stream": "mstr_602ce49cc74dad6a38f99c2f"
}

The same can be done when sending bulk messages and can be mixed with templates:

[
  {
    "to": "+254722000000",
    "body": "John, your account has been debited USD 12.00 at CBK on 2020-Dec-12",
    "stream": "mstr_602ce49cc74dad6a38f99c2f"
  },
  {
    "to": "+254722000000",
    "template": {
      "alias": "counseling_promo",
      "model": {
        "student": {
          "name": "John"
        }
      }
    },
    "stream": "transactional"
  }
]

When sending a message using the Falu dashboard, you will be prompted to select a Message Stream from the ones available in your workspace.

Archiving a Message Stream

You can choose to archive a message stream that is no longer in use.

An archived message stream cannot be used to send any type of messages. Additionally, these streams, along with their activity and statistics, are automatically deleted 45 days after archiving. During this window is it is possible to restore ("Unarchive") the archived stream.

Archiving and unarchiving a message stream can be done using the Archive Message Stream API and the Unarchive Message Stream API, respectively.