> For the complete documentation index, see [llms.txt](https://docs.taqnyat.sa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taqnyat.sa/api-reference/send-templates/send-failover-message.md).

# Send Failover Message

Use this API to send a WhatsApp template message with a fallback channel.

If the WhatsApp message fails because of an error returned from Meta, such as when the recipient does not have a WhatsApp account, Taqnyat can automatically attempt delivery through **SMS** or **Email**, depending on the fallback options included in the request.

### Endpoint

The current failover example uses:

```
GET /messages/?campaignName=<CAMPAIGN_NAME>
```

Full URL:

```
https://api.taqnyat.sa/wa/v2/messages/?campaignName=<CAMPAIGN_NAME>
```

### Authentication

Include your Bearer Token in the request header:

```
Authorization: Bearer <YOUR_TOKEN>Content-Type: application/json
```

The token must be enabled for the services used in the failover flow, such as WhatsApp, SMS, and Email.

### Request Parameters

| Parameter                | Type   | Required           | Description                                                                                           |
| ------------------------ | ------ | ------------------ | ----------------------------------------------------------------------------------------------------- |
| `campaignName`           | String | Yes                | Campaign name used for the failover request. It should remain consistent across the sending channels. |
| `to`                     | String | Yes                | Recipient phone number in international format.                                                       |
| `type`                   | String | Yes                | Must be `template` for the WhatsApp message.                                                          |
| `template.name`          | String | Yes                | Name of the approved WhatsApp template.                                                               |
| `template.language.code` | String | Yes                | Language code of the approved template.                                                               |
| `sms`                    | Object | No                 | SMS fallback configuration.                                                                           |
| `sms.sender`             | String | When SMS is used   | Approved SMS sender name.                                                                             |
| `sms.campaign`           | String | When SMS is used   | Campaign name for the SMS fallback.                                                                   |
| `sms.body`               | String | When SMS is used   | SMS message content.                                                                                  |
| `mail`                   | Object | No                 | Email fallback configuration.                                                                         |
| `mail.from`              | String | When Email is used | Sender email address.                                                                                 |
| `mail.to`                | String | When Email is used | Recipient email address.                                                                              |
| `mail.cc`                | String | No                 | CC email address.                                                                                     |
| `mail.campaign`          | String | When Email is used | Campaign name for the email fallback.                                                                 |
| `mail.subject`           | String | When Email is used | Email subject.                                                                                        |
| `mail.msg`               | String | When Email is used | Email message body.                                                                                   |
| `sendEmailIfFail`        | Object | No                 | Sends an email if the preceding delivery channel fails.                                               |

The public reference specifically notes that Email fallback requires the customer to be subscribed to the Email service and to have a valid Email token enabled.

### Example Payload

{% code overflow="wrap" expandable="true" %}

```json
{
  "to": "9665XXXXXXXX",
  "type": "template",
  "template": {
    "language": {
      "code": "ar"
    },
    "name": "<TEMPLATE_NAME>"
  },
  "sms": {
    "sender": "<SENDER_NAME>",
    "campaign": "<CAMPAIGN_NAME>",
    "body": "Type your SMS message",
    "sendEmailIfFail": {
      "from": "<SENDER_EMAIL>",
      "to": "customer@example.com"
    }
  },
  "mail": {
    "from": "<SENDER_EMAIL>",
    "to": "customer@example.com",
    "cc": "cc@example.com",
    "campaign": "<CAMPAIGN_NAME>",
    "subject": "Type your subject",
    "msg": "Type your email message",
    "sendEmailIfFail": {
      "from": "<SENDER_EMAIL>",
      "to": "customer@example.com"
    }
  }
}
```

{% endcode %}

### Example Request

Using the method shown in the current public cURL example:

{% code overflow="wrap" expandable="true" %}

```bash
curl --location --request GET \
'https://api.taqnyat.sa/wa/v2/messages/?campaignName=<CAMPAIGN_NAME>' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "to": "9665XXXXXXXX",
  "type": "template",
  "template": {
    "language": {
      "code": "ar"
    },
    "name": "<TEMPLATE_NAME>"
  },
  "sms": {
    "sender": "<SENDER_NAME>",
    "campaign": "<CAMPAIGN_NAME>",
    "body": "Type your SMS message",
    "sendEmailIfFail": {
      "from": "<SENDER_EMAIL>",
      "to": "customer@example.com"
    }
  },
  "mail": {
    "from": "<SENDER_EMAIL>",
    "to": "customer@example.com",
    "cc": "cc@example.com",
    "campaign": "<CAMPAIGN_NAME>",
    "subject": "Type your subject",
    "msg": "Type your email message"
  }
}'
```

{% endcode %}

### Failover Flow

The intended flow is:

<pre data-overflow="wrap" data-expandable="true"><code>WhatsApp Template       
            ↓
WhatsApp delivery fails       
<strong>            ↓
</strong><strong>Configured fallback channel       
</strong>            ↓
SMS and/or Email
</code></pre>

### Example Response

A successful WhatsApp submission returns the message ID and recipient:

{% code overflow="wrap" expandable="true" %}

```json
{
  "type": "template",
  "statuses": {
    "message_id": "<MESSAGE_ID>",
    "recipient": "+9665XXXXXXXX"
  }
}
```

{% endcode %}

### Common Errors

#### Campaign Name Already Used

```json
{
  "message": "402",
  "reason": "Campaign name already used"
}
```

#### Invalid Recipient

```json
{
  "message": "402",
  "reason": "Invalid recipient"
}
```

#### Invalid Token

```json
{
  "message": "401",
  "reason": "No such bot/bearer combination"
}
```

#### Invalid Template Name or Language

```json
{
  "message": "132001",
  "reason": "(#132001) Template name does not exist in the translationn"
}
```

### Notes

The campaign name should remain consistent across the failover channels. Make sure the account is subscribed to and has valid credentials for every fallback service you plan to use.