API Walkthrough

Introduction

This page introduces the RCS API to give you an idea for how you would use the API from your own application.

The walkthrough makes use of two popular command line utilities:

We use curl to send requests to the API, and
The jq utility to manipulate JSON structures.

I recommend you install these and run the commands from the scripts below as we proceed.

Prerequisites

Let's start a new terminal and set up a variable for the API:

API_URL=https://api.kero.chat/rbm

You can test if the URL is correct by checking the API version:

curl -s $API_URL/version | jq

The -s ensures that curl is silent and jq should format the output. You should get something like this:

{
  "version": "0.8.0"
}

If you do not, the -i flag shows you more info about the response:

curl -i $API_URL/version

In which case curl will show you more information that might help you troubleshoot.

Basic authentication

You need an API Token as the basic auth credentials. This token is base 64 encoding of a token ID and a token secret. Contact support@kero.chat to get your API token.

Here is an example:

TOKEN_ID=27EFC674F7A74CE4881AE4D800F92A6C-09-1
TOKEN_SECRET=some-secret-code

For this example we encode 27EFC674F7A74CE4881AE4D800F92A6C-09-1:some-secret-code to base 64 and we get:

BASE_64=MjdFRkM2NzRGN0E3NENFNDg4MUFFNEQ4MDBGOTJBNkMtMDktMTpzb21lLXNlY3JldC1jb2Rl

We need to use this value in a header and create an environment variable to make things easier to call:

BASIC_AUTH="Authorization: Basic $BASE_64"

Let's test that by getting a list of the Brand Agents associated with your account:

curl -s -H $BASIC_AUTH $API_URL/basic/agents | jq

The brand agent is an important concept of the Kero API; all messages are send using an agent. If you see no agents here your Kero account is not yet ready for sending messages.

Now take the id property of one of your brand agents and place it in a new variable:

AGENT_ID=your-agent-id

Agent authentication

In order to send a message to a phone number you need an Agent Token. This token is a temporary authentication token that you use to send messages. The idea is to use the token until it expires. This improves the security as well as the throughput of your application.

To get an agent bearer you make this call:

curl -s -H $BASIC_AUTH $API_URL/basic/agent-token/$AGENT_ID | jq

And you should get something like this:

{
  "agentToken": "some-token-value",
  "expiryEpoch": 1708108588,
  "expiry": "2024-02-16T18:36:28Z"
}

Here the agentToken is of primary interest to us. The expiry property shows you when the accessToken expires. At this time you would have to fetch a new value.

The value for expiryEpoch is expiry expressed as an epoch value.

Notice the date format for used for expiry . This format is used for all date values in this API.

The jq utility comes in handy to extract the token into an environment variable:

AGENT_TOKEN=`curl -s -H $BASIC_AUTH $API_URL/basic/agent-token/$AGENT_ID | jq -r ".agentToken"`

The token is used in a bearer auth header, so let's define a variable for that too:

AGENT_AUTH="Authorization: Bearer $AGENT_TOKEN"

Send text

Armed with an agent auth value we just need an MSISDN to send a message.

It is a good idea to configure your own number here, so that you can see it on your device. You need the + prefix followed by your country code and no spaces.

MSISDN=+0007891234

An RCS message requires a JSON structure. Let's use this JSON for a simple text message:

MESSAGE='{"content":{"rcs":{"contentMessage":{"text":"Hello RCS world!"}}}}'

For a WhatsApp agent things look a bit differently; so use this instead if you have WhatsApp:

MESSAGE='{"content":{"wa":{"messaging_product": "whatsapp", "recipient_type": "individual", "type": "text", "text": { "preview_url": false, "body": "Hello WhatsApp world!" }}}}`

The call to send a message is:

JSON_H="Content-Type: application/json"
curl -s -H $AGENT_AUTH -H $JSON_H $API_URL/agent/message/$MSISDN -d $MESSAGE | jq

Note that we must send through the content-type header whenever we use the POST method on RCS API endpoints.

The reply contains the ID of the newly created message, expect something like this:

{
  "id": "test-1710399375697972632-ed3fe72f-c3"
}

In this particular case the message ID starts with test- . This is because I used an MSISDN that begins with +0007. This special prefix is used to send test messages; and they are not forwarded to any device. You can use these MSISDN values to test your API calls during development.

Message query

Now that we sent a message we are ready to fetch the list of sent messages.

Here, we provide criteria to pick the 3 most recent messages:

CRIT='{"limit":3}'

Note that this endpoint is on the /basic API, so we have to use basic auth:

curl -s -H $BASIC_AUTH -H $JSON_H $API_URL/basic/message/query -d $CRIT | jq

What you get back is an array of message objects. Here is an example of a response with a test message:

[
  {
    "agentId": "2[snip]Y",
    "created": "2024-02-19T08:46:22Z",
    "id": "test-1708332382683858-ed3fe72f-c329-",
    "msisdn": "+0007891234"
  }
]

There are optional properties such as sendStatus and sendStatusReason that become available during message processing. These property values are usually updated within a few seconds, but the magnitude of the delay depends on system load.

For example, here is a message that failed:

[
  {
    "created": "2024-03-06T06:05:28.439467Z",
    "id": "dbf79990-635e-4818-ac84-ad030387fa54",
    "msisdn": "+1111111",
    "sendStatus": "failed",
    "sendStatusReason": "Country code Not Found: Invalid phone Number"
  }
]