> ## Documentation Index
> Fetch the complete documentation index at: https://smerio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan RCS messages and fallback

> Keep rich RCS content, choose an explicit fallback sequence and inspect delivery attempts.

A message has one identity and can have several delivery attempts. Start with RCS and add SMS or MMS only when that fallback is useful for your campaign.

> [!NOTE]
>
> Live sending requires an activated sender and an enabled workspace connection. Preparing a channel plan or saving setup details does not activate a channel. Existing test API keys cannot send live messages.

## Choose the content for each channel

Send a structured plan to `POST /api/messaging/messages` with an `Idempotency-Key` header. Use your own workspace sender identifiers.

```json theme={null}
{
  "to": "+12025550123",
  "environment": "test",
  "channels": [
    {
      "channel": "rcs",
      "sender_id": "sender_rcs_test",
      "content": {
        "type": "text",
        "text": "Your order is ready to collect.",
        "suggestions": [
          {
            "type": "url",
            "text": "Collection details",
            "url": "https://example.com/collection"
          }
        ]
      }
    },
    {
      "channel": "sms",
      "sender_id": "sender_sms_test",
      "content": {
        "type": "text",
        "text": "Your order is ready. Collection details: https://example.com/collection"
      }
    }
  ],
  "fallback": {
    "on": ["unavailable", "failed", "expired"]
  }
}
```

The sequence is explicit and each channel can appear once. SMS needs its own text. MMS needs its own media URLs and optional text. Smerio does not silently turn a rich card into a text message or remove actions to make content fit.

RCS supports text, file references, rich cards and carousels in the structured API. An RCS-only message contains one RCS step and omits `fallback`. This is useful when the content would lose its purpose in SMS.

In the test environment, messages remain inside the workspace. The first step is processed locally. This does not check a phone's capabilities or prove that a fallback can be delivered.

## Decide when fallback is allowed

| Trigger | Meaning |
| - | - |
| `unavailable` | A capability check confirms that the recipient cannot receive RCS from the selected sender. |
| `failed` | A trusted delivery result confirms a failed attempt. |
| `expired` | A trusted delivery result confirms that the attempt expired. |

Choose only the triggers you want. A timeout, missing receipt or unknown result does not prove that a message failed. Smerio keeps that outcome unresolved and does not automatically send the next channel.

A late success cancels a fallback that is still queued. A message already handed to a network cannot be recalled. Review attempts when investigating delayed or conflicting results.

## Estimate RCS coverage

Use `POST /api/messaging/coverage` before deciding whether to run an RCS-only audience or prepare fallback content.

```json theme={null}
{
  "sender_id": "sender_rcs_ready",
  "recipients": ["+12025550123", "+12025550124"]
}
```

The response includes `checked_at`, recipient results and three counts:

* **Eligible:** the check found RCS capability for this sender.
* **Unavailable:** the check returned an unavailable result.
* **Unknown:** readiness or a capability result could not be established.

Each request accepts up to 100 numbers. Repeated numbers count once. A sender that is not ready returns unknown coverage. A failed lookup does not turn unknown recipients into unavailable recipients.

Coverage is a timestamped estimate. Devices and networks can change, and `guarantees_delivery` is always `false`. This endpoint does not launch a broadcast or send messages.

## Inspect what happened

Read the message with `GET /api/messaging/messages/{id}`. A structured message includes:

* **Attempts:** channel, status, timestamps, explicit content and a useful error code when available.
* **Events:** the normalized history of each attempt.
* **Delivery channel:** the channel confirmed as delivered, or `null` while unconfirmed.

`pending`, `sent` and `unknown` are not handset-delivery confirmation. In the [Inbox](https://smerio.com/docs/workspace/inbox.md), open **Message details** to inspect the same history. An SMS fallback shows its own text and the channel that delivered it.

For RCS and SMS, `POST /api/messaging/messages/{id}/attempts/{attemptId}/reconcile` refreshes the state from delivery logs. It does not resend. MMS delivery lookup is not available through this endpoint yet.

Use the [generated OpenAPI contract](https://smerio.com/hub/openapi.json) for the complete schemas. Test keys use bearer authentication and remain restricted to test sending. Live API activation is a separate readiness step.

Some connections return compatibility results asynchronously. A first lookup can return `reason: capability_pending` with unknown recipients. Query again after the callback arrives. Observations are reused for five minutes. Partial support remains unknown for arbitrary rich content, and no compatibility result guarantees delivery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.