Sender IDs & agents

On RCS your brand name is not a string you pass — it is a registered sender that has been reviewed and approved. You cannot send under a name you have not registered, and you cannot send under one that is still pending.

Two things, not one

This trips people up, so it is worth being blunt about:

The sender ID

The brand name. Register it here, wait for approval. Enough to send plain text.

The RBM agent

The agent rich messages are sent from. Mapped to your sender by support after Google’s agent onboarding. Required for cards, carousels and chips.

An approved sender with no agent sends plain text perfectly well and fails every rich send with:

sender "FirstDigits" has no RBM agent registered; rich messages need one

If you plan to send rich messages, start the agent conversation with support at the same time as you register the name — agent onboarding is the slower of the two.

Register a sender

POST/ng/v1/rcs/sender-ids

curl -X POST https://api.9bits.net/ng/v1/rcs/sender-ids \
  -H "Authorization: Bearer $NINEBITS_RCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "FirstDigits",
    "country": "NG",
    "purpose": "Order and delivery notifications",
    "isBrandRegistered": "Yes"
  }'

{ "status": 200, "description": "Your request has been submitted for approval" }

Field	Type	Required	Description
senderId	string	✅	The brand name. Must be unique across the platform.
country	string	—	Where it will be used, e.g. NG.
purpose	string	—	What you will send under it. A human reads this.
isBrandRegistered	string	—	"Yes" or "No" — whether the brand is a registered business.

Write a real `purpose`

It is read by a reviewer deciding whether to approve the name. “Order and delivery notifications for firstdigits.com customers” gets approved; “test” and “notifications” invite questions and delay.

A name already taken comes back:

{ "status": 405, "description": "Duplicate Entry. Please enter a unique Sender Name" }

Note the HTTP status is 400 while the body says 405 — read the body.

Check what you can send from

GET/ng/v1/rcs/sender-ids?status=approved

The cheapest pre-flight check there is. It returns a bare array of the names you are actually allowed to send under:

curl "https://api.9bits.net/ng/v1/rcs/sender-ids?status=approved" \
  -H "Authorization: Bearer $NINEBITS_RCS_KEY"

["FirstDigits", "FD-Alerts"]

Without the query parameter you get the full list with review status:

{
  "status": 200,
  "data": [
    { "sender_id": "FirstDigits", "status": "Active",  "country": "NG", "purpose": "Order and delivery notifications" },
    { "sender_id": "FD-Promo",    "status": "Pending", "country": "NG", "purpose": "Marketing" }
  ]
}

An account with nothing registered returns HTTP 200 with:

{ "status": 404, "description": "Sender ID information not found" }

The response shape changes with the query

?status=approved returns an array. Without it you get an object. Code that assumes one shape will break when someone adds the other call.

Approval

Approval is manual and is done by the platform, not by you. POST /ng/v1/rcs/sender-ids/approval exists but is restricted to the configured approval address — every other caller is refused. It is documented in the API reference for completeness.

A sender is sendable once its status is Active (or Approved). Anything else — including Pending — is rejected at send time, before billing:

sender_id "FD-Promo" is not approved (status: Pending)

1. Register the name with a clear purpose.

2. Poll GET /ng/v1/rcs/sender-ids until it shows Active, or wait for the notification email.

3. If you need rich messages, ask support to complete RBM agent onboarding and map the agent to this sender.

4. Send a test to your own number before you wire it into anything.

Sender replacement

Some accounts are configured so that the sender you pass is substituted for a network-appropriate one at send time. If that is on for your account, the name you send under may not be the name that arrives.

Both are recorded — your original and the substitute — so the reports show what actually went out. You do not need to do anything differently; just do not be surprised if a report shows a name you did not pass.

One thing to get right up front

Your sender name becomes the brand key for consent. An opt-out is recorded against the brand slug — FirstDigits becomes first-digits — so the name you register is the name people unsubscribe from.

Changing brands later means starting your consent record from scratch. See Consent & opt-out.