RCS API Logo

Fallback

Create development account

Since RCS requires that the recipient's device and carrier support the technology, fallback logic is used to guarantee delivery (for example, by automatically switching to standard SMS text) if an RCS message cannot be delivered.

Overview: Where is the fallback logic? #

In the API specification, fallback is integrated at two levels:

  1. Configuration (Requests): When sending messages, you specify instructions on how the system should act if RCS fails.
  2. Status follow-up (Responses): When fetching data about sent messages, you can see the exact status and reason for any fallback.

1. Configuring Fallback for Sending (Requests) #

Fallback settings can be defined in three central POST-endpoints when messages are initiated. These endpoints use the data structures Bundle Request, Conversation Request oh Message Request:

  • POST /bundles – Creates a bundle of messages to one or more recipients.
  • POST /conversations – Starts a new two-way conversation with an initial message.
  • POST /conversations/{conversation} - Sending a new message in an ongoing conversation.

Configuration parameters #

The following parameters are included in the JSON body to control the fallback behavior:

ParameterTypeDescription of the project
fallback policyEnumDetermines which strategy/policy to apply. Refers to FallbackPolicy (valid values: NoFallback, FallbackOnNoCapability, FallbackOnFailure, FallbackAfterTimeout, CustomerControlledFallback). Add multiple policies by separating each individual policy with a comma.
fallbackTimeoutSecondsIntegerTime in seconds that the system waits for a delivery report from RCS before the fallback message is triggered.
• Minimum 1
• Maximum: 2147483647
fallback messagestringThe actual text message (e.g., SMS) to be sent if fallback is activated.
• Maximum length: 160 characters (corresponds to the standard length of 1 SMS). The fallback message is auto-generated from Content or Card if not explicitly specified in the call.

2. Follow-up and Status (Responses & GET) #

When reviewing sent messages or bundles via the API GET-endpoints, the object is included RcsMessageFallback in the response to report how the fallback has been handled.

This is available via, among other things:

  • GET /bundles/{bundle}
  • GET /bundles/{bundle}/messages
  • GET /conversations/{conversation}/messages
  • GET /conversations/{conversation}/messages/{id}

Data structures RcsMessageFallback #

When reading a message, the following fields are returned in the fallback object:

FieldTypeDescription of the project
fallback policyText (enum)The policy that is active for the message (NoFallback, FallbackOnNoCapability, FallbackOnFailure, FallbackAfterTimeout, CustomerControlledFallback).
fallback timeoutstring (date range)The time span/setting specified when setting up the request.
fallback messagestringThe text provided in the request.
fallback statusEnumCurrent status of the fallback delivery. Refers to Fallback Status (valid values: Unknown, Pending, Sent, Completed, Failed).
fallback reasonstringSystem error message or description of why fallback was activated (e.g. ”Recipient lacks RCS capability”).
fallbackMessageIdStringObjectId)The unique ID of the generated fallback message (e.g., the Batch ID in the underlying SMS gateway) to enable tracking.

3. Enum definitions #

FallbackPolicy #

Used in requests to select fallback behavior.

  • Values: NoFallback, FallbackOnNoCapability, FallbackOnFailure, FallbackAfterTimeout, CustomerControlledFallback.

Fallback Status #

Used in responses to show where in the process the fallback message is located.

  • Values: Unknown, Pending, Sent, Completed, Failed.
Contents