Skip to content

Agent API

Introduction

This page describes the /agent API endpoints.

These endpoints are protected by a bearer auth token. See the 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:

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:

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

If you typically send many messages in bursts, consider batching them. A message that the recipient are 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

{
    content: MessageContent|null,
    template: TemplateContent|null,
    userRef: string|null,
    smsSenderId: string|null
}
  1. Either the content of the template property must have a value, but not both.
  2. The content property contains a 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 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.

Response schema

Returns the ID of the newly created message.

{
  id: string;
}

Example

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