> ## 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.

# Update Fallback SMS Config

> 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>

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

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

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

***

## Request body

<ParamField body="fallbackDestination" type="string">
  `none`, `ghl`, `twilio` or `telnyx`. `none` turns backup texts off entirely.
</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. Setting this to `false` deletes any stored credentials.
</ParamField>

<ParamField body="telnyxApiKey" type="string">
  **Write only.** Telnyx portal → Account → API Keys. Never returned by `GET`.
</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.
  Setting this before a destination is configured returns `FALLBACK_NOT_CONFIGURED`.
</ParamField>

<ParamField body="dailyLimitOverflow" type="string">
  `reschedule` or `fallback` — what to do when the line hits its daily cap.
</ParamField>

***

## Examples

<CodeGroup>
  ```bash Use Tuco's Telnyx account theme={null}
  curl -X PATCH "https://app.tuco.ai/api/workspace/fallback-config" \
    -H "Authorization: Bearer tuco_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_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_xxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "fallbackDestination": "telnyx", "telnyxUseOwnAccount": false }'
  ```
</CodeGroup>

### Success (`200 OK`)

```json theme={null}
{
  "success": true,
  "fallbackDestination": "telnyx",
  "sendFallbackSmsOnFailed": true
}
```

Read the full config back with
[`GET /api/workspace/fallback-config`](/api-reference/endpoint/fallback-config).

***

## 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`.

***

## Send a test

Sends a real text through the **saved** settings, so it proves the credentials and the number
together. Save first — it reads what is stored, not what you pass.

<ParamField body="destination" type="string" required>
  Which destination to test: `ghl`, `twilio`, `telnyx`, `custom_webhook` or `campaign_ghl_path`.
</ParamField>

<ParamField body="testPhone" type="string">
  E.164 number to send the test text to. Required for `ghl`, `twilio` and `telnyx`.
</ParamField>

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/workspace/fallback-config/test" \
  -H "Authorization: Bearer tuco_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.

***

## Error codes

Returned on `PATCH` as `{ "error": "...", "code": "..." }`.

| 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 |


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