> ## Documentation Index
> Fetch the complete documentation index at: https://onextel-09023014.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Fallback API

> Send a message on a primary channel (SMS, RCS, or WhatsApp) with automatic fallback to secondary channels in a single API call.

The Fallback API is part of the OmniChannel Send API. It lets you send messages with
fallback across primary channels — **SMS**, **RCS**, and **WhatsApp** — in a single API
call. If the primary channel fails to deliver within the configured wait time, the
platform retries on the fallback channel(s) you define.

## Endpoint

```
POST https://api.onexaura.com/oapi/send_sms
```

> [!NOTE]
>
> The Fallback API uses the same endpoint as the OmniChannel send API. Fallback behavior
> is activated by including the `fallback` object in the request body.

## Headers

**apikey** `string` *required*

API key issued by OneXtel, used for authentication.

## Request body

The request body is a JSON object. Each top-level key represents a messaging channel.
You may use any one of `sms`, `wa`, or `rcs` as your primary channel, plus a `fallback`
object defining the fallback behavior.

### `sms` — SMS channel (array of objects)

**sms\[].sender** `string` *required*

SMS sender ID.

**sms\[].recipient** `string` *required*

Recipient phone number.

**sms\[].type** `string` *required*

Message type. Verified accepted on the SMS send API: `SI`, `OTP`, `SE`. Case-sensitive.

