Using message streams

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

Transactional Message Streams are for transactional messages triggered by a user action such as while requesting one time password (OTP). Marketing Message Streams are for marketing(promotional/bulk) messages sent to many recipients at once, for instance, to notify them 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, ensuring a high deliverability of transactional messages.

You can add more message streams in your Falu workspace, alongside the default ones, to further categorize and monitor messages according to your business needs.

Creating a message stream

Message streams can be created or updated through the Dashboard or Message Streams API.

Creating a message stream using the Dashboard

1. Select the workspace to which you'd like to add the 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 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.

Sending a message using a message stream

To send a message using a specific message stream, specify the message stream's id or name. In the image below, these are labeled as 1 and 2, respectively, and can be found in 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 in combination 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"
  }
]

Archiving a message stream

A message stream that is no longer in use can be archived. Once archived, such a stream cannot be used to send any type of messages. Additionally, these streams, along with their activity and statistics, are automatically deleted after 45 days. It is possible to restore ("Unarchive") the archived stream during this period.

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