Plan RCS capability checks and SMS fallback

Use a Bird Navigator when RCS and SMS should form one delivery chain. A direct send to an RCS channel targets that channel; a send to a configured navigator lets Bird choose and track the channel attempts. The Navigator fallback reference defines that behavior.

Decide what must reach the customer

An appointment reminder needs a date, location and working appointment link even when a recipient cannot receive the card. Write the SMS version as its own message and check SMS character limits. Keep the appointment record authoritative when a customer opens an old reminder.

Prepare an RCS agent launched for the intended countries/carriers, the navigator's SMS senders and the customer's channel preferences. Suppressions are recorded per platform. When adding RCS to an existing audience, carry the applicable opt-outs into RCS before sending; an SMS-only suppression does not automatically become an RCS suppression. The fallback reference includes the export/import procedure and scope fields.

Choose when to use the alternate channel

For a use-case-messaging navigator, put the RCS channel in settings.ottChannels and scope it to its launch countries. The following settings illustrate a transactional navigator with an agent launched in the UK; substitute your own channel and countries:

Code example

{
  "useCaseType": "transactional",
  "ottChannels": [
    {
      "channelId": "00000000-0000-4000-8000-000000000001",
      "countries": ["GB"]
    }
  ]
}

Use the navigator configuration reference to create or update your navigator. A settings update replaces the whole settings object, so retain all existing settings you intend to keep, including useCaseType. Confirm the resulting sender order with GET /workspaces/{workspaceId}/navigators/{navigatorId}/coverage. The enrolled OTT channels run in the configured order before SMS; country scoping keeps the RCS agent within its launch markets.

Start with a text reminder that both routes can carry. Use the access key, workspace and own test recipient from the RCS quickstart, set your configured navigator ID, and run:

Code example

export BIRD_NAVIGATOR_ID='replace-with-your-navigator-id'
jq -n --arg to "$RCS_RECIPIENT" --arg url "$APPOINTMENT_URL" '{
  receiver: {contacts: [{identifierKey: "phonenumber", identifierValue: $to}]},
  reference: "appointment-fallback-demo-001",
  body: {type: "text", text: {
    text: ("Your studio visit is Tuesday at 10:00, Riverside Studio. View appointment: " + $url)
  }}
}' > rcs-navigator-message.json

curl --fail-with-body --silent --show-error --request POST \
  "https://api.bird.com/workspaces/$BIRD_WORKSPACE_ID/navigators/$BIRD_NAVIGATOR_ID/messages" \
  --header "Authorization: AccessKey $BIRD_ACCESS_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @rcs-navigator-message.json > rcs-navigator-result.json
jq -e '{id, status, navigatorData}' rcs-navigator-result.json

To send a rich RCS card while keeping the authored SMS text, add a templates object to this request with the platform key rcs-google. Point it to your published RCS template and its declared parameters. Platforms with a matching entry use that template; the SMS route uses body:

Code example

{
  "rcs-google": {
    "projectId": "replace-with-rcs-template-project-id",
    "version": "replace-with-published-version",
    "locale": "en"
  }
}

The navigator responds with 202 Accepted and performs the delivery work asynchronously. These are the important decisions:

Observed outcome	Navigator behavior and application action
RCS attempt is pending	Observe the same navigator message. A slow response does not establish failure.
RCS attempt reaches sending_failed or delivery_failed	The navigator tries its next configured channel, subject to recipient/message-wide stops below.
RCS agent cannot reach the destination	Inspect the failure, launch scope and next attempt. This can reflect carrier launch scope as well as recipient reach.
Recipient opt-out (15016) or holdout rejection	The chain stops; an alternate channel does not bypass that rejection.
Navigator reports delivered	The chain delivered. Inspect attempts to see whether RCS or SMS succeeded.
No read or click is observed	This is engagement evidence, not a delivery failure that triggers another send.

A device capability check, a carrier launch result and an RCS subscription are different signals. For a no-code audience branch, Bird's RCS Journey procedure uses RCS subscription → Boolean → Is true: send the RCS template on the true branch and an SMS/email template on Else. That branch checks a contact property; it is not a live device-feature probe or a failed-delivery fallback. Use the navigator for the delivery chain described here.

Prevent duplicate reminders

Give the reminder one business task ID and save the navigator message ID returned by the send. Let the navigator own its channel retries; an application timer must not launch a second SMS chain while the first is pending. reference correlates records but does not deduplicate a repeated POST.

Subscribe to navigator.outbound for the chain's status, filtered by navigatorId. Use rcs-google.outbound or SMS channel events for individual-leg diagnostics. Follow the subscription and monitoring example and verify notification signatures. Keep the application task and all attempt IDs together when callbacks arrive late.

Replies are received on rcs-google.inbound; they do not carry navigator information in meta. Resolve the customer's reply against the saved contact and current application task instead of assuming it contains the navigator ID.

Test both paths

Send a native RCS case, a destination that causes a definite RCS reach failure, and an opted-out test contact. Check the phone and the recorded chain. The reach failure should show the eligible next attempt; the opt-out should stop the chain. Also exercise a delayed result without allowing an application timer to send again.

Code example

NAVIGATOR_MESSAGE_ID=$(jq -er '.id' rcs-navigator-result.json)
curl --fail-with-body --silent --show-error \
  "https://api.bird.com/workspaces/$BIRD_WORKSPACE_ID/navigators/$BIRD_NAVIGATOR_ID/messages/$NAVIGATOR_MESSAGE_ID" \
  --header "Authorization: AccessKey $BIRD_ACCESS_KEY" > rcs-navigator-status.json
jq '{id, status, attempts: .navigatorData.attempts}' rcs-navigator-status.json

navigatorData.attempts records each channel's channelId, platformId, messageId, status and failure. The top-level status is the result of the whole chain: a failed RCS attempt followed by delivered SMS is a delivered navigator message. An attempt rejected before reaching a platform can have an all-zero message ID; there is no channel message to fetch for that attempt.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Understand the conceptWhat Is RCS for Business?Explore the capabilityRCS

Get an implementation brief