Fallback SMS Config

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.

Authentication

Authorization: Bearer tuco_sk_xxxxxxxxxxxxx

Body parameters

string

none, ghl, twilio or telnyx.

string

E.164. The number backup texts are sent from, and where replies come back to.

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.

string

Write only. Telnyx portal → Account → API Keys.

string

Write only. Telnyx portal → Account → Public Key. Without it, replies from your leads are rejected as unverified.

boolean

Also fall back on a technical send failure, not only when the recipient has no iMessage.

string

reschedule or fallback — what to do when the line hits its daily cap.

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

curl "https://app.tuco.ai/api/workspace/fallback-config" \
  -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx"

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

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

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

Response

{
  "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.

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" }'

{
  "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.

Overview

Webhooks

Errors and status codes

iMessage Availability

Messages

Voice / Calling

Replies

Lines & Leads

Campaigns

Analytics

Goal Bots

API Tools

Fallback SMS Config

Authentication

Body parameters

Examples

Response

Using your own Telnyx account

Error responses

Send a test

​Authentication

​Body parameters

​Examples

​Response

​Using your own Telnyx account

​Error responses

​Send a test

Authentication

Body parameters

Examples

Response

Using your own Telnyx account

Error responses

Send a test