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

# Fallback SMS Config

> Read and change where backup SMS is sent when iMessage fails, including connecting your own Telnyx account. Bearer-token auth, JSON request and response.

<Note>
  Everything on the **Settings → Fallbacks** page is available here, so backup SMS can be set up entirely over the API without opening the dashboard.

  A backup text goes out when iMessage cannot deliver, for two separate reasons: the send failed technically, or the recipient has no iMessage. Both use the same destination.
</Note>

## Authentication

```bash theme={null}
Authorization: Bearer tuco_sk_xxxxxxxxxxxxx
```

## Body parameters

<ParamField body="fallbackDestination" type="string">`none`, `ghl`, `twilio` or `telnyx`.</ParamField>
<ParamField body="telnyxFromNumber" type="string">E.164. The number backup texts are sent from, and where replies come back to.</ParamField>
<ParamField body="telnyxUseOwnAccount" type="boolean" default="false">Send on your own Telnyx account instead of Tuco's, keeping the number, the 10DLC registration and the billing under your brand.</ParamField>
<ParamField body="telnyxApiKey" type="string">Write only. Telnyx portal → Account → API Keys.</ParamField>
<ParamField body="telnyxPublicKey" type="string">Write only. Telnyx portal → Account → Public Key. Without it, replies from your leads are rejected as unverified.</ParamField>
<ParamField body="sendFallbackSmsOnFailed" type="boolean">Also fall back on a technical send failure, not only when the recipient has no iMessage.</ParamField>
<ParamField body="dailyLimitOverflow" type="string">`reschedule` or `fallback` — what to do when the line hits its daily cap.</ParamField>

Credentials are **never returned**. `GET` reports only `telnyxHasOwnApiKey` and `telnyxHasOwnPublicKey`, which say whether one is stored and nothing more.

Omitting a credential leaves the stored one untouched, so you can change the number without re-sending keys. Setting `telnyxUseOwnAccount` to `false` deletes them.

***

## Examples

<CodeGroup>
  ```bash Read the current config theme={null}
  curl "https://app.tuco.ai/api/workspace/fallback-config" \
    -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx"
  ```

  ```bash Use Tuco's Telnyx account theme={null}
  curl -X PATCH "https://app.tuco.ai/api/workspace/fallback-config" \
    -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "fallbackDestination": "telnyx",
      "telnyxFromNumber": "+13055550142",
      "sendFallbackSmsOnFailed": true
    }'
  ```

  ```bash Use your own Telnyx account theme={null}
  curl -X PATCH "https://app.tuco.ai/api/workspace/fallback-config" \
    -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "fallbackDestination": "telnyx",
      "telnyxUseOwnAccount": true,
      "telnyxApiKey": "KEY0197...",
      "telnyxPublicKey": "base64publickey...",
      "telnyxFromNumber": "+13055550142",
      "sendFallbackSmsOnFailed": true
    }'
  ```

  ```bash Go back to Tuco's account theme={null}
  curl -X PATCH "https://app.tuco.ai/api/workspace/fallback-config" \
    -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "fallbackDestination": "telnyx", "telnyxUseOwnAccount": false }'
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "fallbackDestination": "telnyx",
  "telnyxFromNumber": "+13055550142",
  "telnyxUseOwnAccount": true,
  "telnyxHasOwnApiKey": true,
  "telnyxHasOwnPublicKey": true,
  "sendFallbackSmsOnFailed": true,
  "dailyLimitOverflow": "reschedule"
}
```

## Using your own Telnyx account

Both keys are required together. The API key is checked with Telnyx before anything is stored, including that `telnyxFromNumber` is a number on that account — so a wrong key fails here rather than the first time a text needs to go out.

Replies only reach you once Telnyx knows where to send them. In Telnyx, go to **Messaging → Messaging Profiles → your profile → Inbound Settings**, set the **Webhook URL** to:

```
https://app.tuco.ai/api/webhooks/telnyx-inbound
```

and set **API version** to `2`. The URL is the same for everyone; replies are matched to you by `telnyxFromNumber`.

## Error responses

| Code                            | Meaning                                                               |
| ------------------------------- | --------------------------------------------------------------------- |
| `TELNYX_KEY_INVALID`            | Telnyx rejected the API key                                           |
| `TELNYX_NUMBER_NOT_ON_ACCOUNT`  | The key is valid but `telnyxFromNumber` is not on that account        |
| `TELNYX_CREDENTIALS_INCOMPLETE` | `telnyxUseOwnAccount` is `true` but a key is missing                  |
| `TELNYX_UNREACHABLE`            | Telnyx could not be reached to verify the key                         |
| `TELNYX_ERROR`                  | Telnyx returned an unexpected status while verifying the key          |
| `ENCRYPTION_NOT_CONFIGURED`     | Credentials cannot be stored safely — contact support                 |
| `FALLBACK_NOT_CONFIGURED`       | `sendFallbackSmsOnFailed` was set before a destination was configured |
| `INVALID_URL`                   | `customWebhookUrl` is not a valid URL                                 |

## Send a test

Sends a real text through the saved settings, so it proves the credentials and the number together. It reads what is **stored**, so save first.

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/workspace/fallback-config/test" \
  -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "telnyx", "testPhone": "+13055550199" }'
```

```json theme={null}
{
  "ok": true,
  "destination": "telnyx",
  "details": { "sentTo": "+13055550199", "account": "your Telnyx account" }
}
```

`details.account` tells you which account it actually went out on, so you can confirm you are on your own rather than Tuco's.