> [!WARNING]
>
> **Neither `TXN` nor `TRANS` is a valid message type**, despite both having appeared in earlier
> example payloads. Live testing of the SMS send API (Aug 2026) accepts only `SI`, `OTP`, and
> `SE`; `TXN`, `TRANS`, and `Promo` are rejected as `invalid type`.
>
> This matters more in fallback than in a direct send: an invalid `type` here is rejected at the
> **fallback** stage, long after the primary send returned `200`, so the symptom is a successful
> API response and no SMS. Use `SI` or `SE` for service messages — see
> [DLT template types](/guides/sms/dlt#template-types).

> [!NOTE]
>
> The accepted set was verified on the send API, not on the fallback object specifically. If a
> fallback SMS is still not arriving with a valid `type`, confirm the fallback validator uses the
> same set.

**sms\[].messageBody** `string` *required*

Message content.

**sms\[].templateId** `string`

DLT template ID. Optional only when template auto-match is enabled on the API key; otherwise
required for DLT-registered SMS in India.

**sms\[].entityId** `string`

DLT entity ID. Optional only when template auto-match is enabled on the API key; otherwise
required for DLT-registered SMS in India.

> [!NOTE]
>
> With template auto-match enabled on the API key, OneXtel matches `messageBody` against your
> registered DLT templates and fills in `templateId` and `entityId`. When you do pass both, they
> are used as sent.

**sms\[].unicode** `number`

`0` or `1` — enable Unicode encoding. Optional.

**sms\[].custRef1** `object`

Optional custom reference fields for tracking or tagging (e.g. `CustomReference1`,
`CustomReference2`).

### `wa` — WhatsApp channel (array of objects)

**wa\[].messaging\_product** `string` *required*

Always `"whatsapp"`.

**wa\[].recipient\_type** `string` *required*

Always `"individual"`.

**wa\[].recipient** `array` *required*

Array of recipient phone numbers.

**wa\[].sender** `string` *required*

WhatsApp sender number. A Pool ID can also be passed.

**wa\[].type** `string` *required*

Always `"template"`.

**wa\[].template** `object` *required*

Object with `name`, `language.code` (the template language), and `components`. Uses the
same payload structure as the WhatsApp Template Message API.

**wa\[].custref1** `string`

Custom reference fields for tracking: `custref1` through `custref5`. Optional.

### `rcs` — RCS channel (array of objects)

**rcs\[].sender** `string` *required*

RCS sender ID.

**rcs\[].messageType** `string` *required*

Message type.

**rcs\[].recipient** `string` *required*

Recipient phone number.

**rcs\[].contentMessage** `object` *required*

Contains `templateMessage`, an object with `templateCode` and `customParams`. Uses the
same payload structure as the RCS Template Message API.

**rcs\[].custref1** `string`

Custom reference fields for tracking: `custref1` through `custref5`. Optional.

### `fallback` — fallback configuration (object)

Defines fallback behavior when the primary channel fails to deliver.

**fallback.fallback\_id** `string` *required*

Fallback configuration ID.

**fallback.fallback** `boolean` *required*

Set to `true` to enable fallback.

**fallback.waittime** `string` *required*

Maximum time (in seconds) to wait for Delivery / Failure before triggering fallback. If the
primary message carries a `ttl` longer than this wait time, the wait time overrides the TTL, so
the primary attempt ends when fallback fires and the recipient does not get both messages.

**fallback.sms** `object`

SMS fallback object: `sender`, `type`, `messageBody` plus optional `unicode`,
`templateId`, `entityId`, and `custRef1`–`custRef5`. Include as per your fallback
configuration. `templateId` and `entityId` follow the same auto-match rule as the `sms`
channel above.

**fallback.wa** `object`

WhatsApp fallback object: `sender`, `template`, `languageCode`, `templateComponents`
(same payload structure as the WhatsApp Template Message API) plus optional
`custref1`–`custref5`. Include as per your fallback configuration.

**fallback.rcs** `object`

RCS fallback object: `sender`, `messageType`, `templateCode`, `customParams` (same
payload structure as the RCS Template Message API) plus optional
`custref1`–`custref5`. Include as per your fallback configuration.

> [!NOTE]
>
> Fallback Channel 1 and Fallback Channel 2 details can be added as per your fallback
> configuration. If a third-party fallback is used, dynamic keys can be added with the
> specific channel name.

### Optional top-level fields

**prefix** `string`

Phone number prefix, e.g. `"+91"`. Optional.

**campaignName** `string`

Campaign identifier string. Optional.

**urlShortener** `object`

Object with `flag` (set to `1` — mandatory if a URL shortener is required in the
message body) and a `urlDetails` array. Each `urlDetails` item contains `longUrl`
(mandatory when `flag` is `1`), `domain` (optional), and `track_user` (optional).

## Example request

The example below sends a WhatsApp template message as the primary channel with SMS
configured as the fallback channel.

```bash cURL theme={null}
curl --request POST \
  --url https://api.onexaura.com/oapi/send_sms \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "wa": [
    {
      "messaging_product": "whatsapp",
      "recipient_type": "individual",
      "recipient": [
        "919999999999",
        "919999999998"
      ],
      "sender": "YOUR_WA_SENDER",
      "type": "template",
      "template": {
        "name": "YOUR_TEMPLATE_NAME",
        "language": {
          "code": "en"
        },
        "components": []
      }
    }
  ],
  "fallback": {
    "fallback_id": "YOUR_FALLBACK_ID",
    "fallback": true,
    "waittime": "30",
    "sms": {
      "sender": "YOUR_SMS_SENDER",
      "type": "SI",
      "messageBody": "Your message text",
      "templateId": "YOUR_DLT_TEMPLATE_ID",
      "entityId": "YOUR_DLT_ENTITY_ID"
    }
  }
}'
```

```json Request body (all channels) theme={null}
{
  "sms": [
    {
      "sender": "YOUR_SMS_SENDER",
      "recipient": "919999999999",
      "type": "SI",
      "messageBody": "Your message text",
      "templateId": "YOUR_DLT_TEMPLATE_ID",
      "entityId": "YOUR_DLT_ENTITY_ID",
      "unicode": 0,
      "custRef1": {
        "CustomReference1": "",
        "CustomReference2": ""
      }
    }
  ],
  "wa": [
    {
      "messaging_product": "whatsapp",
      "recipient_type": "individual",
      "recipient": [
        "919999999999",
        "919999999998"
      ],
      "sender": "YOUR_WA_SENDER",
      "type": "template",
      "template": {
        "name": "YOUR_TEMPLATE_NAME",
        "language": {
          "code": "en"
        },
        "components": []
      }
    }
  ],
  "rcs": [
    {
      "sender": "YOUR_RCS_SENDER",
      "messageType": "template",
      "recipient": "919999999999",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "YOUR_TEMPLATE_CODE",
          "customParams": "{}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "fallback": {
    "fallback_id": "YOUR_FALLBACK_ID",
    "fallback": true,
    "waittime": "30",
    "sms": {
      "sender": "YOUR_SMS_SENDER",
      "type": "SI",
      "messageBody": "Your message text",
      "unicode": 0,
      "templateId": "YOUR_DLT_TEMPLATE_ID",
      "entityId": "YOUR_DLT_ENTITY_ID"
    },
    "wa": {
      "sender": "YOUR_WA_SENDER",
      "template": "YOUR_TEMPLATE_NAME",
      "languageCode": "en",
      "templateComponents": []
    },
    "rcs": {
      "sender": "YOUR_RCS_SENDER",
      "messageType": "template",
      "templateCode": "YOUR_TEMPLATE_CODE",
      "customParams": "{}"
    }
  }
}
```

> [!TIP]
>
> Include only the channel array (`sms`, `wa`, or `rcs`) that you want as the primary
> channel, and only the fallback channel objects that match your fallback configuration.
> The example under "Request body (all channels)" shows every supported block in one
> payload for reference.


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