Delivery reports

A 200 from the send endpoint means accepted and queued. A delivery report is how you find out what actually happened.

Set a webhook URL and we push every outcome to you. Set none and the outcome is only visible in the reports.

The lifecycle

Queued ──submit──▶ Dispatched ──receipt──▶ Delivered
                        │                └─▶ Undelivered
                        │                └─▶ Rejected
                        └──(no response)──▶ Sent

  any pre-wire failure ─────────────────────▶ Failed

Status	Meaning	Terminal
Queued	Accepted, billed, waiting for a worker.	—
Dispatched	Handed to the gateway, awaiting a receipt.	—
Sent	Submitted, but no response came back. Indeterminate.	—
Delivered	It reached the handset.	✅
Undelivered	It did not, and will not — expired, deleted, unreachable.	✅
Rejected	Refused by the network or the platform.	✅
Failed	Failed before it ever went out.	✅

`Sent` is not `Delivered`, and not a failure either

Sent is reserved for one specific case: the message reached the wire but no acknowledgement came back, so nobody knows whether it landed.

Such a message is never re-sent and never refunded — re-sending risks delivering twice, and refunding risks giving away a message that arrived. A late receipt resolves it.

Treat it as “in flight” in your UI, not as an error. In the reports it is grouped with Dispatched under the sent filter for exactly this reason: from your side, both mean gone, not yet confirmed.

Receive the webhook

Set your endpoint once, in the portal: Settings → Webhooks → RCS. Every RCS event for the account is posted there — delivery outcomes and replies alike.

RCS has its own field

The Webhooks tab has a card per channel. RCS reads the RCS one and nothing else: the SMS field is for SMS delivery receipts, which arrive in a different shape entirely. Setting the SMS one does not enable RCS.

One URL per account, and that is the only place it is set — the send endpoints take no callback_url of their own. Leave it empty and events are still recorded and visible in the reports, just not pushed.

The event

{
  "event": "message.delivered",
  "message_id": "8f2c41ba9d7e40a1b5c3",
  "reference_id": "8f2c41ba9d7e40a1b5c3",
  "rbm_message_id": "2f5a1c9e-7b04-4f8a-9d31-6c0e8a2b4d17",
  "agent": "FirstDigits",
  "destination": "2348020000000",
  "status": "Delivered",
  "raw_event": "READ",
  "timestamp": "2026-09-02T14:31:08Z"
}

Field	Description
event	What happened. Switch on this.
message_id	The referenceId the send returned. This is your join key.
reference_id	The same value, under the name the send response used.
rbm_message_id	The RBM platform’s own id. Useful when raising a ticket.
agent	The agent it was sent from.
destination	The recipient.
status	The message’s status, in the same words the reports use.
raw_event	The provider’s own event name, before we mapped it.
timestamp	RFC 3339 UTC.

Four event names, and no others will appear:

event	Meaning
message.delivered	It reached the handset.
message.undelivered	It did not, and will not.
message.failed	Refused, or failed before it went out.
message.received	Someone replied to your agent.

`status` matches the reports; `raw_event` keeps the detail

status is the same vocabulary the reports and the portal show, so a webhook and a report never disagree about one message.

raw_event is the provider’s spelling underneath it. DELIVERED, READ and DISPLAYED all map to Delivered — a message that was read was necessarily delivered, and we do not bill it differently — but if you care which one arrived, raw_event tells you.

Events that are not an outcome — sent, pending, queued, IS_TYPING — are never pushed. They would otherwise walk a message backwards from Delivered.

An inbound reply

message.received carries the reply instead of a delivery outcome:

{
  "event": "message.received",
  "raw_event": "message",
  "agent_id": "firstdigits_agent",
  "msisdn": "2348020000000",
  "text": "STOP",
  "rbm_message_id": "9c1e4a77-2b30-40de-8f61-1a5d3e90c284",
  "kind": "message",
  "raw": { }
}

