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
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.Write only. Telnyx portal → Account → Public Key. Without it, replies from your leads are
rejected as unverified.
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.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.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 |