> ## 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.

# Agent API

> Reference for the /agent API endpoints, protected by a bearer auth token.

## Introduction

This page describes the `/agent` API endpoints.

These endpoints are protected by a bearer auth token. See the
[brand agent token](https://kero.chat/help/kero-developer-pages/basic-api.md#brand-agent-token) endpoint for more
information on how to get such a token.

The examples in the sections that follow use variables that you might want to
configure on a terminal session:

```sh theme={null}
API_URL=https://api.celerity.co.za/rbm
AGENT_ID='<Brand Agent ID>'
BASIC_AUTH="Authorization: Basic $API_TOKEN_BASE_64"
```

Also, useful to get a fresh `AGENT_TOKEN` with the help of `jq`:

```sh theme={null}
AGENT_TOKEN=`curl -s -H $BASIC_AUTH $API_URL/basic/agent-token/$AGENT_ID | jq -r ".agentToken"`
AGENT_AUTH="Authorization: Bearer $AGENT_TOKEN"
```

## Message submit

Send a message to a single phone number.

If you typically send more than one messages in bursts, rather use
[batching](https://kero.chat/help/kero-developer-pages/basic-api.md#batch-create). An urgent message that the recipient is
waiting for (like those that contain an OTP) should not be batched. For such
messages this direct submit is likely to be the correct solution.

Note there is a per-provider limit on the messages per second that will be
accepted on this endpoint (this is usually around `50 mps`). Please contact us
for more details if you are concerned about this limitation.

Endpoint: `POST /message/:msidn`

**Request schema**

```ts theme={null}
{
   content: MessageContent|null,
   template: TemplateContent|null,
   userRef: string|null,
   smsSenderId: string|null,
   isMarketing: boolean|null,
}
```

1. Either the `content` of the `template` property must have a value, but not
   both.
2. The `content` property contains a
   [Message Content](https://kero.chat/help/kero-developer-pages/object-schemas.md#message-content) object.
3. The `content` property must contain valid content for the `providerType` of
   the brand agent you are using.
4. The `template` property contains a
   [Template Content](https://kero.chat/help/kero-developer-pages/object-schemas.md#template-content) object.
5. The `userRef` property is limited to a length of `36` characters; and it
   cannot be an empty string.
6. If the `smsSenderId` is not `null` this value takes precedence over the
   sender ID provided on the template.
7. The `isMarketing` flag should be set to `true` if the batch contains marketing messages. The default value is `false`

**Response schema**

Returns the ID of the newly created message.

```ts theme={null}
{
  id: string;
}
```

**Example**

```sh theme={null}
MESSAGE='{"content":{"rcs":{"contentMessage":{"text":"Hello world"}}}}'
JSON_H="Content-Type: application/json"
curl -H $AGENT_AUTH -H $JSON_H $API_URL/agent/message/$MSISDN -d $MESSAGE | jq
```


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