raw is the provider’s original body, passed through untouched. Read it if you need something we do not surface yet — but do not build on its shape: it belongs to the RBM platform and changes without notice.

STOP is already handled

A reply of STOP (or UNSUBSCRIBE, CANCEL, END, QUIT) opts that number out at the platform, before you see this event — the next campaign will not include them. You do not need to act on it. Mirror it into your own records if you keep a suppression list of your own.

Rules for your endpoint

Node.js

app.post('/hooks/rcs', express.json(), async (req, res) => {
  // 1. Acknowledge first. Do the work after.
  res.sendStatus(200);

  const { event, message_id, status, timestamp } = req.body;

  if (event === 'message.received') {
    await handleReply(req.body.msisdn, req.body.text);
    return;
  }

  // 2. Be idempotent: the same outcome can arrive more than once.
  await db.messages.updateOne(
    { referenceId: message_id, outcome: null },
    { $set: { outcome: status, doneAt: timestamp } },
  );
});

Python

@app.post("/hooks/rcs")
def rcs_webhook():
    body = request.get_json()
    event = body.get("event")

    if event == "message.received":
        handle_reply(body.get("msisdn"), body.get("text"))
    elif event in ("message.delivered", "message.undelivered", "message.failed"):
        mark_message(body["message_id"], body["status"], body.get("timestamp"))

    # Always 200, even for an event you do not recognise.
    return "", 200

Three things your endpoint must do:

1. Return 2xx quickly. A non-2xx is retried — five attempts, a minute apart — after which the event is abandoned and the outcome is only in the reports. Acknowledge first, process after.
2. Be idempotent. Retries and repeated receipts both mean the same event can arrive more than once. Key on message_id and ignore an outcome for a message already in a terminal state.
3. Tolerate unknown event values. Ignore what you do not recognise rather than erroring on it — an error costs you the retry budget for events you do care about.

Your URL must be public HTTPS

The portal refuses http://, localhost, and private ranges: events carry message content, and an address we cannot reach means callbacks that never arrive. Use a tunnel when developing locally.

The reports

Without a webhook URL, or to reconcile after the fact, query the reports. Timestamps are YYYY-MM-DD HH:MM in your account’s local time.

POST/ng/v1/rcs/reports/messages

curl -X POST https://api.9bits.net/ng/v1/rcs/reports/messages \
  -H "Authorization: Bearer $NINEBITS_RCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDateTime": "2026-09-01 00:00",
    "endDateTime": "2026-09-02 23:59",
    "selectedStatus": "undelivered",
    "page": 1,
    "pageSize": 50
  }'

selectedStatus accepts all, delivered, undelivered, sent, queued, rejected and failed. An unrecognised value shows everything rather than nothing — so a typo produces a confusingly large result set, not an empty one.

Pass both timestamps explicitly

A missing or unparseable timestamp silently defaults to now instead of erroring. Omit startDateTime and you get a zero-width window, not “all time”.

Companion endpoints:

Endpoint	Returns
POST /ng/v1/rcs/reports/messages/kpi	Summary counts across the whole filter, not just the page.
POST /ng/v1/rcs/reports/messages/export	The full range as JSON rows plus a filename.
POST /ng/v1/rcs/reports/broadcasts	Your campaigns and their progress.
POST /ng/v1/rcs/reports/broadcasts/messages	Per-recipient drill-down for one campaign.
POST /ng/v1/rcs/reports/broadcasts/export	A real CSV file, named in Content-Disposition.

All of them are runnable in the API reference.

When there is no RCS

Undelivered on RCS often means the handset simply does not have it — not a transient failure worth retrying on the same channel.

The usual pattern is to fall back once, to SMS:

if (outcome === 'undelivered' && !message.smsFallbackSent) {
  await sendSms({ from: 'FirstDigits', to: [dest], content: message.plainText });
  await db.messages.updateOne({ referenceId: message_id },
    { $set: { smsFallbackSent: true } });
}

Guard it with a flag. Without one, a duplicate delivery report sends the SMS twice — see Idempotency & retries.