> ## Documentation Index
> Fetch the complete documentation index at: https://kero.chat/help/llms.txt
> Use this file to discover all available pages before exploring further.

# API Walkthrough

> A guided introduction to the Kero RCS API, showing how you would use it from your own application.

## 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](https://curl.se/) to send requests to the API, and
* The [jq](https://jquery.com/) 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:

```sh theme={null}
API_URL=https://api.kero.chat/rbm
```

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

```sh theme={null}
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:

```json theme={null}
{
  "version": "0.8.0"
}
```

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

```sh theme={null}
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](mailto:support@kero.chat) to get
your *API token*.

Here is an example:

```sh theme={null}
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:

```sh theme={null}
BASE_64=MjdFRkM2NzRGN0E3NENFNDg4MUFFNEQ4MDBGOTJBNkMtMDktMTpzb21lLXNlY3JldC1jb2Rl
```

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

```sh theme={null}
BASIC_AUTH="Authorization: Basic $BASE_64"
```

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

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
curl -s -H $BASIC_AUTH $API_URL/basic/agent-token/$AGENT_ID | jq
```

And you should get something like this:

```json theme={null}
{
  "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](https://en.wikipedia.org/wiki/Epoch_\(computing\)).

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:

```sh theme={null}
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:

```sh theme={null}
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.

```sh theme={null}
MSISDN=+0007891234
```

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

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
{
  "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:

```sh theme={null}
CRIT='{"limit":3}'
```

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

```sh theme={null}
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:

```json theme={null}
[
  {
    "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:

```json theme={null}
[
  {
    "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"
  }
]
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.