Update Fallback SMS Config
curl --request PATCH \
--url https://app.tuco.ai/api/workspace/fallback-config \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fallbackDestination": "<string>",
"telnyxFromNumber": "<string>",
"telnyxUseOwnAccount": true,
"telnyxApiKey": "<string>",
"telnyxPublicKey": "<string>",
"sendFallbackSmsOnFailed": true,
"dailyLimitOverflow": "<string>",
"destination": "<string>",
"testPhone": "<string>"
}
'import requests
url = "https://app.tuco.ai/api/workspace/fallback-config"
payload = {
"fallbackDestination": "<string>",
"telnyxFromNumber": "<string>",
"telnyxUseOwnAccount": True,
"telnyxApiKey": "<string>",
"telnyxPublicKey": "<string>",
"sendFallbackSmsOnFailed": True,
"dailyLimitOverflow": "<string>",
"destination": "<string>",
"testPhone": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fallbackDestination: '<string>',
telnyxFromNumber: '<string>',
telnyxUseOwnAccount: true,
telnyxApiKey: '<string>',
telnyxPublicKey: '<string>',
sendFallbackSmsOnFailed: true,
dailyLimitOverflow: '<string>',
destination: '<string>',
testPhone: '<string>'
})
};
fetch('https://app.tuco.ai/api/workspace/fallback-config', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/workspace/fallback-config",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'fallbackDestination' => '<string>',
'telnyxFromNumber' => '<string>',
'telnyxUseOwnAccount' => true,
'telnyxApiKey' => '<string>',
'telnyxPublicKey' => '<string>',
'sendFallbackSmsOnFailed' => true,
'dailyLimitOverflow' => '<string>',
'destination' => '<string>',
'testPhone' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/workspace/fallback-config"
payload := strings.NewReader("{\n \"fallbackDestination\": \"<string>\",\n \"telnyxFromNumber\": \"<string>\",\n \"telnyxUseOwnAccount\": true,\n \"telnyxApiKey\": \"<string>\",\n \"telnyxPublicKey\": \"<string>\",\n \"sendFallbackSmsOnFailed\": true,\n \"dailyLimitOverflow\": \"<string>\",\n \"destination\": \"<string>\",\n \"testPhone\": \"<string>\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://app.tuco.ai/api/workspace/fallback-config")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"fallbackDestination\": \"<string>\",\n \"telnyxFromNumber\": \"<string>\",\n \"telnyxUseOwnAccount\": true,\n \"telnyxApiKey\": \"<string>\",\n \"telnyxPublicKey\": \"<string>\",\n \"sendFallbackSmsOnFailed\": true,\n \"dailyLimitOverflow\": \"<string>\",\n \"destination\": \"<string>\",\n \"testPhone\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/workspace/fallback-config")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fallbackDestination\": \"<string>\",\n \"telnyxFromNumber\": \"<string>\",\n \"telnyxUseOwnAccount\": true,\n \"telnyxApiKey\": \"<string>\",\n \"telnyxPublicKey\": \"<string>\",\n \"sendFallbackSmsOnFailed\": true,\n \"dailyLimitOverflow\": \"<string>\",\n \"destination\": \"<string>\",\n \"testPhone\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyMessages
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.
PATCH
/
api
/
workspace
/
fallback-config
Update Fallback SMS Config
curl --request PATCH \
--url https://app.tuco.ai/api/workspace/fallback-config \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fallbackDestination": "<string>",
"telnyxFromNumber": "<string>",
"telnyxUseOwnAccount": true,
"telnyxApiKey": "<string>",
"telnyxPublicKey": "<string>",
"sendFallbackSmsOnFailed": true,
"dailyLimitOverflow": "<string>",
"destination": "<string>",
"testPhone": "<string>"
}
'import requests
url = "https://app.tuco.ai/api/workspace/fallback-config"
payload = {
"fallbackDestination": "<string>",
"telnyxFromNumber": "<string>",
"telnyxUseOwnAccount": True,
"telnyxApiKey": "<string>",
"telnyxPublicKey": "<string>",
"sendFallbackSmsOnFailed": True,
"dailyLimitOverflow": "<string>",
"destination": "<string>",
"testPhone": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fallbackDestination: '<string>',
telnyxFromNumber: '<string>',
telnyxUseOwnAccount: true,
telnyxApiKey: '<string>',
telnyxPublicKey: '<string>',
sendFallbackSmsOnFailed: true,
dailyLimitOverflow: '<string>',
destination: '<string>',
testPhone: '<string>'
})
};
fetch('https://app.tuco.ai/api/workspace/fallback-config', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/workspace/fallback-config",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'fallbackDestination' => '<string>',
'telnyxFromNumber' => '<string>',
'telnyxUseOwnAccount' => true,
'telnyxApiKey' => '<string>',
'telnyxPublicKey' => '<string>',
'sendFallbackSmsOnFailed' => true,
'dailyLimitOverflow' => '<string>',
'destination' => '<string>',
'testPhone' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/workspace/fallback-config"
payload := strings.NewReader("{\n \"fallbackDestination\": \"<string>\",\n \"telnyxFromNumber\": \"<string>\",\n \"telnyxUseOwnAccount\": true,\n \"telnyxApiKey\": \"<string>\",\n \"telnyxPublicKey\": \"<string>\",\n \"sendFallbackSmsOnFailed\": true,\n \"dailyLimitOverflow\": \"<string>\",\n \"destination\": \"<string>\",\n \"testPhone\": \"<string>\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://app.tuco.ai/api/workspace/fallback-config")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"fallbackDestination\": \"<string>\",\n \"telnyxFromNumber\": \"<string>\",\n \"telnyxUseOwnAccount\": true,\n \"telnyxApiKey\": \"<string>\",\n \"telnyxPublicKey\": \"<string>\",\n \"sendFallbackSmsOnFailed\": true,\n \"dailyLimitOverflow\": \"<string>\",\n \"destination\": \"<string>\",\n \"testPhone\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/workspace/fallback-config")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fallbackDestination\": \"<string>\",\n \"telnyxFromNumber\": \"<string>\",\n \"telnyxUseOwnAccount\": true,\n \"telnyxApiKey\": \"<string>\",\n \"telnyxPublicKey\": \"<string>\",\n \"sendFallbackSmsOnFailed\": true,\n \"dailyLimitOverflow\": \"<string>\",\n \"destination\": \"<string>\",\n \"testPhone\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyEverything 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.
telnyxUseOwnAccount to false
deletes them.
Authentication
Pass your workspace API key as a Bearer token, or use a Clerk session token.Authorization: Bearer tuco_xxxxxxxxxxxxx
Request body
string
none, ghl, twilio or telnyx. none turns backup texts off entirely.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. Setting this to
false deletes any stored credentials.string
Write only. Telnyx portal → Account → API Keys. Never returned by
GET.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.
Setting this before a destination is configured returns
FALLBACK_NOT_CONFIGURED.string
reschedule or fallback — what to do when the line hits its daily cap.Examples
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
}'
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
}'
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 }'
Success (200 OK)
{
"success": true,
"fallbackDestination": "telnyx",
"sendFallbackSmsOnFailed": true
}
GET /api/workspace/fallback-config.
Using your own Telnyx account
Both keys are required together. The API key is checked with Telnyx before anything is stored, including thattelnyxFromNumber 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
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.string
required
Which destination to test:
ghl, twilio, telnyx, custom_webhook or campaign_ghl_path.string
E.164 number to send the test text to. Required for
ghl, twilio and telnyx.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" }'
{
"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 onPATCH 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 |