Telnyx Messaging — Full Documentation

SMS, MMS, RCS, WhatsApp, short codes, 10DLC compliance, and messaging profiles. Complete page content for the Messaging section of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this section: https://developers.telnyx.com/development/llms/messaging-llms-txt.md

SMS & MMS

Send Your First Message

Source: https://developers.telnyx.com/docs/messaging/messages/send-message.md

Send your first SMS using the Telnyx Messaging API. This guide takes you from zero to sending a message in about 5 minutes by testing between two Telnyx numbers—no carrier registration required.

Prerequisites

A Telnyx account (free to create)

1. Get two phone numbers

Purchase two Telnyx numbers so you can test messaging between them without registration requirements. Navigate to Numbers > Search & Buy in the portal. Enter your preferred area code or region, check SMS under features, and click Search. Click Add to Cart on two numbers, then Place Order. Having two numbers lets you test on-net (Telnyx-to-Telnyx) messaging immediately, and also test receiving inbound messages.

2. Create a Messaging Profile

Navigate to Messaging in the portal. Click Add new profile, give it a name (e.g., “My App”), and click Save. Go to My Numbers, and for each number, click the Messaging Profile dropdown, select your profile, and save.

3. Get your API key

Go to API Keys and copy your API key (or create one if needed).

4. Send a message

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Hello, world!"
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Hello, world!'
});

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.send(
    from_="+15551234567",
    to="+15559876543",
    text="Hello, world!"
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: "+15559876543",
  text: "Hello, world!"
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From: "+15551234567",
    To:   "+15559876543",
    Text: "Hello, world!",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendParams params = MessageSendParams.builder()
            .from("+15551234567")
            .to("+15559876543")
            .text("Hello, world!")
            .build();

        MessageSendResponse response = client.messages().send(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Hello, world!"
});

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => 'Hello, world!'
]);

print_r($response);

MMS messages support media attachments. Your number must be MMS-enabled.

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Check out this image!",
    "subject": "Picture",
    "media_urls": ["https://example.com/image.jpg"]
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Check out this image!',
  subject: 'Picture',
  media_urls: ['https://example.com/image.jpg']
});

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.send(
    from_="+15551234567",
    to="+15559876543",
    text="Check out this image!",
    subject="Picture",
    media_urls=["https://example.com/image.jpg"]
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: "+15559876543",
  text: "Check out this image!",
  subject: "Picture",
  media_urls: ["https://example.com/image.jpg"]
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From:      "+15551234567",
    To:        "+15559876543",
    Text:      "Check out this image!",
    Subject:   "Picture",
    MediaURLs: []string{"https://example.com/image.jpg"},
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;
import java.util.List;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendParams params = MessageSendParams.builder()
            .from("+15551234567")
            .to("+15559876543")
            .text("Check out this image!")
            .subject("Picture")
            .mediaUrls(List.of("https://example.com/image.jpg"))
            .build();

        MessageSendResponse response = client.messages().send(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Check out this image!",
    Subject = "Picture",
    MediaUrls = new[] { "https://example.com/image.jpg" }
});

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => 'Check out this image!',
    'subject' => 'Picture',
    'media_urls' => ['https://example.com/image.jpg']
]);

print_r($response);

Media URLs must be publicly accessible. Replace the placeholder values:

YOUR_API_KEY: Your API key from step 3
from: Your first Telnyx number (the sender)
to: Your second Telnyx number (the recipient)

E.164 format is required. Always include the + prefix, country code, and full number with no spaces or punctuation.

Country	Format	Example
US/Canada	+1 + 10 digits	`+15551234567`
UK	+44 + 10-11 digits (drop leading 0)	`+447911123456`
Germany	+49 + 10-11 digits (drop leading 0)	`+4915123456789`
Australia	+61 + 9 digits (drop leading 0)	`+61412345678`
Brazil	+55 + 10-11 digits	`+5511987654321`
India	+91 + 10 digits	`+919876543210`

Common mistakes:

❌ 15551234567 (missing +)
❌ +1 (555) 123-4567 (contains spaces and punctuation)
❌ +1-555-123-4567 (contains dashes)
✅ +15551234567

Sending to non-Telnyx numbers? Off-net messaging to external carriers typically requires sender registration (10DLC, toll-free verification, etc.). See Next steps for registration guides.

Response

A successful response looks like this:

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+15551234567",
      "carrier": "Telnyx",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+15559876543",
        "status": "queued",
        "carrier": "CARRIER",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, world!",
    "encoding": "GSM-7",
    "parts": 1,
    "cost": {
      "amount": 0.0051,
      "currency": "USD"
    }
  }
}

The status: "queued" means your message is on its way. Save the id to track delivery status.

Error handling

API errors return structured JSON responses with an error code, title, and detail message. Handle these in your application to provide clear feedback and enable automatic recovery.

Error response format

{
  "errors": [
    {
      "code": "40300",
      "title": "Forbidden",
      "detail": "The from number +15551234567 is not assigned to a messaging profile.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/messaging/messages/error-codes"
      }
    }
  ]
}

SDK error handling examples

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

try {
  const response = await client.messages.send({
    from: '+15551234567',
    to: '+15559876543',
    text: 'Hello, world!'
  });
  console.log('Message sent:', response.data.id);
} catch (error) {
  switch (error.status) {
    case 400:
      console.error('Bad request:', error.message);
      // Malformed JSON, missing required fields
      break;
    case 401:
      console.error('Authentication failed. Check your API key.');
      break;
    case 403:
      console.error('Forbidden:', error.message);
      // Number not assigned to profile, or registration required
      break;
    case 422:
      console.error('Validation error:', error.message);
      // Invalid phone number format, text too long, etc.
      break;
    case 429:
      // Rate limited — extract retry-after header
      const retryAfter = error.headers?.['retry-after'] || 1;
      console.warn(`Rate limited. Retrying after ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      // Retry the request
      break;
    default:
      console.error(`Error (${error.status}):`, error.message);
  }
}

Python

import os
import time
from telnyx import Telnyx
from telnyx import APIError, AuthenticationError, RateLimitError

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

def send_with_retry(from_number, to_number, text, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.messages.send(
                from_=from_number,
                to=to_number,
                text=text,
            )
            print(f"Message sent: {response.data.id}")
            return response
        except AuthenticationError:
            print("Authentication failed. Check your API key.")
            raise  # Don't retry auth errors
        except RateLimitError as e:
            retry_after = int(e.headers.get("retry-after", 1))
            print(f"Rate limited. Retrying in {retry_after}s (attempt {attempt + 1})")
            time.sleep(retry_after)
        except APIError as e:
            if e.status_code == 422:
                print(f"Validation error: {e.message}")
                raise  # Don't retry validation errors
            elif e.status_code == 403:
                print(f"Forbidden: {e.message}")
                raise  # Don't retry permission errors
            elif e.status_code >= 500:
                wait = 2 ** attempt
                print(f"Server error ({e.status_code}). Retrying in {wait}s...")
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

send_with_retry("+15551234567", "+15559876543", "Hello, world!")

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

begin
  response = client.messages.send_(
    from: "+15551234567",
    to: "+15559876543",
    text: "Hello, world!"
  )
  puts "Message sent: #{response.id}"
rescue Telnyx::AuthenticationError
  puts "Authentication failed. Check your API key."
rescue Telnyx::RateLimitError => e
  retry_after = e.http_headers["retry-after"]&.to_i || 1
  puts "Rate limited. Retry after #{retry_after}s"
  sleep(retry_after)
  retry
rescue Telnyx::InvalidRequestError => e
  puts "Validation error: #{e.message}"
rescue Telnyx::APIError => e
  puts "API error (#{e.http_status}): #{e.message}"
end

package main

import (
  "context"
  "errors"
  "fmt"
  "os"
  "time"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func sendWithRetry(client *telnyx.Client, params telnyx.MessageSendParams, maxRetries int) error {
  for attempt := 0; attempt < maxRetries; attempt++ {
    response, err := client.Messages.Send(context.TODO(), params)
    if err == nil {
      fmt.Printf("Message sent: %s\n", response.Data.ID)
      return nil
    }

    var apiErr *telnyx.Error
    if errors.As(err, &apiErr) {
      switch apiErr.StatusCode {
      case 401:
        return fmt.Errorf("authentication failed: %s", apiErr.Message)
      case 403:
        return fmt.Errorf("forbidden: %s", apiErr.Message)
      case 422:
        return fmt.Errorf("validation error: %s", apiErr.Message)
      case 429:
        wait := time.Duration(1<= 500 {
          wait := time.Duration(1<= 500) {
                    long waitMs = (long) Math.pow(2, attempt) * 1000;
                    System.out.printf("Server error (%d). Retrying in %dms...%n", e.getStatusCode(), waitMs);
                    Thread.sleep(waitMs);
                } else {
                    throw e;
                }
            }
        }
        throw new Exception("Max retries exceeded");
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var options = new MessageSendOptions
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Hello, world!"
};

int maxRetries = 3;
for (int attempt = 0; attempt < maxRetries; attempt++)
{
    try
    {
        var response = await service.SendAsync(options);
        Console.WriteLine($"Message sent: {response.Data.Id}");
        break;
    }
    catch (TelnyxException e) when (e.HttpStatusCode == 429)
    {
        var wait = (int)Math.Pow(2, attempt) * 1000;
        Console.WriteLine($"Rate limited. Retrying in {wait}ms...");
        await Task.Delay(wait);
    }
    catch (TelnyxException e) when (e.HttpStatusCode == 401)
    {
        Console.Error.WriteLine("Authentication failed. Check your API key.");
        throw;
    }
    catch (TelnyxException e) when (e.HttpStatusCode == 422)
    {
        Console.Error.WriteLine($"Validation error: {e.Message}");
        throw; // Don't retry validation errors
    }
    catch (TelnyxException e) when (e.HttpStatusCode >= 500)
    {
        var wait = (int)Math.Pow(2, attempt) * 1000;
        Console.WriteLine($"Server error ({e.HttpStatusCode}). Retrying in {wait}ms...");
        await Task.Delay(wait);
    }
}

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

function sendWithRetry($params, $maxRetries = 3) {
    for ($attempt = 0; $attempt < $maxRetries; $attempt++) {
        try {
            $response = \Telnyx\Message::Create($params);
            echo "Message sent: " . $response->id . "\n";
            return $response;
        } catch (\Telnyx\Exception\AuthenticationException $e) {
            echo "Authentication failed. Check your API key.\n";
            throw $e;
        } catch (\Telnyx\Exception\InvalidRequestException $e) {
            echo "Validation error: " . $e->getMessage() . "\n";
            throw $e; // Don't retry validation errors
        } catch (\Telnyx\Exception\RateLimitException $e) {
            $wait = pow(2, $attempt);
            echo "Rate limited. Retrying in {$wait}s...\n";
            sleep($wait);
        } catch (\Telnyx\Exception\ApiException $e) {
            if ($e->getHttpStatus() >= 500) {
                $wait = pow(2, $attempt);
                echo "Server error ({$e->getHttpStatus()}). Retrying in {$wait}s...\n";
                sleep($wait);
            } else {
                throw $e;
            }
        }
    }
    throw new \Exception("Max retries exceeded");
}

sendWithRetry([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => 'Hello, world!'
]);

HTTP error codes

HTTP Status	Meaning	Retryable	Action
`400`	Bad Request	No	Fix the request body — malformed JSON or missing required fields
`401`	Unauthorized	No	Check your API key is correct and active
`402`	Payment Required	No	Add funds to your account balance
`403`	Forbidden	No	Number not assigned to a messaging profile, or sender registration required
`404`	Not Found	No	The resource (message ID, profile ID) does not exist
`422`	Unprocessable Entity	No	Validation failed — see error detail for the specific field
`429`	Too Many Requests	Yes	Rate limited — wait for the `retry-after` header value, then retry
`500`	Internal Server Error	Yes	Telnyx server error — retry with exponential backoff
`503`	Service Unavailable	Yes	Temporary outage — retry with exponential backoff

Messaging-specific error codes

These codes appear in the errors[].code field and provide more specific detail than HTTP status codes alone:

Code	Description	Resolution
`40001`	Phone number not in E.164 format	Format as `+[country code][number]` with no spaces or punctuation
`40002`	Missing required field	Include all required fields: `from`, `to`, and `text` (or `media_urls`)
`40300`	Number not assigned to messaging profile	Go to My Numbers and assign a messaging profile
`40301`	Sender registration required	Register for 10DLC, toll-free verification, or another sender type
`40302`	Messaging profile disabled	Re-enable the profile in the portal
`42200`	Invalid `from` number	Verify the number belongs to your account and supports messaging
`42201`	Invalid `to` number	Verify the destination is a valid, active phone number
`42202`	Message body too long	SMS max: 1,600 characters (concatenated). Reduce content or split into multiple messages
`42203`	Invalid media URL	Ensure `media_urls` are publicly accessible HTTPS URLs
`42204`	Too many media attachments	MMS supports up to 10 media URLs per message
`42205`	Media file too large	Individual media files must be under 1 MB; total under 2 MB

For a complete error code reference including delivery failure codes, see the Messaging Error Codes guide.

Rate limiting

The Telnyx Messaging API enforces rate limits to ensure platform stability. When you exceed the limit, the API returns 429 Too Many Requests with a retry-after header. Rate limit headers:

Header	Description
`x-ratelimit-limit`	Maximum requests allowed in the current window
`x-ratelimit-remaining`	Requests remaining in the current window
`x-ratelimit-reset`	Unix timestamp when the window resets
`retry-after`	Seconds to wait before retrying (only on `429` responses)

Best practices for high-volume sending:

Implement exponential backoff: wait 2^attempt seconds between retries (1s, 2s, 4s, 8s…)
Add jitter to prevent thundering herd: wait = base_wait * (0.5 + random())
Set a maximum retry count (3–5 attempts) to avoid infinite loops
Use a message queue (Redis, RabbitMQ, SQS) to buffer outbound messages and control throughput
Monitor x-ratelimit-remaining and slow down before hitting the limit

Troubleshooting checklist

If your message fails to send, work through this checklist: Confirm your API key is active at API Keys. Revoked or expired keys return 401. Verify your from number is assigned to a messaging profile at My Numbers. Unassigned numbers return 403. Both from and to must be in E.164 format: +15551234567. No spaces, dashes, or parentheses. Sending to US carriers off-net requires registration. Check your registration status:

10DLC: 10DLC Registration
Toll-free: Toll-Free Verification
Short code: Short Codes Insufficient balance returns 402. Check and top up at Billing.
SMS body must not exceed 1,600 characters
MMS media URLs must be publicly accessible HTTPS URLs
Content must comply with carrier guidelines (no SHAFT content without proper registration) If the API returns 200 but the message doesn’t arrive, check message.finalized webhook events for delivery failure details. See Webhooks and delivery tracking.

Still stuck? Check the Telnyx Status Page for platform issues, or contact support with your message ID from the API response.

Webhooks and delivery tracking

After sending a message, Telnyx delivers real-time status updates via webhooks. Configure a webhook URL on your Messaging Profile to receive these events automatically.

Message lifecycle events

Messages progress through these statuses:

Event	Status	Description
`message.sent`	`sent`	Message accepted and sent to the carrier
`message.finalized`	`delivered`	Carrier confirmed delivery to the handset
`message.finalized`	`delivery_failed`	Carrier could not deliver the message
`message.finalized`	`delivery_unconfirmed`	No delivery confirmation received from the carrier

Not all carriers return delivery receipts. Some messages may remain in sent status without a finalized event. US carriers generally support delivery receipts for SMS; international coverage varies.

Webhook payload example

{
  "data": {
    "event_type": "message.finalized",
    "id": "e6e3e550-4e3f-4b3a-9e10-1c2d3e4f5a6b",
    "occurred_at": "2026-03-05T18:30:00.000+00:00",
    "payload": {
      "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
      "record_type": "message",
      "direction": "outbound",
      "type": "SMS",
      "from": { "phone_number": "+15551234567" },
      "to": [
        {
          "phone_number": "+15559876543",
          "status": "delivered"
        }
      ],
      "text": "Hello, world!",
      "parts": 1,
      "cost": { "amount": "0.0051", "currency": "USD" },
      "errors": [],
      "completed_at": "2026-03-05T18:30:00.000+00:00"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks"
  }
}

Processing webhooks

Set up an endpoint to receive webhook POST requests and return a 200 response. Telnyx retries failed deliveries with exponential backoff.

Node

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/messaging', (req, res) => {
  const event = req.body.data;

  switch (event.event_type) {
    case 'message.sent':
      console.log(`Message ${event.payload.id} sent`);
      break;
    case 'message.finalized': {
      const status = event.payload.to[0].status;
      if (status === 'delivered') {
        console.log(`Message ${event.payload.id} delivered`);
      } else if (status === 'delivery_failed') {
        console.error(`Message ${event.payload.id} failed:`, event.payload.errors);
      }
      break;
    }
  }

  res.sendStatus(200);
});

app.listen(3000, () => console.log('Webhook server listening on port 3000'));

Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/messaging", methods=["POST"])
def handle_webhook():
    event = request.json["data"]

    if event["event_type"] == "message.sent":
        print(f"Message {event['payload']['id']} sent")
    elif event["event_type"] == "message.finalized":
        status = event["payload"]["to"][0]["status"]
        if status == "delivered":
            print(f"Message {event['payload']['id']} delivered")
        elif status == "delivery_failed":
            print(f"Message {event['payload']['id']} failed:", event["payload"]["errors"])

    return jsonify(success=True), 200

if __name__ == "__main__":
    app.run(port=3000)

Ruby

require "sinatra"
require "json"

post "/webhooks/messaging" do
  event = JSON.parse(request.body.read)["data"]

  case event["event_type"]
  when "message.sent"
    puts "Message #{event['payload']['id']} sent"
  when "message.finalized"
    status = event["payload"]["to"][0]["status"]
    if status == "delivered"
      puts "Message #{event['payload']['id']} delivered"
    elsif status == "delivery_failed"
      puts "Message #{event['payload']['id']} failed: #{event['payload']['errors']}"
    end
  end

  status 200
  json success: true
end

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
)

type WebhookEvent struct {
  Data struct {
    EventType string `json:"event_type"`
    Payload   struct {
      ID   string `json:"id"`
      To   []struct {
        Status string `json:"status"`
      } `json:"to"`
      Errors []map[string]interface{} `json:"errors"`
    } `json:"payload"`
  } `json:"data"`
}

func handleWebhook(w http.ResponseWriter, r *http.Request) {
  var event WebhookEvent
  if err := json.NewDecoder(r.Body).Decode(&event); err != nil {
    http.Error(w, "Bad request", 400)
    return
  }

  switch event.Data.EventType {
  case "message.sent":
    fmt.Printf("Message %s sent\n", event.Data.Payload.ID)
  case "message.finalized":
    if len(event.Data.Payload.To) > 0 {
      status := event.Data.Payload.To[0].Status
      if status == "delivered" {
        fmt.Printf("Message %s delivered\n", event.Data.Payload.ID)
      } else if status == "delivery_failed" {
        fmt.Printf("Message %s failed: %v\n", event.Data.Payload.ID, event.Data.Payload.Errors)
      }
    }
  }

  w.WriteHeader(http.StatusOK)
  json.NewEncoder(w).Encode(map[string]bool{"success": true})
}

func main() {
  http.HandleFunc("/webhooks/messaging", handleWebhook)
  log.Println("Webhook server listening on port 3000")
  log.Fatal(http.ListenAndServe(":3000", nil))
}

Java

package com.telnyx.example;

import com.sun.net.httpserver.HttpServer;
import com.sun.net.httpserver.HttpExchange;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;

public class WebhookServer {
    private static final ObjectMapper mapper = new ObjectMapper();

    public static void main(String[] args) throws IOException {
        HttpServer server = HttpServer.create(new InetSocketAddress(3000), 0);
        server.createContext("/webhooks/messaging", WebhookServer::handleWebhook);
        System.out.println("Webhook server listening on port 3000");
        server.start();
    }

    private static void handleWebhook(HttpExchange exchange) throws IOException {
        JsonNode body = mapper.readTree(exchange.getRequestBody());
        JsonNode data = body.get("data");
        String eventType = data.get("event_type").asText();
        String messageId = data.get("payload").get("id").asText();

        if ("message.sent".equals(eventType)) {
            System.out.printf("Message %s sent%n", messageId);
        } else if ("message.finalized".equals(eventType)) {
            String status = data.get("payload").get("to").get(0).get("status").asText();
            if ("delivered".equals(status)) {
                System.out.printf("Message %s delivered%n", messageId);
            } else if ("delivery_failed".equals(status)) {
                System.out.printf("Message %s failed: %s%n", messageId, data.get("payload").get("errors"));
            }
        }

        String response = "{\"success\":true}";
        exchange.sendResponseHeaders(200, response.length());
        try (OutputStream os = exchange.getResponseBody()) {
            os.write(response.getBytes());
        }
    }
}

.NET

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/webhooks/messaging", async (HttpContext context) =>
{
    using var doc = await JsonDocument.ParseAsync(context.Request.Body);
    var data = doc.RootElement.GetProperty("data");
    var eventType = data.GetProperty("event_type").GetString();
    var messageId = data.GetProperty("payload").GetProperty("id").GetString();

    if (eventType == "message.sent")
    {
        Console.WriteLine($"Message {messageId} sent");
    }
    else if (eventType == "message.finalized")
    {
        var status = data.GetProperty("payload").GetProperty("to")[0].GetProperty("status").GetString();
        if (status == "delivered")
            Console.WriteLine($"Message {messageId} delivered");
        else if (status == "delivery_failed")
            Console.WriteLine($"Message {messageId} failed: {data.GetProperty("payload").GetProperty("errors")}");
    }

    return Results.Ok(new { success = true });
});

app.Run("http://localhost:3000");

PHP

<?php
$payload = json_decode(file_get_contents('php://input'), true);
$event = $payload['data'];

switch ($event['event_type']) {
    case 'message.sent':
        error_log("Message {$event['payload']['id']} sent");
        break;
    case 'message.finalized':
        $status = $event['payload']['to'][0]['status'];
        if ($status === 'delivered') {
            error_log("Message {$event['payload']['id']} delivered");
        } elseif ($status === 'delivery_failed') {
            error_log("Message {$event['payload']['id']} failed: " . json_encode($event['payload']['errors']));
        }
        break;
}

http_response_code(200);
echo json_encode(['success' => true]);

Retrieve message status via API

You can also check a message’s current status by its ID:

curl

curl -X GET "https://api.telnyx.com/v2/messages/b0c7e8cb-6227-4c74-9f32-c7f80c30934b" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node

const message = await client.messages.retrieve('b0c7e8cb-6227-4c74-9f32-c7f80c30934b');
console.log(message.data.to[0].status); // "delivered"

Python

message = client.messages.retrieve("b0c7e8cb-6227-4c74-9f32-c7f80c30934b")
print(message.data.to[0].status)  # "delivered"

Delivery failure error codes

When a message fails delivery, the errors array in the webhook payload contains error codes:

Code	Description	Action
`30003`	Unreachable destination	Verify the number is active and can receive SMS
`30004`	Message blocked by carrier	Check content compliance and sender registration
`30005`	Unknown destination	Number may be disconnected or invalid
`30006`	Landline or unreachable	Number cannot receive SMS (landline, VoIP)
`30007`	Carrier violation	Message rejected due to content filtering
`30008`	Destination capacity exceeded	Retry after a delay

For a complete error code reference, see the Messaging Error Codes guide.

Webhook security

Validate incoming webhooks to ensure they’re from Telnyx:

IP allowlisting — Telnyx sends webhooks from 192.76.120.192/27
HTTPS endpoints — Always use HTTPS for your webhook URL
Respond quickly — Return 200 within 5 seconds to prevent retries

If your endpoint consistently fails to respond, Telnyx will retry with exponential backoff and eventually disable the webhook. Monitor your endpoint health to avoid missing delivery events.

Next steps

Set up webhooks to receive incoming SMS Learn about long codes, toll-free, and short codes Register your brand for US messaging compliance Explore all messaging parameters

Receive Messages

Source: https://developers.telnyx.com/docs/messaging/messages/receive-message.md

Receive inbound SMS and MMS messages via webhooks. When someone texts your Telnyx number, Telnyx sends an HTTP POST request with the message details to your configured webhook URL.

Prerequisites

A Telnyx phone number assigned to a messaging profile
A webhook URL configured on your messaging profile
ngrok or similar tool for local development

Already have a webhook server? Skip to Configure your webhook URL to point it at your messaging profile.

Quick Start

Build a web server that accepts POST requests from Telnyx:

Node

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks', (req, res) => {
  const { data } = req.body;

  if (data.event_type === 'message.received') {
    const { payload } = data;
    console.log(`From: ${payload.from.phone_number}`);
    console.log(`Text: ${payload.text}`);
    console.log(`Type: ${payload.type}`); // SMS or MMS

    if (payload.media?.length > 0) {
      console.log(`Media attachments: ${payload.media.length}`);
      payload.media.forEach(m => console.log(`  ${m.content_type}: ${m.url}`));
    }
  }

  res.sendStatus(200);
});

app.listen(5000, () => console.log('Webhook server running on port 5000'));

Python

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def webhooks():
    data = request.json.get('data', {})

    if data.get('event_type') == 'message.received':
        payload = data.get('payload', {})
        print(f"From: {payload['from']['phone_number']}")
        print(f"Text: {payload.get('text')}")
        print(f"Type: {payload.get('type')}")  # SMS or MMS

        for media in payload.get('media', []):
            print(f"  {media['content_type']}: {media['url']}")

    return '', 200

if __name__ == "__main__":
    app.run(port=5000)

Ruby

require 'sinatra'
require 'json'

set :port, 5000

post '/webhooks' do
  body = JSON.parse(request.body.read)
  data = body['data']

  if data['event_type'] == 'message.received'
    payload = data['payload']
    puts "From: #{payload['from']['phone_number']}"
    puts "Text: #{payload['text']}"
    puts "Type: #{payload['type']}"

    (payload['media'] || []).each do |media|
      puts "  #{media['content_type']}: #{media['url']}"
    end
  end

  status 200
end

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
)

type WebhookEvent struct {
  Data struct {
    EventType string `json:"event_type"`
    Payload   struct {
      From struct {
        PhoneNumber string `json:"phone_number"`
      } `json:"from"`
      Text  string `json:"text"`
      Type  string `json:"type"`
      Media []struct {
        URL         string `json:"url"`
        ContentType string `json:"content_type"`
      } `json:"media"`
    } `json:"payload"`
  } `json:"data"`
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  var event WebhookEvent
  json.NewDecoder(r.Body).Decode(&event)

  if event.Data.EventType == "message.received" {
    p := event.Data.Payload
    fmt.Printf("From: %s\n", p.From.PhoneNumber)
    fmt.Printf("Text: %s\n", p.Text)
    fmt.Printf("Type: %s\n", p.Type)

    for _, m := range p.Media {
      fmt.Printf("  %s: %s\n", m.ContentType, m.URL)
    }
  }

  w.WriteHeader(http.StatusOK)
}

func main() {
  http.HandleFunc("/webhooks", webhookHandler)
  fmt.Println("Webhook server running on port 5000")
  http.ListenAndServe(":5000", nil)
}

Java

package com.example.webhook;

import com.sun.net.httpserver.HttpServer;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.InputStream;
import java.net.InetSocketAddress;

public class WebhookServer {
    public static void main(String[] args) throws Exception {
        HttpServer server = HttpServer.create(new InetSocketAddress(5000), 0);

        server.createContext("/webhooks", exchange -> {
            if ("POST".equals(exchange.getRequestMethod())) {
                InputStream is = exchange.getRequestBody();
                String body = new String(is.readAllBytes());
                JsonObject json = JsonParser.parseString(body).getAsJsonObject();
                JsonObject data = json.getAsJsonObject("data");

                if ("message.received".equals(data.get("event_type").getAsString())) {
                    JsonObject payload = data.getAsJsonObject("payload");
                    String from = payload.getAsJsonObject("from").get("phone_number").getAsString();
                    System.out.println("From: " + from);
                    System.out.println("Text: " + payload.get("text").getAsString());
                    System.out.println("Type: " + payload.get("type").getAsString());

                    JsonArray media = payload.getAsJsonArray("media");
                    if (media != null) {
                        media.forEach(m -> {
                            JsonObject obj = m.getAsJsonObject();
                            System.out.println("  " + obj.get("content_type").getAsString()
                                + ": " + obj.get("url").getAsString());
                        });
                    }
                }

                exchange.sendResponseHeaders(200, -1);
            }
        });

        server.start();
        System.out.println("Webhook server running on port 5000");
    }
}

.NET

using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/webhooks", async (HttpRequest request) =>
{
    using var doc = await JsonDocument.ParseAsync(request.Body);
    var data = doc.RootElement.GetProperty("data");

    if (data.GetProperty("event_type").GetString() == "message.received")
    {
        var payload = data.GetProperty("payload");
        Console.WriteLine($"From: {payload.GetProperty("from").GetProperty("phone_number").GetString()}");
        Console.WriteLine($"Text: {payload.GetProperty("text").GetString()}");
        Console.WriteLine($"Type: {payload.GetProperty("type").GetString()}");

        if (payload.TryGetProperty("media", out var media))
        {
            foreach (var m in media.EnumerateArray())
            {
                Console.WriteLine($"  {m.GetProperty("content_type").GetString()}: {m.GetProperty("url").GetString()}");
            }
        }
    }

    return Results.Ok();
});

app.Run("http://localhost:5000");

PHP

<?php

$payload = json_decode(file_get_contents('php://input'), true);
$data = $payload['data'] ?? [];

if (($data['event_type'] ?? '') === 'message.received') {
    $msg = $data['payload'];
    echo "From: " . $msg['from']['phone_number'] . "\n";
    echo "Text: " . ($msg['text'] ?? '') . "\n";
    echo "Type: " . ($msg['type'] ?? '') . "\n";

    foreach ($msg['media'] ?? [] as $media) {
        echo "  {$media['content_type']}: {$media['url']}\n";
    }
}

http_response_code(200);

Use ngrok to create a public URL that forwards to your local server:

ngrok http 5000

Copy the forwarding URL (e.g., https://abc123.ngrok.io). Set the webhook URL on your messaging profile via the Portal or API:

curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "webhook_url": "https://abc123.ngrok.io/webhooks"
  }'

Find your messaging profile ID in the Portal or via the List Messaging Profiles endpoint. Send a text message from your phone to your Telnyx number. You should see the message details logged in your server console. You can also test locally without a phone:

curl -X POST http://localhost:5000/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "event_type": "message.received",
      "payload": {
        "from": {"phone_number": "+15551234567"},
        "to": [{"phone_number": "+15559876543"}],
        "text": "Hello from test!",
        "type": "SMS",
        "media": []
      }
    }
  }'

Your webhook must return a 2xx response within 2 seconds (API v2) or 5 seconds (API v1). If delivery fails, Telnyx retries up to 2 times per URL. With a failover URL configured, that’s up to 4 total attempts.

Auto-Reply to Incoming Messages

A common pattern is sending an automatic reply when a message arrives. Combine your webhook handler with the Send Message API:

Node

import express from 'express';
import Telnyx from 'telnyx';

const app = express();
app.use(express.json());

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

app.post('/webhooks', async (req, res) => {
  const { data } = req.body;

  if (data.event_type === 'message.received') {
    const { payload } = data;
    const from = payload.from.phone_number;
    const to = payload.to[0].phone_number;

    // Send auto-reply
    await client.messages.send({
      from: to,   // Reply from the number that received the message
      to: from,   // Reply to the sender
      text: `Thanks for your message! We received: "${payload.text}"`
    });

    console.log(`Auto-reply sent to ${from}`);
  }

  res.sendStatus(200);
});

app.listen(5000);

Python

import os
from flask import Flask, request
from telnyx import Telnyx

app = Flask(__name__)
client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

@app.route('/webhooks', methods=['POST'])
def webhooks():
    data = request.json.get('data', {})

    if data.get('event_type') == 'message.received':
        payload = data.get('payload', {})
        sender = payload['from']['phone_number']
        recipient = payload['to'][0]['phone_number']

        # Send auto-reply
        client.messages.send(
            from_=recipient,
            to=sender,
            text=f'Thanks for your message! We received: "{payload.get("text")}"'
        )

        print(f"Auto-reply sent to {sender}")

    return '', 200

if __name__ == "__main__":
    app.run(port=5000)

Ruby

require 'sinatra'
require 'json'
require 'telnyx'

Telnyx.api_key = ENV['TELNYX_API_KEY']

post '/webhooks' do
  body = JSON.parse(request.body.read)
  data = body['data']

  if data['event_type'] == 'message.received'
    payload = data['payload']
    sender = payload['from']['phone_number']
    recipient = payload['to'][0]['phone_number']

    Telnyx::Message.create(
      from: recipient,
      to: sender,
      text: "Thanks for your message! We received: \"#{payload['text']}\""
    )

    puts "Auto-reply sent to #{sender}"
  end

  status 200
end

package main

import (
  "context"
  "encoding/json"
  "fmt"
  "net/http"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )

  http.HandleFunc("/webhooks", func(w http.ResponseWriter, r *http.Request) {
    var event WebhookEvent
    json.NewDecoder(r.Body).Decode(&event)

    if event.Data.EventType == "message.received" {
      p := event.Data.Payload
      sender := p.From.PhoneNumber
      recipient := p.To[0].PhoneNumber

      client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
        From: recipient,
        To:   sender,
        Text: fmt.Sprintf("Thanks for your message! We received: \"%s\"", p.Text),
      })

      fmt.Printf("Auto-reply sent to %s\n", sender)
    }

    w.WriteHeader(http.StatusOK)
  })

  fmt.Println("Server running on port 5000")
  http.ListenAndServe(":5000", nil)
}

Avoid reply loops. If both sides auto-reply, they’ll ping each other forever. Guard against this by checking the sender isn’t one of your own numbers, or by tracking recently replied conversations.

Webhook Payload Reference

Inbound SMS

{
  "data": {
    "event_type": "message.received",
    "id": "b301ed3f-1490-491f-995f-6e64e69674d4",
    "occurred_at": "2024-01-15T20:16:07.588+00:00",
    "payload": {
      "direction": "inbound",
      "encoding": "GSM-7",
      "from": {
        "carrier": "T-Mobile USA",
        "line_type": "long_code",
        "phone_number": "+13125550001",
        "status": "webhook_delivered"
      },
      "id": "84cca175-9755-4859-b67f-4730d7f58aa3",
      "media": [],
      "messaging_profile_id": "740572b6-099c-44a1-89b9-6c92163bc68d",
      "parts": 1,
      "received_at": "2024-01-15T20:16:07.503+00:00",
      "record_type": "message",
      "text": "Hello from Telnyx!",
      "to": [
        {
          "carrier": "Telnyx",
          "line_type": "Wireless",
          "phone_number": "+17735550002",
          "status": "webhook_delivered"
        }
      ],
      "type": "SMS"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks"
  }
}

Inbound MMS

MMS messages include a media array with downloadable attachments:

{
  "data": {
    "event_type": "message.received",
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "occurred_at": "2024-01-15T20:18:30.000+00:00",
    "payload": {
      "direction": "inbound",
      "from": {
        "carrier": "T-Mobile USA",
        "line_type": "long_code",
        "phone_number": "+13125550001"
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "media": [
        {
          "url": "https://media.telnyx.com/example-image.png",
          "content_type": "image/png",
          "sha256": "ab1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
          "size": 102400
        }
      ],
      "messaging_profile_id": "740572b6-099c-44a1-89b9-6c92163bc68d",
      "parts": 1,
      "received_at": "2024-01-15T20:18:30.000+00:00",
      "record_type": "message",
      "text": "Check out this photo!",
      "to": [
        {
          "carrier": "Telnyx",
          "line_type": "Wireless",
          "phone_number": "+17735550002"
        }
      ],
      "type": "MMS"
    },
    "record_type": "event"
  }
}

MMS media URLs expire after 30 days. Download and store media files if you need long-term access.

Webhook Payload Schema

Field	Type	Description
`data.event_type`	`string`	Always `message.received` for inbound messages
`data.id`	`string`	Unique event ID (UUID) — use for idempotency
`data.occurred_at`	`string`	ISO 8601 timestamp when the event occurred
`data.record_type`	`string`	Always `event`
`meta.attempt`	`integer`	Webhook delivery attempt number (1–3)
`meta.delivered_to`	`string`	The webhook URL this was delivered to
Field	Type	Description
-------	------	-------------
`payload.id`	`string`	Unique message ID (UUID) — use for deduplication
`payload.direction`	`string`	Always `inbound` for received messages
`payload.from.phone_number`	`string`	Sender’s phone number (E.164 format)
`payload.from.carrier`	`string`	Sender’s carrier name
`payload.from.line_type`	`string`	`long_code`, `toll_free`, `short_code`, etc.
`payload.to[].phone_number`	`string`	Your Telnyx number that received the message
`payload.text`	`string`	Message body (may be `null` for media-only MMS)
`payload.type`	`string`	`SMS` or `MMS`
`payload.encoding`	`string`	`GSM-7` or `UCS-2` (details)
`payload.parts`	`integer`	Number of message segments
`payload.messaging_profile_id`	`string`	Messaging profile that received the message
`payload.received_at`	`string`	ISO 8601 timestamp when the message was received
`payload.record_type`	`string`	Always `message`
Field	Type	Description
-------	------	-------------
`payload.media`	`array`	Array of media attachments (empty for SMS)
`payload.media[].url`	`string`	Authenticated download URL (expires in 30 days)
`payload.media[].content_type`	`string`	MIME type (e.g., `image/png`, `video/mp4`)
`payload.media[].sha256`	`string`	SHA-256 hash of the media file
`payload.media[].size`	`integer`	File size in bytes

Supported MMS media types:

Images: image/jpeg, image/png, image/gif, image/bmp, image/webp
Video: video/mp4, video/3gpp
Audio: audio/mpeg, audio/ogg, audio/amr
Files: application/pdf, text/vcard, text/calendar

Downloading MMS Media

Download media attachments from inbound MMS messages using the URLs in the media array. Authenticate with your API key:

Node

import fs from 'fs';

async function downloadMedia(mediaUrl, apiKey) {
  const response = await fetch(mediaUrl, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const buffer = Buffer.from(await response.arrayBuffer());
  const filename = mediaUrl.split('/').pop();
  fs.writeFileSync(filename, buffer);
  console.log(`Downloaded: ${filename} (${buffer.length} bytes)`);
}

// In your webhook handler:
for (const media of payload.media) {
  await downloadMedia(media.url, process.env.TELNYX_API_KEY);
}

Python

import requests
import os

def download_media(media_url, api_key):
    response = requests.get(
        media_url,
        headers={"Authorization": f"Bearer {api_key}"}
    )
    filename = media_url.split("/")[-1]
    with open(filename, "wb") as f:
        f.write(response.content)
    print(f"Downloaded: {filename} ({len(response.content)} bytes)")

# In your webhook handler:
for media in payload.get("media", []):
    download_media(media["url"], os.environ["TELNYX_API_KEY"])

func downloadMedia(mediaURL, apiKey string) error {
  req, _ := http.NewRequest("GET", mediaURL, nil)
  req.Header.Set("Authorization", "Bearer "+apiKey)

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    return err
  }
  defer resp.Body.Close()

  parts := strings.Split(mediaURL, "/")
  filename := parts[len(parts)-1]

  file, _ := os.Create(filename)
  defer file.Close()

  written, _ := io.Copy(file, resp.Body)
  fmt.Printf("Downloaded: %s (%d bytes)\n", filename, written)
  return nil
}

Ruby

require 'net/http'
require 'uri'

def download_media(media_url, api_key)
  uri = URI.parse(media_url)
  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = "Bearer #{api_key}"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  filename = File.basename(uri.path)
  File.open(filename, 'wb') { |f| f.write(response.body) }
  puts "Downloaded: #{filename} (#{response.body.bytesize} bytes)"
end

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;

public static void downloadMedia(String mediaUrl, String apiKey) throws Exception {
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(mediaUrl))
        .header("Authorization", "Bearer " + apiKey)
        .build();

    String filename = mediaUrl.substring(mediaUrl.lastIndexOf('/') + 1);
    client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of(filename)));
    System.out.println("Downloaded: " + filename);
}

.NET

using var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", apiKey);

var response = await httpClient.GetAsync(mediaUrl);
var bytes = await response.Content.ReadAsByteArrayAsync();
var filename = new Uri(mediaUrl).Segments.Last();
await File.WriteAllBytesAsync(filename, bytes);
Console.WriteLine($"Downloaded: {filename} ({bytes.Length} bytes)");

PHP

<?php
$ch = curl_init($mediaUrl);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $apiKey"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($ch);
curl_close($ch);

$filename = basename(parse_url($mediaUrl, PHP_URL_PATH));
file_put_contents($filename, $data);
echo "Downloaded: $filename (" . strlen($data) . " bytes)\n";

curl

curl -o downloaded-media.png \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://media.telnyx.com/example-image.png"

Verifying Webhook Signatures

In production, verify webhook signatures to confirm requests are from Telnyx. All webhooks are signed using ED25519 public key cryptography. Each webhook includes two headers:

telnyx-signature-ed25519 — Base64-encoded signature
telnyx-timestamp — Unix timestamp when the webhook was sent

Node

import Telnyx from 'telnyx';

const telnyx = new Telnyx('YOUR_API_KEY');

app.post('/webhooks', (req, res) => {
  const signature = req.headers['telnyx-signature-ed25519'];
  const timestamp = req.headers['telnyx-timestamp'];
  const payload = JSON.stringify(req.body);

  try {
    const event = telnyx.webhooks.constructEvent(
      payload,
      signature,
      timestamp,
      process.env.TELNYX_PUBLIC_KEY
    );
    console.log('Verified event:', event.data.event_type);
    res.sendStatus(200);
  } catch (err) {
    console.error('Signature verification failed:', err.message);
    res.sendStatus(400);
  }
});

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"
telnyx.public_key = "YOUR_PUBLIC_KEY"

@app.route('/webhooks', methods=['POST'])
def webhooks():
    payload = request.data
    signature = request.headers.get('telnyx-signature-ed25519')
    timestamp = request.headers.get('telnyx-timestamp')

    try:
        event = telnyx.Webhook.construct_event(payload, signature, timestamp)
        print(f"Verified event: {event['data']['event_type']}")
        return '', 200
    except telnyx.error.SignatureVerificationError as e:
        print(f"Signature verification failed: {e}")
        return '', 400

Ruby

require 'telnyx'

Telnyx.api_key = 'YOUR_API_KEY'
Telnyx.public_key = 'YOUR_PUBLIC_KEY'

post '/webhooks' do
  payload = request.body.read
  signature = request.env['HTTP_TELNYX_SIGNATURE_ED25519']
  timestamp = request.env['HTTP_TELNYX_TIMESTAMP']

  begin
    event = Telnyx::Webhook.construct_event(payload, signature, timestamp)
    puts "Verified event: #{event['data']['event_type']}"
    status 200
  rescue Telnyx::SignatureVerificationError => e
    puts "Signature verification failed: #{e.message}"
    status 400
  end
end

.NET

using Telnyx;

app.MapPost("/webhooks", async (HttpRequest request) =>
{
    var payload = await new StreamReader(request.Body).ReadToEndAsync();
    var signature = request.Headers["telnyx-signature-ed25519"].ToString();
    var timestamp = request.Headers["telnyx-timestamp"].ToString();

    try
    {
        var webhookEvent = Webhook.ConstructEvent(payload, signature, timestamp);
        Console.WriteLine($"Verified event: {webhookEvent.EventType}");
        return Results.Ok();
    }
    catch (TelnyxSignatureVerificationException e)
    {
        Console.WriteLine($"Signature verification failed: {e.Message}");
        return Results.BadRequest();
    }
});

PHP

<?php
require_once 'vendor/autoload.php';

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_TELNYX_SIGNATURE_ED25519'] ?? '';
$timestamp = $_SERVER['HTTP_TELNYX_TIMESTAMP'] ?? '';

try {
    $event = \Telnyx\Webhook::constructEvent($payload, $signature, $timestamp);
    echo "Verified event: " . $event['data']['event_type'];
    http_response_code(200);
} catch (\Telnyx\Exception\SignatureVerificationException $e) {
    echo "Signature verification failed: " . $e->getMessage();
    http_response_code(400);
}

Get your public key from the Mission Control Portal under Account Settings > Keys & Credentials > Public Key. For detailed webhook signature verification, see Webhook Fundamentals.

Handling Failed Webhooks

When webhook delivery fails, Telnyx retries automatically. Build resilience into your architecture:

Node

import express from 'express';
import { createClient } from 'redis';

const app = express();
app.use(express.json());

const redis = createClient();
await redis.connect();

app.post('/webhooks', async (req, res) => {
  // Respond immediately to avoid timeout
  res.sendStatus(200);

  const { data } = req.body;
  const messageId = data.payload?.id;

  // Deduplicate using Redis (TTL: 24 hours)
  if (messageId) {
    const exists = await redis.get(`msg:${messageId}`);
    if (exists) return; // Already processed
    await redis.set(`msg:${messageId}`, '1', { EX: 86400 });
  }

  // Process asynchronously
  try {
    await processMessage(data);
  } catch (err) {
    console.error(`Failed to process ${messageId}:`, err);
    // Log to dead letter queue for manual review
    await redis.lpush('webhook:failed', JSON.stringify({ data, error: err.message }));
  }
});

Python

import redis
import json
import threading
from flask import Flask, request

app = Flask(__name__)
r = redis.Redis()

def process_async(data, message_id):
    """Process webhook in background thread."""
    try:
        process_message(data)
    except Exception as e:
        print(f"Failed to process {message_id}: {e}")
        r.lpush("webhook:failed", json.dumps({"data": data, "error": str(e)}))

@app.route('/webhooks', methods=['POST'])
def webhooks():
    data = request.json.get('data', {})
    message_id = data.get('payload', {}).get('id')

    # Deduplicate
    if message_id:
        if r.get(f"msg:{message_id}"):
            return '', 200
        r.set(f"msg:{message_id}", "1", ex=86400)

    # Process in background thread — return 200 immediately
    # For production, use Celery or RQ instead of threads
    threading.Thread(target=process_async, args=(data, message_id)).start()

    return '', 200

For high-volume applications, use a message queue (Redis, SQS, RabbitMQ) between your webhook endpoint and processing logic. This ensures you always respond within the 2-second timeout.

Troubleshooting

Check your webhook URL is configured:

curl -s "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data.webhook_url'

Common causes:

Webhook URL not set on the messaging profile
Phone number not assigned to the messaging profile
Server not publicly accessible (use ngrok for local dev)
Firewall blocking Telnyx IPs

Test your endpoint directly:

curl -X POST https://your-server.com/webhooks \
  -H "Content-Type: application/json" \
  -d '{"data":{"event_type":"message.received","payload":{"text":"test"}}}'

Duplicates happen when your server doesn’t respond with 2xx within the timeout (2 seconds for API v2). Telnyx retries up to 2 times. Fix: Return 200 immediately, then process the message asynchronously. Use the payload.id field to deduplicate.

// Deduplicate using a Set (use Redis in production)
const processed = new Set();

app.post('/webhooks', (req, res) => {
  res.sendStatus(200); // Respond immediately

  const messageId = req.body.data.payload?.id;
  if (messageId && processed.has(messageId)) return;
  processed.add(messageId);

  // Process message asynchronously
  handleMessage(req.body.data);
});

Your server must respond within 2 seconds (API v2) or 5 seconds (API v1). Solutions:

Return 200 immediately, process in background
Use a message queue (Redis, SQS, RabbitMQ) for heavy processing
Set up a failover URL as a backup
Check the type field is MMS (SMS messages have an empty media array)
Media URLs require authentication — include your API key in the Authorization header
Media URLs expire after 30 days
Verify your number is MMS-enabled in the Portal

Webhook URL Hierarchy

Telnyx checks for webhook URLs in this order:

Request body — URLs provided when sending a message (outbound delivery receipts only)
Messaging profile — URLs configured on the profile
No URL — Webhook delivery is skipped

Configure a failover URL on your messaging profile for redundancy. If the primary URL fails all retry attempts, Telnyx sends to the failover URL.

Your webhook URL receives more than just message.received. For delivery status tracking and other events, see Receiving Webhooks.

Event	Description
`message.received`	Inbound SMS or MMS received (this guide)
`message.sent`	Outbound message accepted by carrier
`message.finalized`	Final delivery status (delivered, failed, etc.)

Next Steps

Send outbound SMS and MMS messages All webhook event types and payload details Understand GSM-7, UCS-2, and message segmentation Handle STOP/HELP keywords automatically

Webhooks

Source: https://developers.telnyx.com/docs/messaging/messages/receiving-webhooks.md

Telnyx sends webhooks to notify your application about messaging events in real time — inbound messages, delivery status updates, and errors. This guide covers every event type, payload structure, signature verification, and best practices for production webhook handling.

Prerequisites

A Telnyx account with a phone number assigned to a messaging profile
A publicly accessible HTTPS endpoint (or ngrok for local development)
Your API key and public key (for signature verification)

How webhook delivery works

A message is received by your number, or a sent message changes status (queued → sent → delivered). An HTTP POST with a JSON payload is sent to your configured webhook URL. Return a 2xx status code within 2 seconds to acknowledge receipt. If your server doesn’t respond in time, Telnyx retries (up to 3 attempts per URL) and then tries your failover URL if configured.

Webhook URL hierarchy

Telnyx determines where to send webhooks using this priority order:

Per-message URLs — webhook_url and webhook_failover_url in the send message request body
Messaging profile URLs — Configured on the messaging profile
No webhook — If neither is set, no webhook is delivered (events are still available in Message Detail Records)

Webhook event types

Telnyx messaging produces the following webhook events:

Event Type	Trigger	Direction
`message.received`	An inbound SMS/MMS arrives at your number	Inbound
`message.sent`	An outbound message has been accepted and sent to the carrier	Outbound
`message.finalized`	An outbound message has reached a terminal state (delivered, failed, etc.)	Outbound

Payload structure

All messaging webhooks share this top-level structure:

{
  "data": {
    "event_type": "message.received",
    "id": "unique-event-id",
    "occurred_at": "2024-01-15T20:16:07.588+00:00",
    "payload": { ... },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks"
  }
}

Field	Description
`data.event_type`	The event type (`message.received`, `message.sent`, `message.finalized`)
`data.id`	Unique identifier for this webhook event
`data.occurred_at`	ISO 8601 timestamp of when the event occurred
`data.payload`	Message details (see examples below)
`data.record_type`	Always `"event"`
`meta.attempt`	Delivery attempt number (starts at 1)
`meta.delivered_to`	The URL this webhook was delivered to

Event examples

Inbound message (`message.received`)

Triggered when your Telnyx number receives an SMS or MMS:

{
  "data": {
    "event_type": "message.received",
    "id": "b301ed3f-1490-491f-995f-6e64e69674d4",
    "occurred_at": "2024-01-15T20:16:07.588+00:00",
    "payload": {
      "completed_at": null,
      "cost": { "amount": "0.0000", "currency": "USD" },
      "direction": "inbound",
      "encoding": "GSM-7",
      "errors": [],
      "from": {
        "carrier": "T-Mobile USA",
        "line_type": "long_code",
        "phone_number": "+13125550001"
      },
      "id": "84cca175-9755-4859-b67f-4730d7f58aa3",
      "media": [],
      "messaging_profile_id": "740572b6-099c-44a1-89b9-6c92163bc68d",
      "organization_id": "47a530f8-4362-4526-829b-bcee17fd9f7a",
      "parts": 1,
      "received_at": "2024-01-15T20:16:07.503+00:00",
      "record_type": "message",
      "sent_at": null,
      "tags": [],
      "text": "Hello from Telnyx!",
      "to": [
        {
          "carrier": "Telnyx",
          "line_type": "Wireless",
          "phone_number": "+17735550002",
          "status": "webhook_delivered"
        }
      ],
      "type": "SMS",
      "valid_until": null,
      "webhook_failover_url": null,
      "webhook_url": "https://example.com/webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks"
  }
}

MMS messages include a media array with URLs, content types, and file sizes:

{
  "media": [
    {
      "url": "https://media.telnyx.com/example-image.png",
      "content_type": "image/png",
      "sha256": "ab1c2d3e4f...",
      "size": 102400
    }
  ],
  "type": "MMS"
}

MMS media links expire after 30 days. Download and store media files if you need long-term access.

Message sent (`message.sent`)

Triggered when an outbound message has been accepted by the downstream carrier:

{
  "data": {
    "event_type": "message.sent",
    "id": "a1b2c3d4-5678-9012-abcd-ef1234567890",
    "occurred_at": "2024-01-15T21:32:13.596+00:00",
    "payload": {
      "completed_at": null,
      "cost": { "amount": "0.0051", "currency": "USD" },
      "direction": "outbound",
      "encoding": "GSM-7",
      "errors": [],
      "from": {
        "carrier": "Telnyx",
        "line_type": "Wireless",
        "phone_number": "+13125550001"
      },
      "id": "ac012cbf-5e09-46af-a69a-7c0e2d90993c",
      "media": [],
      "messaging_profile_id": "83d2343b-553f-4c5f-b8c8-fd27004f94bf",
      "organization_id": "9d76d591-1b7d-405d-8c64-1320ee070245",
      "parts": 1,
      "received_at": "2024-01-15T21:32:13.552+00:00",
      "record_type": "message",
      "sent_at": "2024-01-15T21:32:13.596+00:00",
      "text": "Hello there!",
      "to": [
        {
          "carrier": "T-MOBILE USA, INC.",
          "line_type": "Wireless",
          "phone_number": "+13125550002",
          "status": "sent"
        }
      ],
      "type": "SMS",
      "valid_until": "2024-01-15T22:32:13.552+00:00",
      "webhook_url": "https://example.com/webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks"
  }
}

Delivery receipt (`message.finalized`)

Triggered when a message reaches a terminal delivery state:

{
  "data": {
    "event_type": "message.finalized",
    "id": "4ee8c3a6-4995-4309-a3c6-38e3db9ea4be",
    "occurred_at": "2024-01-15T21:32:14.148+00:00",
    "payload": {
      "completed_at": "2024-01-15T21:32:14.148+00:00",
      "cost": {
        "amount": "0.0051",
        "currency": "USD"
      },
      "cost_breakdown": {
        "carrier_fee": { "amount": "0.00305", "currency": "USD" },
        "rate": { "amount": "0.00205", "currency": "USD" }
      },
      "direction": "outbound",
      "encoding": "GSM-7",
      "errors": [],
      "from": {
        "carrier": "Telnyx",
        "line_type": "Wireless",
        "phone_number": "+13125550001",
        "status": "webhook_delivered"
      },
      "id": "ac012cbf-5e09-46af-a69a-7c0e2d90993c",
      "media": [],
      "messaging_profile_id": "83d2343b-553f-4c5f-b8c8-fd27004f94bf",
      "organization_id": "9d76d591-1b7d-405d-8c64-1320ee070245",
      "parts": 1,
      "received_at": "2024-01-15T21:32:13.552+00:00",
      "record_type": "message",
      "sent_at": "2024-01-15T21:32:13.596+00:00",
      "tags": ["tag-a", "tag-b"],
      "text": "Hello there!",
      "to": [
        {
          "carrier": "T-MOBILE USA, INC.",
          "line_type": "Wireless",
          "phone_number": "+13125550002",
          "status": "delivered"
        }
      ],
      "type": "SMS",
      "valid_until": "2024-01-15T22:32:13.552+00:00",
      "webhook_url": "https://example.com/webhooks",
      "tcr_campaign_billable": true,
      "tcr_campaign_id": "CNZO3VL",
      "tcr_campaign_registered": "REGISTERED"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks"
  }
}

Delivery statuses

The to[].status field in message.finalized events indicates the final delivery outcome:

Status	Description
`queued`	Message is queued on Telnyx’s side
`sending`	Message is being sent to an upstream carrier
`sent`	Message has been sent to the upstream carrier
`delivered`	Carrier has confirmed delivery to the recipient
`sending_failed`	Telnyx failed to send the message to the carrier
`delivery_failed`	The carrier failed to deliver the message to the recipient
`delivery_unconfirmed`	No delivery confirmation was received from the carrier

When a message fails, the errors array in the payload contains details:

{
  "errors": [
    {
      "code": "40300",
      "title": "Destination number unreachable",
      "detail": "The destination number is not reachable on the carrier network.",
      "source": { "pointer": "/to/0/phone_number" }
    }
  ]
}

Common error codes:

Code	Meaning
`40001`	Destination number invalid
`40002`	Destination number not in service
`40300`	Destination unreachable
`40008`	Message filtered by carrier
`40010`	Message blocked (spam/content filter)
`47000`	10DLC campaign required

For a complete list, see the Error Codes reference.

Webhook signature verification

Telnyx signs every webhook using Ed25519 public key cryptography so you can verify that requests genuinely come from Telnyx. This is strongly recommended for production deployments. Each webhook request includes two headers:

Header	Description
`telnyx-signature-ed25519`	Base64-encoded Ed25519 signature
`telnyx-timestamp`	Unix timestamp of when the request was signed

The signature is computed over the string {timestamp}|{json_payload}.

Get your public key

Find your public key in the Mission Control Portal under Keys & Credentials → Public Key.

Verification examples

Node

import express from 'express';
import Telnyx from 'telnyx';

const app = express();
app.use(express.json());

const telnyx = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

app.post('/webhooks', (req, res) => {
  const signature = req.headers['telnyx-signature-ed25519'];
  const timestamp = req.headers['telnyx-timestamp'];
  const payload = JSON.stringify(req.body);

  try {
    const event = telnyx.webhooks.constructEvent(
      payload,
      signature,
      timestamp,
      process.env.TELNYX_PUBLIC_KEY
    );
    console.log('Verified event:', event.data.event_type);
    res.sendStatus(200);
  } catch (err) {
    console.error('Signature verification failed:', err.message);
    res.sendStatus(403);
  }
});

app.listen(5000, () => console.log('Server running on port 5000'));

Python

from flask import Flask, request
import telnyx

app = Flask(__name__)
telnyx.api_key = "YOUR_API_KEY"
telnyx.public_key = "YOUR_PUBLIC_KEY"

@app.route('/webhooks', methods=['POST'])
def webhooks():
    payload = request.data
    signature = request.headers.get('telnyx-signature-ed25519')
    timestamp = request.headers.get('telnyx-timestamp')

    try:
        event = telnyx.Webhook.construct_event(payload, signature, timestamp)
        print(f"Verified event: {event['data']['event_type']}")
        return '', 200
    except telnyx.error.SignatureVerificationError:
        return 'Invalid signature', 403

Ruby

require 'sinatra'
require 'telnyx'
require 'json'

Telnyx.api_key = ENV['TELNYX_API_KEY']
Telnyx.public_key = ENV['TELNYX_PUBLIC_KEY']

post '/webhooks' do
  payload = request.body.read
  signature = request.env['HTTP_TELNYX_SIGNATURE_ED25519']
  timestamp = request.env['HTTP_TELNYX_TIMESTAMP']

  begin
    event = Telnyx::Webhook.construct_event(payload, signature, timestamp)
    puts "Verified event: #{event['data']['event_type']}"
    status 200
  rescue Telnyx::SignatureVerificationError
    status 403
    body 'Invalid signature'
  end
end

package main

import (
  "crypto/ed25519"
  "encoding/base64"
  "fmt"
  "io"
  "net/http"
  "os"
)

func verifySignature(payload, signature, timestamp string, publicKey ed25519.PublicKey) bool {
  signedPayload := timestamp + "|" + payload
  sigBytes, err := base64.StdEncoding.DecodeString(signature)
  if err != nil {
    return false
  }
  return ed25519.Verify(publicKey, []byte(signedPayload), sigBytes)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  body, _ := io.ReadAll(r.Body)
  signature := r.Header.Get("telnyx-signature-ed25519")
  timestamp := r.Header.Get("telnyx-timestamp")

  pubKeyBytes, _ := base64.StdEncoding.DecodeString(os.Getenv("TELNYX_PUBLIC_KEY"))
  publicKey := ed25519.PublicKey(pubKeyBytes)

  if !verifySignature(string(body), signature, timestamp, publicKey) {
    http.Error(w, "Invalid signature", http.StatusForbidden)
    return
  }

  fmt.Println("Webhook verified and received")
  w.WriteHeader(http.StatusOK)
}

func main() {
  http.HandleFunc("/webhooks", webhookHandler)
  fmt.Println("Server running on port 5000")
  http.ListenAndServe(":5000", nil)
}

Java

package com.example.webhook;

import com.sun.net.httpserver.HttpServer;
import java.io.InputStream;
import java.net.InetSocketAddress;
import java.security.*;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

public class WebhookServer {
    private static boolean verifySignature(String payload, String signature,
                                           String timestamp, String publicKeyBase64) throws Exception {
        byte[] pubKeyBytes = Base64.getDecoder().decode(publicKeyBase64);
        KeyFactory keyFactory = KeyFactory.getInstance("Ed25519");
        PublicKey publicKey = keyFactory.generatePublic(new X509EncodedKeySpec(pubKeyBytes));

        Signature sig = Signature.getInstance("Ed25519");
        sig.initVerify(publicKey);
        sig.update((timestamp + "|" + payload).getBytes());
        return sig.verify(Base64.getDecoder().decode(signature));
    }

    public static void main(String[] args) throws Exception {
        String publicKeyBase64 = System.getenv("TELNYX_PUBLIC_KEY");

        HttpServer server = HttpServer.create(new InetSocketAddress(5000), 0);
        server.createContext("/webhooks", exchange -> {
            InputStream is = exchange.getRequestBody();
            String body = new String(is.readAllBytes());
            String signature = exchange.getRequestHeaders().getFirst("telnyx-signature-ed25519");
            String timestamp = exchange.getRequestHeaders().getFirst("telnyx-timestamp");

            try {
                if (verifySignature(body, signature, timestamp, publicKeyBase64)) {
                    System.out.println("Webhook verified");
                    exchange.sendResponseHeaders(200, -1);
                } else {
                    exchange.sendResponseHeaders(403, -1);
                }
            } catch (Exception e) {
                exchange.sendResponseHeaders(500, -1);
            }
        });

        server.start();
        System.out.println("Server running on port 5000");
    }
}

.NET

// Requires: dotnet add package NSec.Cryptography
using System.Text;
using NSec.Cryptography;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/webhooks", async (HttpContext context) =>
{
    using var reader = new StreamReader(context.Request.Body);
    var body = await reader.ReadToEndAsync();
    var signature = context.Request.Headers["telnyx-signature-ed25519"].ToString();
    var timestamp = context.Request.Headers["telnyx-timestamp"].ToString();

    var publicKeyBytes = Convert.FromBase64String(
        Environment.GetEnvironmentVariable("TELNYX_PUBLIC_KEY")!);
    var signedPayload = Encoding.UTF8.GetBytes($"{timestamp}|{body}");
    var signatureBytes = Convert.FromBase64String(signature);

    var algorithm = SignatureAlgorithm.Ed25519;
    var publicKey = PublicKey.Import(algorithm, publicKeyBytes, KeyBlobFormat.RawPublicKey);

    if (algorithm.Verify(publicKey, signedPayload, signatureBytes))
    {
        Console.WriteLine("Webhook verified");
        return Results.Ok();
    }

    return Results.StatusCode(403);
});

app.Run("http://0.0.0.0:5000");

PHP

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_TELNYX_SIGNATURE_ED25519'] ?? '';
$timestamp = $_SERVER['HTTP_TELNYX_TIMESTAMP'] ?? '';
$publicKey = getenv('TELNYX_PUBLIC_KEY');

$signedPayload = $timestamp . '|' . $payload;
$sigBytes = base64_decode($signature);
$pubKeyBytes = base64_decode($publicKey);

$valid = sodium_crypto_sign_verify_detached($sigBytes, $signedPayload, $pubKeyBytes);

if (!$valid) {
    http_response_code(403);
    echo 'Invalid signature';
    exit;
}

http_response_code(200);
echo 'Webhook verified';

Timestamp tolerance: To prevent replay attacks, reject webhooks where telnyx-timestamp is more than 5 minutes old.

Handling webhooks in your application

Basic webhook handler

Node

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks', (req, res) => {
  // Respond immediately to avoid timeout
  res.sendStatus(200);

  const { data } = req.body;

  switch (data.event_type) {
    case 'message.received':
      handleInboundMessage(data.payload);
      break;
    case 'message.sent':
      handleMessageSent(data.payload);
      break;
    case 'message.finalized':
      handleDeliveryReceipt(data.payload);
      break;
  }
});

function handleInboundMessage(payload) {
  const from = payload.from.phone_number;
  const text = payload.text;
  console.log(`Inbound from ${from}: ${text}`);

  // Check for MMS media
  if (payload.media?.length > 0) {
    payload.media.forEach(m => console.log(`Media: ${m.url} (${m.content_type})`));
  }
}

function handleMessageSent(payload) {
  console.log(`Message ${payload.id} sent to carrier`);
}

function handleDeliveryReceipt(payload) {
  const status = payload.to[0]?.status;
  console.log(`Message ${payload.id} finalized: ${status}`);

  if (status === 'delivery_failed') {
    console.error('Delivery failed:', payload.errors);
  }
}

app.listen(5000, () => console.log('Webhook server running on port 5000'));

Python

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def webhooks():
    data = request.json.get('data', {})
    event_type = data.get('event_type')
    payload = data.get('payload', {})

    if event_type == 'message.received':
        handle_inbound_message(payload)
    elif event_type == 'message.sent':
        handle_message_sent(payload)
    elif event_type == 'message.finalized':
        handle_delivery_receipt(payload)

    return '', 200

def handle_inbound_message(payload):
    from_number = payload['from']['phone_number']
    text = payload.get('text', '')
    print(f"Inbound from {from_number}: {text}")

    for media in payload.get('media', []):
        print(f"Media: {media['url']} ({media['content_type']})")

def handle_message_sent(payload):
    print(f"Message {payload['id']} sent to carrier")

def handle_delivery_receipt(payload):
    status = payload['to'][0]['status']
    print(f"Message {payload['id']} finalized: {status}")

    if status == 'delivery_failed':
        print(f"Delivery failed: {payload.get('errors')}")

if __name__ == '__main__':
    app.run(port=5000)

Ruby

require 'sinatra'
require 'json'

post '/webhooks' do
  body = JSON.parse(request.body.read)
  data = body['data']
  payload = data['payload']

  case data['event_type']
  when 'message.received'
    puts "Inbound from #{payload['from']['phone_number']}: #{payload['text']}"
    payload['media']&.each { |m| puts "Media: #{m['url']}" }
  when 'message.sent'
    puts "Message #{payload['id']} sent to carrier"
  when 'message.finalized'
    status_val = payload['to'][0]['status']
    puts "Message #{payload['id']} finalized: #{status_val}"
    puts "Errors: #{payload['errors']}" if status_val == 'delivery_failed'
  end

  status 200
end

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
)

type Webhook struct {
  Data struct {
    EventType string `json:"event_type"`
    Payload   struct {
      ID   string `json:"id"`
      From struct {
        PhoneNumber string `json:"phone_number"`
      } `json:"from"`
      To []struct {
        PhoneNumber string `json:"phone_number"`
        Status      string `json:"status"`
      } `json:"to"`
      Text   string `json:"text"`
      Media  []struct {
        URL         string `json:"url"`
        ContentType string `json:"content_type"`
      } `json:"media"`
      Errors []struct {
        Code   string `json:"code"`
        Title  string `json:"title"`
      } `json:"errors"`
    } `json:"payload"`
  } `json:"data"`
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  var wh Webhook
  json.NewDecoder(r.Body).Decode(&wh)

  switch wh.Data.EventType {
  case "message.received":
    fmt.Printf("Inbound from %s: %s\n", wh.Data.Payload.From.PhoneNumber, wh.Data.Payload.Text)
    for _, m := range wh.Data.Payload.Media {
      fmt.Printf("Media: %s (%s)\n", m.URL, m.ContentType)
    }
  case "message.sent":
    fmt.Printf("Message %s sent to carrier\n", wh.Data.Payload.ID)
  case "message.finalized":
    if len(wh.Data.Payload.To) > 0 {
      fmt.Printf("Message %s finalized: %s\n", wh.Data.Payload.ID, wh.Data.Payload.To[0].Status)
    }
  }

  w.WriteHeader(http.StatusOK)
}

func main() {
  http.HandleFunc("/webhooks", webhookHandler)
  fmt.Println("Webhook server running on port 5000")
  http.ListenAndServe(":5000", nil)
}

Java

package com.example.webhook;

import com.sun.net.httpserver.HttpServer;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.InputStream;
import java.net.InetSocketAddress;

public class WebhookServer {
    public static void main(String[] args) throws Exception {
        HttpServer server = HttpServer.create(new InetSocketAddress(5000), 0);

        server.createContext("/webhooks", exchange -> {
            InputStream is = exchange.getRequestBody();
            String body = new String(is.readAllBytes());
            JsonObject json = JsonParser.parseString(body).getAsJsonObject();
            JsonObject data = json.getAsJsonObject("data");
            String eventType = data.get("event_type").getAsString();
            JsonObject payload = data.getAsJsonObject("payload");

            switch (eventType) {
                case "message.received":
                    String from = payload.getAsJsonObject("from")
                        .get("phone_number").getAsString();
                    String text = payload.get("text").getAsString();
                    System.out.println("Inbound from " + from + ": " + text);
                    break;
                case "message.sent":
                    System.out.println("Message " + payload.get("id").getAsString() + " sent");
                    break;
                case "message.finalized":
                    String status = payload.getAsJsonArray("to").get(0)
                        .getAsJsonObject().get("status").getAsString();
                    System.out.println("Message " + payload.get("id").getAsString()
                        + " finalized: " + status);
                    break;
            }

            exchange.sendResponseHeaders(200, -1);
        });

        server.start();
        System.out.println("Webhook server running on port 5000");
    }
}

.NET

using Microsoft.AspNetCore.Mvc;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/webhooks", async (HttpContext context) =>
{
    using var reader = new StreamReader(context.Request.Body);
    var body = await reader.ReadToEndAsync();
    var json = JsonDocument.Parse(body);
    var data = json.RootElement.GetProperty("data");
    var eventType = data.GetProperty("event_type").GetString();
    var payload = data.GetProperty("payload");

    switch (eventType)
    {
        case "message.received":
            var from = payload.GetProperty("from").GetProperty("phone_number").GetString();
            var text = payload.GetProperty("text").GetString();
            Console.WriteLine($"Inbound from {from}: {text}");
            break;
        case "message.sent":
            Console.WriteLine($"Message {payload.GetProperty("id").GetString()} sent");
            break;
        case "message.finalized":
            var status = payload.GetProperty("to")[0].GetProperty("status").GetString();
            Console.WriteLine($"Message {payload.GetProperty("id").GetString()} finalized: {status}");
            break;
    }

    return Results.Ok();
});

app.Run("http://0.0.0.0:5000");

PHP

<?php
$body = json_decode(file_get_contents('php://input'), true);
$data = $body['data'] ?? [];
$eventType = $data['event_type'] ?? '';
$payload = $data['payload'] ?? [];

switch ($eventType) {
    case 'message.received':
        $from = $payload['from']['phone_number'];
        $text = $payload['text'] ?? '';
        echo "Inbound from {$from}: {$text}\n";

        foreach ($payload['media'] ?? [] as $media) {
            echo "Media: {$media['url']} ({$media['content_type']})\n";
        }
        break;

    case 'message.sent':
        echo "Message {$payload['id']} sent to carrier\n";
        break;

    case 'message.finalized':
        $status = $payload['to'][0]['status'] ?? 'unknown';
        echo "Message {$payload['id']} finalized: {$status}\n";

        if ($status === 'delivery_failed') {
            echo "Errors: " . json_encode($payload['errors']) . "\n";
        }
        break;
}

http_response_code(200);

Retry behavior and error handling

Retry policy

Behavior	Detail
Timeout	Your endpoint must respond within 2 seconds (API v2)
Retries	Up to 3 attempts per URL with exponential backoff
Failover	If all retries fail, Telnyx tries the failover URL (if configured)
Total attempts	Up to 6 total (3 primary + 3 failover)
Success response	Any `2xx` status code
Failure response	Any non-`2xx` response, including `3xx` redirects

Best practices for reliability

Respond immediately — Return 200 before processing the event. Offload heavy logic to a background queue.
Handle duplicates — Webhooks may be delivered more than once. Use the data.id field as an idempotency key.
Handle out-of-order delivery — Events may arrive in a different order than they occurred. Use data.occurred_at timestamps to sequence events.
Use HTTPS — Always use TLS-encrypted endpoints in production.
Verify signatures — Validate telnyx-signature-ed25519 headers to prevent spoofing.

Webhook IP allowlist

If your server uses a firewall or ACL, allowlist the following Telnyx subnet:

192.76.120.192/27

Troubleshooting

Check your messaging profile — Confirm a webhook URL is configured in the Portal or via the API.

Test your endpoint — Send a test POST request with curl to ensure your server is accessible:

curl -X POST https://your-endpoint.com/webhooks \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Check ngrok — If using ngrok, verify the tunnel is running and the URL matches your profile configuration.
Check firewall — Ensure 192.76.120.192/27 is allowlisted.
Check Message Detail Records — Events are logged regardless of webhook delivery. Check MDRs in the portal.

This is expected behavior. Telnyx may deliver the same webhook more than once, especially during retries. Track processed event IDs (data.id) and skip duplicates:

const processedEvents = new Set();

app.post('/webhooks', (req, res) => {
  const eventId = req.body.data.id;
  if (processedEvents.has(eventId)) {
    return res.sendStatus(200); // Already processed
  }
  processedEvents.add(eventId);
  // Process event...
  res.sendStatus(200);
});

For production, use a persistent store (Redis, database) instead of in-memory sets. Telnyx does not guarantee delivery order. For example, message.finalized may arrive before message.sent. Use the data.occurred_at timestamp to determine event sequence, and design your logic to handle any arrival order.

Ensure you’re reading the raw body — Parse the signature against the raw request body, not a re-serialized JSON object.
Check your public key — Verify you’re using the correct public key from the Portal.
Check timestamp tolerance — If you’re rejecting stale timestamps, ensure your server clock is synchronized (NTP).

Your endpoint must respond within 2 seconds. If your processing takes longer:

Return 200 immediately
Process the event asynchronously (use a message queue like Redis, RabbitMQ, or SQS)

Next steps

Step-by-step guide to building a webhook server Send SMS and MMS with the Messaging API Platform-wide webhook concepts, signing, and retry behavior Query historical message data and delivery statuses

Choosing a Sender Type

Source: https://developers.telnyx.com/docs/messaging/getting-started/choosing-your-sender-type.md

Interactive Product Selector

Answer a few quick questions to get a personalized recommendation: This is a high-level recommendation. Contact Telnyx Sales for detailed guidance on complex use cases.

Use Case Decision Tree

Not sure which sender type fits? Start with your primary use case: Best options:

Toll-free — Fast provisioning (2–3 days), high throughput, handset-level delivery receipts. Ideal for US/CA transactional messaging.
10DLC long code — Good alternative if you want a local presence. Requires brand + campaign registration (2–3 business days).
Short code — Best for very high volume (200+ MPS). Longer provisioning (2–6 weeks) and higher cost.

For OTP/2FA specifically, see our Two-Factor Authentication guide. Best options:

10DLC long code — Required for A2P marketing in the US. Register your brand and campaign through 10DLC registration.
Toll-free — Good for mixed marketing + transactional. Requires toll-free verification.
Short code — Premium option for brand recognition and highest throughput.
RCS — Rich media cards, carousels, and suggested actions for supported devices.

Best options:

10DLC long code — Local number feel, supports voice + SMS on the same number.
Toll-free — Works well for two-way if local presence isn’t important.
RCS — Rich interactive experience with read receipts, typing indicators, and suggested replies.

Alphanumeric sender IDs are one-way only — recipients cannot reply. Best options:

Alphanumeric sender ID — Supported in 100+ countries. No number procurement needed. Great for brand recognition internationally.
Local long codes — Required in some countries. Use the coverage checker below for availability.

US toll-free and short code numbers only work for US/CA destinations. For international, use alphanumeric IDs or local numbers. Best options:

RCS — Full rich media support: images, video, carousels, suggested actions, branded sender profiles.
MMS via long code/toll-free — Image and video support for US/CA only.

See our RCS Getting Started guide for details.

Sender Comparison

Capabilities at a Glance

	10DLC Long Code	Toll-Free	Short Code	RCS	Alphanumeric
Brand Recognition	Local number	Brand	Brand	Brand (verified)	Brand name
Throughput	3–75 MPS*	3–150 MPS	200+ MPS	100+ MPS	100+ MPS
Daily Volume Limits	10K–200K (T-Mobile)**	Unlimited	Unlimited	Unlimited	Unlimited
Two-Way Messaging	✅ Yes	✅ Yes	✅ Yes	✅ Yes	❌ No
Voice Support	✅ Yes	✅ Yes	❌ No	❌ No	❌ No
Delivery Receipts	Carrier only	Handset	Handset	Handset	Handset
MMS Support	US/CA only	US/CA only	US/CA only	Rich media	❌ No
Opt-Out Management	Telnyx managed	Network managed	Telnyx managed	Telnyx managed	N/A

* Throughput varies based on TCR Trust Score. ** T-Mobile daily limits based on TCR brand score; can be increased upon request.

Registration & Cost Comparison

Understanding the time and cost investment for each sender type helps you plan your launch:

	10DLC Long Code	Toll-Free	Short Code	RCS	Alphanumeric
Provisioning Time	2–3 business days	2–3 business days	2–6 weeks	6–10 weeks	Instant
Registration Required	Brand + Campaign (TCR)	Toll-free verification	Carrier approval	Google verification	None
Number Procurement Cost	Low (~$1/mo)	Low (~$2/mo)	High (~$500–1000/mo)	Agent setup fee	Free
Per-Message Cost	Standard rates	Standard rates	Premium rates	Standard rates	Standard rates
Renewal/Ongoing	Annual brand vetting	One-time verification	Monthly lease	Ongoing	None

Register your brand and campaign for US A2P messaging. Verify your toll-free number for higher throughput. Apply for a dedicated short code. Set up RCS business messaging with rich media. Send branded one-way messages internationally. Bring your existing numbers to Telnyx messaging.

Check Coverage by Country

Sender type availability varies by country. Use the tool below to check which options are available for your destination:

Key Regional Considerations

10DLC is required for A2P messaging to US mobile numbers (enforced by carriers since 2023)
Toll-free numbers work for both US and CA
Short codes are country-specific (US short codes don’t work in CA and vice versa)
MMS is supported on long code, toll-free, and short code
RCS is available for Android users
Alphanumeric sender IDs are widely supported and commonly used
Some countries require pre-registration of alphanumeric IDs (e.g., UK, France)
Local long codes may be required for two-way messaging
Short codes are available in select markets
GDPR compliance required for all messaging
Alphanumeric sender IDs supported in most countries
Local long codes recommended for better deliverability
Some carriers require pre-approved sender IDs or templates
WhatsApp is dominant — consider RCS as an alternative rich channel
Regulations vary significantly by country
India requires DLT registration and approved templates
Australia supports alphanumeric IDs and local numbers
Some countries require local entity for number procurement
Check coverage tool above for specific country details

Quick Start: Send Your First Message

Once you’ve chosen your sender type, sending a message uses the same API regardless of sender:

cURL

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Hello from Telnyx!"
  }'

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"

message = telnyx.Message.create(
    from_="+15551234567",
    to="+15559876543",
    text="Hello from Telnyx!"
)
print(message.id)

Node.js

const telnyx = require('telnyx')('YOUR_API_KEY');

const message = await telnyx.messages.create({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Hello from Telnyx!'
});
console.log(message.data.id);

Ruby

require 'telnyx'

Telnyx.api_key = 'YOUR_API_KEY'

message = Telnyx::Message.create(
  from: '+15551234567',
  to: '+15559876543',
  text: 'Hello from Telnyx!'
)
puts message.id

Java

import com.telnyx.sdk.*;
import com.telnyx.sdk.api.MessagesApi;
import com.telnyx.sdk.model.CreateMessageRequest;

ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

MessagesApi api = new MessagesApi(client);
CreateMessageRequest request = new CreateMessageRequest()
    .from("+15551234567")
    .to("+15559876543")
    .text("Hello from Telnyx!");

api.createMessage(request);

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey("YOUR_API_KEY");

var service = new MessagingSenderIdService();
var message = service.CreateMessage(new NewMessage
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Hello from Telnyx!"
});
Console.WriteLine(message.Id);

PHP

require 'vendor/autoload.php';

$telnyx = new \Telnyx\TelnyxClient('YOUR_API_KEY');

$message = $telnyx->messages->create([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => 'Hello from Telnyx!'
]);
echo $message->id;

package main

import (
    "context"
    "fmt"
    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient("YOUR_API_KEY")

    message, err := client.Messages.Create(context.Background(),
        &telnyx.MessageParams{
            From: "+15551234567",
            To:   "+15559876543",
            Text: "Hello from Telnyx!",
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(message.ID)
}

The from field determines your sender type automatically:

Phone number (+15551234567) → Long code or toll-free
Short code (12345) → Short code
Alphanumeric ("MyBrand") → Alphanumeric sender ID

You can also use a Messaging Profile to let Telnyx select the best sender from your number pool.

Next Steps

Complete guide to sending your first SMS/MMS. Configure number pools, webhooks, and features. Understand throughput tiers and daily caps.

Message Encoding

Source: https://developers.telnyx.com/docs/messaging/messages/message-encoding.md

SMS messages are encoded into segments of 140 bytes each. You are billed per segment, so understanding encoding is key to controlling costs. The encoding determines how many characters fit in each segment:

Encoding	Bits per char	Single segment	Multi-part segment
GSM 7-bit	7	160 chars	153 chars
ASCII 7-bit	7	160 chars	153 chars
ASCII 8-bit	8	140 chars	134 chars
UTF-16	16	70 chars	67 chars

A single non-GSM-7 character (like an emoji or curly quote) switches the entire message to UTF-16, cutting capacity from 160 to 70 characters per segment. This can more than double your costs.

Segment calculator

Use this interactive tool to check how your message will be encoded and segmented:

How segments work

Every SMS message is transmitted in units of 140 bytes. When a message exceeds one segment, a 6-byte header (User Data Header, or UDH) is added to each segment for reassembly, reducing the usable space.

Single segment:   140 bytes available → 160 GSM-7 chars or 70 UTF-16 chars
Multi-part:       134 bytes per segment → 153 GSM-7 chars or 67 UTF-16 chars
Maximum:          10 segments per message

Segment calculation formula

To calculate the number of segments for a message:

Characters ≤ 160  →  1 segment
Characters > 160  →  ⌈characters / 153⌉ segments

Examples:
- 100 chars = 1 segment
- 160 chars = 1 segment
- 161 chars = 2 segments (153 + 8)
- 306 chars = 2 segments (153 + 153)
- 307 chars = 3 segments (153 + 153 + 1)
- 1530 chars = 10 segments (maximum)

Characters ≤ 70   →  1 segment
Characters > 70   →  ⌈characters / 67⌉ segments

Examples:
- 50 chars = 1 segment
- 70 chars = 1 segment
- 71 chars = 2 segments (67 + 4)
- 134 chars = 2 segments (67 + 67)
- 135 chars = 3 segments (67 + 67 + 1)
- 670 chars = 10 segments (maximum)

Cost impact example

Consider a 200-character message:

Scenario	Encoding	Segments	Relative cost
All GSM-7 characters	GSM-7	2	2×
Contains one emoji 😀	UTF-16	3	3×
Contains one curly quote “	UTF-16	3	3×
With smart encoding enabled	GSM-7	2	2×

Enable smart encoding to automatically replace common Unicode characters (like curly quotes and em dashes) with GSM-7 equivalents, reducing segment counts.

Encoding by sender type

Sender type	Default encoding	Fallback
Long Code	GSM 7-bit	UTF-16
Toll-Free	GSM 7-bit	UTF-16
Short Code	ASCII 7-bit	UTF-16
Alphanumeric	GSM 7-bit	UTF-16

If your message contains characters outside the default encoding’s character set, the fallback encoding is used automatically for the entire message. MMS and RCS messages use UTF-8 encoding by default and are not affected by these limits.

GSM 7-bit character set

Telnyx uses a GSM 7-bit encoding optimized for maximum carrier compatibility. Only characters in this set will keep your message in the efficient GSM-7 encoding. Letters:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o p q r s t u v w x y z

Digits:

0 1 2 3 4 5 6 7 8 9

Symbols and punctuation:

! " # $ % & ' ( ) * + , - . / : ; < = > ? @

Special characters:

Character	Description
`space`	Space
`\n`	Line feed
`\r`	Carriage return
`_`	Underscore
`£`	Pound sign
`¥`	Yen sign
`è`	e grave
`é`	e acute
`ù`	u grave
`ì`	i grave
`ò`	o grave
`Ø`	O with stroke
`ø`	o with stroke
`Å`	A with ring
`å`	a with ring
`Æ`	AE ligature
`æ`	ae ligature
`ß`	Sharp s
`É`	E acute
`¡`	Inverted exclamation
`Ä`	A umlaut
`Ö`	O umlaut
`Ñ`	N tilde
`Ü`	U umlaut
`§`	Section sign
`¿`	Inverted question
`ä`	a umlaut
`ö`	o umlaut
`ñ`	n tilde
`ü`	u umlaut
`à`	a grave

These characters require an escape sequence and count as 2 characters in segment calculations:

Character	Description	Character count
`~`	Tilde	2
`^`	Circumflex	2
`\|`	Pipe / vertical bar	2
`\`	Backslash	2
`{`	Left curly bracket	2
`}`	Right curly bracket	2
`[`	Left square bracket	2
`]`	Right square bracket	2
`€`	Euro sign	2

Extended characters are easy to overlook when estimating segment counts. A message with 155 standard characters and 3 pipe characters (|) uses 155 + (3 × 2) = 161 character slots, requiring 2 segments instead of 1.

Detecting encoding in your application

Before sending, you can check if a message will use GSM-7 or UTF-16 encoding to estimate costs. Here are helper functions for each language:

Python

import re

# GSM-7 basic character set
GSM7_BASIC = set(
    "@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞ ÆæßÉ"
    " !\"#¤%&'()*+,-./0123456789:;<=>?"
    "¡ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    "ÄÖÑܧ¿abcdefghijklmnopqrstuvwxyz"
    "äöñüà"
)
GSM7_EXTENDED = set("^{}\\[~]|€")

def calculate_segments(text: str) -> dict:
    """Calculate encoding and segment count for an SMS message."""
    is_gsm7 = all(c in GSM7_BASIC or c in GSM7_EXTENDED for c in text)

    if is_gsm7:
        # Count extended chars as 2
        char_count = sum(2 if c in GSM7_EXTENDED else 1 for c in text)
        if char_count <= 160:
            segments = 1
        else:
            segments = -(-char_count // 153)  # ceiling division
        return {"encoding": "GSM-7", "char_count": char_count, "segments": segments}
    else:
        # UTF-16: emojis count as 2 chars (surrogate pairs)
        char_count = 0
        for c in text:
            char_count += 2 if ord(c) > 0xFFFF else 1
        if char_count <= 70:
            segments = 1
        else:
            segments = -(-char_count // 67)
        return {"encoding": "UTF-16", "char_count": char_count, "segments": segments}

# Example usage
result = calculate_segments("Hello, world!")
print(f"Encoding: {result['encoding']}, Segments: {result['segments']}")
# Output: Encoding: GSM-7, Segments: 1

result = calculate_segments("Hello 😀")
print(f"Encoding: {result['encoding']}, Segments: {result['segments']}")
# Output: Encoding: UTF-16, Segments: 1

Node

const GSM7_BASIC = new Set(
  '@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞ ÆæßÉ' +
  ' !"#¤%&\'()*+,-./0123456789:;<=>?' +
  '¡ABCDEFGHIJKLMNOPQRSTUVWXYZ' +
  'ÄÖÑܧ¿abcdefghijklmnopqrstuvwxyz' +
  'äöñüà'
);
const GSM7_EXTENDED = new Set('^{}\\[~]|€');

function calculateSegments(text) {
  const chars = [...text];
  const isGsm7 = chars.every(c => GSM7_BASIC.has(c) || GSM7_EXTENDED.has(c));

  if (isGsm7) {
    const charCount = chars.reduce(
      (sum, c) => sum + (GSM7_EXTENDED.has(c) ? 2 : 1), 0
    );
    const segments = charCount <= 160 ? 1 : Math.ceil(charCount / 153);
    return { encoding: 'GSM-7', charCount, segments };
  } else {
    const charCount = chars.reduce(
      (sum, c) => sum + (c.codePointAt(0) > 0xFFFF ? 2 : 1), 0
    );
    const segments = charCount <= 70 ? 1 : Math.ceil(charCount / 67);
    return { encoding: 'UTF-16', charCount, segments };
  }
}

// Example usage
console.log(calculateSegments('Hello, world!'));
// { encoding: 'GSM-7', charCount: 13, segments: 1 }

console.log(calculateSegments('Hello 😀'));
// { encoding: 'UTF-16', charCount: 8, segments: 1 }

Ruby

GSM7_BASIC = Set.new(
  "@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞ ÆæßÉ" \
  " !\"#¤%&'()*+,-./0123456789:;<=>?" \
  "¡ABCDEFGHIJKLMNOPQRSTUVWXYZ" \
  "ÄÖÑܧ¿abcdefghijklmnopqrstuvwxyz" \
  "äöñüà"
).flat_map(&:chars).to_set
GSM7_EXTENDED = Set.new("^{}\\[~]|€".chars)

def calculate_segments(text)
  chars = text.chars
  is_gsm7 = chars.all? { |c| GSM7_BASIC.include?(c) || GSM7_EXTENDED.include?(c) }

  if is_gsm7
    char_count = chars.sum { |c| GSM7_EXTENDED.include?(c) ? 2 : 1 }
    segments = char_count <= 160 ? 1 : (char_count.to_f / 153).ceil
    { encoding: "GSM-7", char_count: char_count, segments: segments }
  else
    char_count = chars.sum { |c| c.ord > 0xFFFF ? 2 : 1 }
    segments = char_count <= 70 ? 1 : (char_count.to_f / 67).ceil
    { encoding: "UTF-16", char_count: char_count, segments: segments }
  end
end

puts calculate_segments("Hello, world!")
# {:encoding=>"GSM-7", :char_count=>13, :segments=>1}

package main

import (
  "fmt"
  "math"
  "unicode/utf8"
)

var gsm7Basic = map[rune]bool{
  '@': true, '£': true, '$': true, '¥': true, 'è': true, 'é': true,
  'ù': true, 'ì': true, 'ò': true, 'Ç': true, '\n': true, 'Ø': true,
  'ø': true, '\r': true, 'Å': true, 'å': true, 'Δ': true, '_': true,
  'Φ': true, 'Γ': true, 'Λ': true, 'Ω': true, 'Π': true, 'Ψ': true,
  'Σ': true, 'Θ': true, 'Ξ': true, ' ': true, 'Æ': true, 'æ': true,
  'ß': true, 'É': true, '¡': true, 'Ä': true, 'Ö': true, 'Ñ': true,
  'Ü': true, '§': true, '¿': true, 'ä': true, 'ö': true, 'ñ': true,
  'ü': true, 'à': true,
}

var gsm7Extended = map[rune]bool{
  '^': true, '{': true, '}': true, '\\': true,
  '[': true, '~': true, ']': true, '|': true, '€': true,
}

func init() {
  // Add printable ASCII
  for c := '!'; c <= '~'; c++ {
    gsm7Basic[c] = true
  }
}

type SegmentResult struct {
  Encoding  string
  CharCount int
  Segments  int
}

func CalculateSegments(text string) SegmentResult {
  isGSM7 := true
  for _, r := range text {
    if !gsm7Basic[r] && !gsm7Extended[r] {
      isGSM7 = false
      break
    }
  }

  if isGSM7 {
    charCount := 0
    for _, r := range text {
      if gsm7Extended[r] {
        charCount += 2
      } else {
        charCount++
      }
    }
    segments := 1
    if charCount > 160 {
      segments = int(math.Ceil(float64(charCount) / 153))
    }
    return SegmentResult{"GSM-7", charCount, segments}
  }

  charCount := 0
  for _, r := range text {
    if r > 0xFFFF {
      charCount += 2
    } else {
      charCount++
    }
  }
  _ = utf8.RuneCountInString(text) // ensure valid UTF-8
  segments := 1
  if charCount > 70 {
    segments = int(math.Ceil(float64(charCount) / 67))
  }
  return SegmentResult{"UTF-16", charCount, segments}
}

func main() {
  fmt.Println(CalculateSegments("Hello, world!"))
  // {GSM-7 13 1}
}

Java

import java.util.Set;

public class SmsEncoding {

    private static final Set GSM7_EXTENDED =
        Set.of('^', '{', '}', '\\', '[', '~', ']', '|', '€');

    private static final String GSM7_CHARS =
        "@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞ ÆæßÉ"
        + " !\"#¤%&'()*+,-./0123456789:;<=>?"
        + "¡ABCDEFGHIJKLMNOPQRSTUVWXYZ"
        + "ÄÖÑܧ¿abcdefghijklmnopqrstuvwxyz"
        + "äöñüà^{}\\[~]|€";

    private static final Set GSM7_BASIC = new java.util.HashSet<>();
    static {
        for (char c : GSM7_CHARS.toCharArray()) {
            GSM7_BASIC.add(c);
        }
    }

    public record SegmentResult(String encoding, int charCount, int segments) {}

    public static SegmentResult calculateSegments(String text) {
        boolean isGsm7 = text.chars()
            .mapToObj(c -> (char) c)
            .allMatch(c -> GSM7_BASIC.contains(c) || GSM7_EXTENDED.contains(c));

        if (isGsm7) {
            int charCount = text.chars()
                .map(c -> GSM7_EXTENDED.contains((char) c) ? 2 : 1)
                .sum();
            int segments = charCount <= 160 ? 1 : (int) Math.ceil(charCount / 153.0);
            return new SegmentResult("GSM-7", charCount, segments);
        } else {
            int charCount = text.codePoints()
                .map(cp -> cp > 0xFFFF ? 2 : 1)
                .sum();
            int segments = charCount <= 70 ? 1 : (int) Math.ceil(charCount / 67.0);
            return new SegmentResult("UTF-16", charCount, segments);
        }
    }

    public static void main(String[] args) {
        System.out.println(calculateSegments("Hello, world!"));
        // SegmentResult[encoding=GSM-7, charCount=13, segments=1]
    }
}

.NET

using System;
using System.Collections.Generic;
using System.Linq;

public record SegmentResult(string Encoding, int CharCount, int Segments);

public static class SmsEncoding
{
    private static readonly HashSet Gsm7Extended =
        new("^{}\\[~]|€");

    private static readonly HashSet Gsm7Basic = new(
        "@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞ ÆæßÉ"
        + " !\"#¤%&'()*+,-./0123456789:;<=>?"
        + "¡ABCDEFGHIJKLMNOPQRSTUVWXYZ"
        + "ÄÖÑܧ¿abcdefghijklmnopqrstuvwxyz"
        + "äöñüà"
    );

    public static SegmentResult CalculateSegments(string text)
    {
        bool isGsm7 = text.All(c => Gsm7Basic.Contains(c) || Gsm7Extended.Contains(c));

        if (isGsm7)
        {
            int charCount = text.Sum(c => Gsm7Extended.Contains(c) ? 2 : 1);
            int segments = charCount <= 160 ? 1 : (int)Math.Ceiling(charCount / 153.0);
            return new SegmentResult("GSM-7", charCount, segments);
        }
        else
        {
            int charCount = 0;
            for (int i = 0; i < text.Length; i++)
            {
                charCount += char.IsHighSurrogate(text[i]) ? 2 : 1;
                if (char.IsHighSurrogate(text[i])) i++; // skip low surrogate
            }
            int segments = charCount <= 70 ? 1 : (int)Math.Ceiling(charCount / 67.0);
            return new SegmentResult("UTF-16", charCount, segments);
        }
    }
}

// Usage:
// var result = SmsEncoding.CalculateSegments("Hello, world!");
// Console.WriteLine($"{result.Encoding}, {result.Segments} segment(s)");

PHP

<?php

function calculateSegments(string $text): array
{
    $gsm7Extended = str_split('^{}\\[~]|€');
    $gsm7Basic = str_split(
        "@£\$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞ ÆæßÉ"
        . " !\"#¤%&'()*+,-./0123456789:;<=>?"
        . "¡ABCDEFGHIJKLMNOPQRSTUVWXYZ"
        . "ÄÖÑܧ¿abcdefghijklmnopqrstuvwxyz"
        . "äöñüà"
    );
    $basicSet = array_flip($gsm7Basic);
    $extSet = array_flip($gsm7Extended);

    $chars = mb_str_split($text);
    $isGsm7 = true;
    foreach ($chars as $c) {
        if (!isset($basicSet[$c]) && !isset($extSet[$c])) {
            $isGsm7 = false;
            break;
        }
    }

    if ($isGsm7) {
        $charCount = array_sum(array_map(
            fn($c) => isset($extSet[$c]) ? 2 : 1, $chars
        ));
        $segments = $charCount <= 160 ? 1 : (int) ceil($charCount / 153);
        return ['encoding' => 'GSM-7', 'char_count' => $charCount, 'segments' => $segments];
    }

    $charCount = 0;
    foreach ($chars as $c) {
        $charCount += mb_ord($c) > 0xFFFF ? 2 : 1;
    }
    $segments = $charCount <= 70 ? 1 : (int) ceil($charCount / 67);
    return ['encoding' => 'UTF-16', 'char_count' => $charCount, 'segments' => $segments];
}

// Usage
$result = calculateSegments("Hello, world!");
echo "{$result['encoding']}, {$result['segments']} segment(s)\n";
// GSM-7, 1 segment(s)

Common encoding issues

Symptom: Your message uses more segments than expected. Cause: A non-GSM-7 character is present, forcing the entire message to UTF-16. Common culprits:

Character	Source	GSM-7?
`"` `"` (curly quotes)	Word processors, mobile keyboards	❌
`'` `'` (curly apostrophes)	Auto-correct, CMS platforms	❌
`—` (em dash)	Word processors	❌
`…` (ellipsis)	Mobile keyboards	❌
`€` (euro sign)	Manual entry	✅ (extended, costs 2 chars)

Fix:

Enable smart encoding to auto-replace these characters
Or manually replace them with GSM-7 equivalents before sending

Symptom: Adding a single emoji doubles or triples the number of segments. Cause: Emojis force UTF-16 encoding (70 chars/segment instead of 160). Additionally, most emojis use surrogate pairs and count as 2 UTF-16 characters. Example:

"Thanks for your order!"        → GSM-7, 1 segment (22 chars)
"Thanks for your order! 🎉"     → UTF-16, 1 segment (25 chars)
"Thanks for your order! ... 🎉" → UTF-16, 2 segments (71+ chars)

Fix: If cost is a concern, avoid emojis in SMS. Use emojis freely in MMS/RCS where encoding isn’t a factor. Symptom: A 155-character message that looks like it should fit in one segment actually requires two. Cause: Characters like [, ], {, }, |, \, ^, ~, and € are in the GSM-7 extended set and count as 2 characters each. Example:

"Price: $100 [USD]" → 18 visible chars but 20 GSM-7 chars ([ and ] each cost 2)

Fix: Account for extended characters when calculating message length. Use the segment calculator above or the SDK helpers in this guide. Symptom: Text that looks like normal ASCII actually contains Unicode characters. Cause: Word processors often replace straight quotes with curly quotes, hyphens with em dashes, and three periods with an ellipsis character. These are invisible differences that force UTF-16. Fix:

Enable smart encoding — this handles the most common substitutions automatically
Sanitize text before sending by replacing known problem characters
Use the encoding parameter set to gsm7 to get a 400 error if non-GSM-7 characters are present (fail-fast approach)

Symptom: The recipient sees a message split in unexpected places, or parts arrive out of order. Cause: Multi-part messages are reassembled by the recipient’s device using the UDH (User Data Header). Some older devices or carriers may not support reassembly for messages over a certain number of segments. Fix:

Keep messages under 3-4 segments for maximum compatibility
Telnyx supports up to 10 segments, but recipient device support varies
Consider using MMS for longer content

Symptom: Messages in non-Latin scripts use significantly more segments than English messages of similar visible length. Cause: Non-Latin characters have no GSM-7 equivalents, so the entire message uses UTF-16 encoding (70 characters per segment). Smart encoding cannot help here. Fix:

This is expected behavior — plan for higher segment counts when messaging in non-Latin scripts
Keep messages concise
Consider MMS for longer non-Latin content

Best practices

Turn on smart encoding on your messaging profile to automatically handle Unicode-to-GSM-7 substitutions. This is the single biggest cost-saving measure. Use the encoding detection helpers above to check segment counts before sending. Alert your application when messages will be unexpectedly expensive. If you accept user-generated content, sanitize it before sending. Strip or replace invisible Unicode characters, curly quotes, and other common problem characters. Stay under 160 characters (GSM-7) or 70 characters (UTF-16) to avoid multi-part message overhead. Each additional segment adds 7 characters of UDH overhead. For messages that need emojis, rich formatting, or non-Latin scripts, consider MMS or RCS instead of SMS.

Automatically replace Unicode characters with GSM-7 equivalents to reduce costs. Get started with the Telnyx Messaging API. API reference for sending messages with encoding options. Configure smart encoding and other profile settings.

Rate Limiting

Source: https://developers.telnyx.com/docs/messaging/messages/rate-limiting.md

This guide covers message delivery throughput. For API request limits, see API Rate Limiting.

Rate Limits

The following are the default rate limits applied by Telnyx for each message type and sender type.

Account

Message Type	Default Rate Limit	Max Queue Length
SMS	50 messages/second	720,000
MMS	15 messages/second	216,000
RCS	1 message/second	14,400

Sender

Sender Type	Rate Limit	Per	Max Queue Length
Long Code	0.1 MPS	Number	1,440
Toll-Free	20 MPS	Number	288,000
Short Code	1,000 MPS	Number	14,400,000
Alphanumeric	0.1 MPS	Sender ID	1,440

The default Long Code rate limit applies to non-US destinations. For US destinations, throughput is determined at the campaign level based on your 10DLC registration. See 10DLC for carrier-specific limits. If you need an increased rate limit, contact Telnyx sales to discuss your options.

10DLC

When using US long codes for A2P messaging, throughput is determined by mobile network operators (MNOs) based on your registered 10DLC campaign. Each carrier has different throughput systems. AT&T assigns throughput per campaign based on “Message Class,” determined by use case type and vetting score.

Message Class	Use Case Type	Vetting Score	SMS TPM	MMS TPM
A	Standard (Dedicated)	75-100	4,500	2,400
B	Standard (Mixed/Marketing)	75-100	4,500	2,400
C	Standard (Dedicated)	50-74	2,400	1,200
D	Standard (Mixed/Marketing)	50-74	2,400	1,200
E	Standard (Dedicated)	1-49	240	150
F	Standard (Mixed/Marketing)	1-49	240	150
T	Low Volume Mixed	-	75	50
K	Political	-	4,500	2,400
P	Charity	-	2,400	1,200
S	Social	-	9,000	2,400
X	Emergency / Public Safety	-	4,500	2,400
W	Sole Proprietor	-	15	50
G	Proxy	-	60/number	50/number
N	Agents and Franchises	-	60/number	50/number

TPM = Throughput Per Minute. For standard use cases, the vetting score from your 10DLC brand registration determines which message class (and throughput) your campaign receives. Special use cases have fixed throughput regardless of vetting score. T-Mobile assigns daily message caps at the brand level, shared across all campaigns under that brand.

Brand Tier	Vetting Score	Daily Cap
Top	75-100	200,000
High Mid	50-74	40,000
Low Mid	25-49	10,000
Low	1-24	2,000

Unvetted brands default to Low tier unless listed on the Russell 3000. Sole Proprietor campaigns have a 1,000 daily cap. Verizon has not published specific throughput limits but uses content filtering for 10DLC traffic.

Queuing

When you send messages faster than your rate limit allows, excess messages are automatically queued for delivery.

How Queuing Works

Message submitted — Request validated against your Messaging Profile
Rate limit check — Under limit: sent immediately. Over limit: queued
Queue processing — Messages held up to 4 hours, released in FIFO order
Delivery — Sent to carrier, webhook fired, visible in MDR search

Calculating Queue Size

Each sender type and message type combination has its own queue. The maximum queue length is:

Max Queue Length = Rate Limit (MPS) × 14,400 seconds (4 hours)

The following examples illustrate how sender and account queues interact: Acme Corp sends SMS from a single Toll-Free number. Their application submits messages at 50 MPS, but the Toll-Free rate limit is 20 MPS.

Queue	Rate Limit	Max Queue Length
Toll-Free #1	20 MPS	288,000 segments

Messages are delivered at 20 MPS, but 30 MPS (50 - 20) accumulates in the queue. After 4 hours of sustained sending, the queue reaches its 288,000 segment limit. Any additional messages return error 40318 (queue full). Acme Corp sends SMS from 5 Toll-Free numbers simultaneously, each at 20 MPS.

Queue	Rate Limit	Max Queue Length
Toll-Free #1	20 MPS	288,000 segments
Toll-Free #2	20 MPS	288,000 segments
Toll-Free #3	20 MPS	288,000 segments
Toll-Free #4	20 MPS	288,000 segments
Toll-Free #5	20 MPS	288,000 segments
Account SMS	50 MPS	720,000 segments

Combined sender capacity is 100 MPS (5 × 20), but the account limit is 50 MPS. Messages exceeding the account limit queue at the account level. Once the account queue (720,000) fills, additional messages return error 40318. Acme Corp sends SMS from 10 Long Code numbers simultaneously, each at 0.1 MPS.

Queue	Rate Limit	Max Queue Length
Long Codes (10 total)	1 MPS combined	14,400 segments each
Account SMS	50 MPS	720,000 segments

Here, the sender limit (1 MPS combined) is well below the account limit (50 MPS). The sender queues will fill first. Each Long Code queue holds 1,440 segments — once full, messages to that specific number return error 40318, even though the account has capacity. When a queue is full, additional messages return error code 40318. See API Errors for details.

Monitoring Queued Messages

Queued messages return a queued status and won’t appear in MDR search until delivered. Monitor queue depth via the Mission Control Portal. To avoid queue buildup, implement client-side rate limiting to match your throughput limits. See Client-Side Rate Limiting below.

Client-Side Rate Limiting

Implementing rate limiting in your application prevents queue buildup, avoids 40318 errors, and gives you control over message pacing. The examples below show a token bucket rate limiter that works for any sender type.

Python

import time
import threading
import os

try:
    from telnyx import Telnyx
except ImportError:
    Telnyx = None

class RateLimiter:
    """Token bucket rate limiter for SMS sending."""

    def __init__(self, rate: float, burst: int | None = None):
        """
        Args:
            rate: Messages per second (e.g., 0.1 for long code, 20 for toll-free).
            burst: Max burst size. Defaults to rate (no bursting).
        """
        self.rate = rate
        self.burst = burst or max(1, int(rate))
        self.tokens = self.burst
        self.last_refill = time.monotonic()
        self.lock = threading.Lock()

    def acquire(self, timeout: float = 30.0) -> bool:
        """Wait until a token is available. Returns False on timeout."""
        deadline = time.monotonic() + timeout
        while True:
            with self.lock:
                self._refill()
                if self.tokens >= 1:
                    self.tokens -= 1
                    return True
            wait_time = min(1.0 / self.rate, deadline - time.monotonic())
            if wait_time <= 0:
                return False
            time.sleep(wait_time)

    def _refill(self):
        now = time.monotonic()
        elapsed = now - self.last_refill
        self.tokens = min(self.burst, self.tokens + elapsed * self.rate)
        self.last_refill = now

# Usage: Toll-Free at 20 MPS
limiter = RateLimiter(rate=20)

if Telnyx:
    client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

recipients = ["+15551234567", "+15559876543"]  # your recipient list

for to_number in recipients:
    if not limiter.acquire(timeout=60):
        print(f"Rate limit timeout sending to {to_number}")
        continue
    if Telnyx:
        response = client.messages.send(
            from_="+15550001111",
            to=to_number,
            text="Hello from Telnyx!",
        )
        print(f"Sent to {to_number}: {response.data.id}")

Node

const Telnyx = require('telnyx');

class RateLimiter {
  /**
   * Token bucket rate limiter.
   * @param {number} rate - Messages per second
   * @param {number} [burst] - Max burst size
   */
  constructor(rate, burst) {
    this.rate = rate;
    this.burst = burst || Math.max(1, Math.floor(rate));
    this.tokens = this.burst;
    this.lastRefill = Date.now();
  }

  async acquire(timeoutMs = 30000) {
    const deadline = Date.now() + timeoutMs;
    while (Date.now() < deadline) {
      this._refill();
      if (this.tokens >= 1) {
        this.tokens -= 1;
        return true;
      }
      const waitMs = Math.min(1000 / this.rate, deadline - Date.now());
      if (waitMs <= 0) break;
      await new Promise(r => setTimeout(r, waitMs));
    }
    return false;
  }

  _refill() {
    const now = Date.now();
    const elapsed = (now - this.lastRefill) / 1000;
    this.tokens = Math.min(this.burst, this.tokens + elapsed * this.rate);
    this.lastRefill = now;
  }
}

// Usage: Toll-Free at 20 MPS
const limiter = new RateLimiter(20);
const client = new Telnyx(process.env.TELNYX_API_KEY);

const recipients = ['+15551234567', '+15559876543'];

(async () => {
  for (const to of recipients) {
    if (!(await limiter.acquire(60000))) {
      console.log(`Rate limit timeout sending to ${to}`);
      continue;
    }
    try {
      const response = await client.messages.send({
        from: '+15550001111',
        to,
        text: 'Hello from Telnyx!',
      });
      console.log(`Sent to ${to}: ${response.data.id}`);
    } catch (err) {
      console.error(`Error sending to ${to}:`, err.message);
    }
  }
})();

Ruby

require "telnyx"

class RateLimiter
  def initialize(rate, burst: nil)
    @rate = rate.to_f
    @burst = burst || [@rate.ceil, 1].max
    @tokens = @burst.to_f
    @last_refill = Process.clock_gettime(Process::CLOCK_MONOTONIC)
    @mutex = Mutex.new
  end

  def acquire(timeout: 30)
    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
    loop do
      @mutex.synchronize do
        refill
        if @tokens >= 1
          @tokens -= 1
          return true
        end
      end
      wait = [1.0 / @rate, deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)].min
      return false if wait <= 0
      sleep(wait)
    end
  end

  private

  def refill
    now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
    elapsed = now - @last_refill
    @tokens = [@burst, @tokens + elapsed * @rate].min
    @last_refill = now
  end
end

# Usage: Toll-Free at 20 MPS
limiter = RateLimiter.new(20)
Telnyx.api_key = ENV["TELNYX_API_KEY"]

recipients = ["+15551234567", "+15559876543"]

recipients.each do |to|
  unless limiter.acquire(timeout: 60)
    puts "Rate limit timeout sending to #{to}"
    next
  end

  begin
    response = Telnyx::Message.create(
      from: "+15550001111",
      to: to,
      text: "Hello from Telnyx!"
    )
    puts "Sent to #{to}: #{response.id}"
  rescue => e
    puts "Error sending to #{to}: #{e.message}"
  end
end

package main

import (
  "context"
  "fmt"
  "os"
  "sync"
  "time"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

// RateLimiter implements a token bucket algorithm.
type RateLimiter struct {
  rate       float64
  burst      float64
  tokens     float64
  lastRefill time.Time
  mu         sync.Mutex
}

// NewRateLimiter creates a rate limiter.
// rate is messages per second (e.g., 20 for toll-free).
func NewRateLimiter(rate float64) *RateLimiter {
  burst := rate
  if burst < 1 {
    burst = 1
  }
  return &RateLimiter{
    rate:       rate,
    burst:      burst,
    tokens:     burst,
    lastRefill: time.Now(),
  }
}

// Acquire blocks until a token is available or the timeout expires.
func (r *RateLimiter) Acquire(timeout time.Duration) bool {
  deadline := time.Now().Add(timeout)
  for time.Now().Before(deadline) {
    r.mu.Lock()
    r.refill()
    if r.tokens >= 1 {
      r.tokens--
      r.mu.Unlock()
      return true
    }
    r.mu.Unlock()
    wait := time.Duration(float64(time.Second) / r.rate)
    remaining := time.Until(deadline)
    if remaining < wait {
      wait = remaining
    }
    if wait <= 0 {
      return false
    }
    time.Sleep(wait)
  }
  return false
}

func (r *RateLimiter) refill() {
  now := time.Now()
  elapsed := now.Sub(r.lastRefill).Seconds()
  r.tokens = min(r.burst, r.tokens+elapsed*r.rate)
  r.lastRefill = now
}

func min(a, b float64) float64 {
  if a < b {
    return a
  }
  return b
}

func main() {
  limiter := NewRateLimiter(20) // Toll-Free at 20 MPS

  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )

  recipients := []string{"+15551234567", "+15559876543"}

  for _, to := range recipients {
    if !limiter.Acquire(60 * time.Second) {
      fmt.Printf("Rate limit timeout sending to %s\n", to)
      continue
    }
    resp, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
      From: "+15550001111",
      To:   to,
      Text: "Hello from Telnyx!",
    })
    if err != nil {
      fmt.Printf("Error sending to %s: %v\n", to, err)
      continue
    }
    fmt.Printf("Sent to %s: %s\n", to, resp.Data.ID)
  }
}

Java

import java.util.List;
import java.util.concurrent.locks.ReentrantLock;

public class RateLimitedSender {

    static class RateLimiter {
        private final double rate;
        private final double burst;
        private double tokens;
        private long lastRefillNanos;
        private final ReentrantLock lock = new ReentrantLock();

        public RateLimiter(double rate) {
            this.rate = rate;
            this.burst = Math.max(1, rate);
            this.tokens = this.burst;
            this.lastRefillNanos = System.nanoTime();
        }

        public boolean acquire(long timeoutMs) throws InterruptedException {
            long deadlineNanos = System.nanoTime() + timeoutMs * 1_000_000L;
            while (System.nanoTime() < deadlineNanos) {
                lock.lock();
                try {
                    refill();
                    if (tokens >= 1) {
                        tokens--;
                        return true;
                    }
                } finally {
                    lock.unlock();
                }
                long waitMs = Math.min(
                    (long) (1000.0 / rate),
                    (deadlineNanos - System.nanoTime()) / 1_000_000L
                );
                if (waitMs <= 0) return false;
                Thread.sleep(waitMs);
            }
            return false;
        }

        private void refill() {
            long now = System.nanoTime();
            double elapsed = (now - lastRefillNanos) / 1e9;
            tokens = Math.min(burst, tokens + elapsed * rate);
            lastRefillNanos = now;
        }
    }

    public static void main(String[] args) throws Exception {
        RateLimiter limiter = new RateLimiter(20); // Toll-Free at 20 MPS

        // Use with Telnyx Java SDK:
        // TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        List recipients = List.of("+15551234567", "+15559876543");

        for (String to : recipients) {
            if (!limiter.acquire(60_000)) {
                System.out.println("Rate limit timeout: " + to);
                continue;
            }
            // MessageSendParams params = MessageSendParams.builder()
            //     .from("+15550001111")
            //     .to(to)
            //     .text("Hello from Telnyx!")
            //     .build();
            // var response = client.messages().send(params);
            System.out.println("Sent to " + to);
        }
    }
}

.NET

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

public class RateLimiter
{
    private readonly double _rate;
    private readonly double _burst;
    private double _tokens;
    private DateTime _lastRefill;
    private readonly object _lock = new();

    public RateLimiter(double rate, double? burst = null)
    {
        _rate = rate;
        _burst = burst ?? Math.Max(1, rate);
        _tokens = _burst;
        _lastRefill = DateTime.UtcNow;
    }

    public async Task AcquireAsync(TimeSpan timeout)
    {
        var deadline = DateTime.UtcNow + timeout;
        while (DateTime.UtcNow < deadline)
        {
            lock (_lock)
            {
                Refill();
                if (_tokens >= 1)
                {
                    _tokens--;
                    return true;
                }
            }
            var waitMs = Math.Min(1000.0 / _rate, (deadline - DateTime.UtcNow).TotalMilliseconds);
            if (waitMs <= 0) return false;
            await Task.Delay(TimeSpan.FromMilliseconds(waitMs));
        }
        return false;
    }

    private void Refill()
    {
        var now = DateTime.UtcNow;
        var elapsed = (now - _lastRefill).TotalSeconds;
        _tokens = Math.Min(_burst, _tokens + elapsed * _rate);
        _lastRefill = now;
    }
}

// Usage: Toll-Free at 20 MPS
// var limiter = new RateLimiter(20);
// TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));
// var service = new MessageService();
//
// foreach (var to in recipients)
// {
//     if (!await limiter.AcquireAsync(TimeSpan.FromSeconds(60)))
//     {
//         Console.WriteLine($"Timeout: {to}");
//         continue;
//     }
//     var response = await service.SendAsync(new MessageSendOptions
//     {
//         From = "+15550001111", To = to, Text = "Hello from Telnyx!"
//     });
//     Console.WriteLine($"Sent to {to}: {response.Data.Id}");
// }

PHP

<?php
require_once 'vendor/autoload.php';

class RateLimiter
{
    private float $rate;
    private float $burst;
    private float $tokens;
    private float $lastRefill;

    public function __construct(float $rate, ?float $burst = null)
    {
        $this->rate = $rate;
        $this->burst = $burst ?? max(1, $rate);
        $this->tokens = $this->burst;
        $this->lastRefill = hrtime(true) / 1e9;
    }

    public function acquire(float $timeout = 30.0): bool
    {
        $deadline = hrtime(true) / 1e9 + $timeout;
        while (hrtime(true) / 1e9 < $deadline) {
            $this->refill();
            if ($this->tokens >= 1) {
                $this->tokens--;
                return true;
            }
            $wait = min(1.0 / $this->rate, $deadline - hrtime(true) / 1e9);
            if ($wait <= 0) {
                return false;
            }
            usleep((int) ($wait * 1e6));
        }
        return false;
    }

    private function refill(): void
    {
        $now = hrtime(true) / 1e9;
        $elapsed = $now - $this->lastRefill;
        $this->tokens = min($this->burst, $this->tokens + $elapsed * $this->rate);
        $this->lastRefill = $now;
    }
}

// Usage: Toll-Free at 20 MPS
$limiter = new RateLimiter(20);
\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$recipients = ['+15551234567', '+15559876543'];

foreach ($recipients as $to) {
    if (!$limiter->acquire(60)) {
        echo "Rate limit timeout: {$to}\n";
        continue;
    }

    try {
        $response = \Telnyx\Message::Create([
            'from' => '+15550001111',
            'to' => $to,
            'text' => 'Hello from Telnyx!',
        ]);
        echo "Sent to {$to}: {$response->id}\n";
    } catch (\Exception $e) {
        echo "Error: {$e->getMessage()}\n";
    }
}

Adapting for your sender type

Change the rate parameter to match your sender type:

Sender Type	Rate Parameter	Example
Long Code	`0.1`	`RateLimiter(0.1)`
Toll-Free	`20`	`RateLimiter(20)`
Short Code	`1000`	`RateLimiter(1000)`
Alphanumeric	`0.1`	`RateLimiter(0.1)`

For Number Pool configurations, the effective rate is the per-number limit multiplied by the number of numbers in the pool. For example, 10 Long Codes at 0.1 MPS each gives an effective 1 MPS pool rate.

Handling Rate Limit Errors

When your sending rate exceeds limits, the API returns specific error codes. Handle them gracefully with retry logic:

Python

import time
import os

from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

def send_with_retry(to: str, from_: str, text: str, max_retries: int = 3):
    """Send a message with exponential backoff on rate limit errors."""
    for attempt in range(max_retries + 1):
        try:
            response = client.messages.send(from_=from_, to=to, text=text)
            return response
        except Exception as e:
            error_code = getattr(e, "code", None)
            if error_code == "40318":  # Queue full
                wait = min(2**attempt, 30)
                print(f"Queue full, retrying in {wait}s (attempt {attempt + 1})")
                time.sleep(wait)
            else:
                raise
    raise Exception(f"Failed to send to {to} after {max_retries} retries")

Node

const Telnyx = require('telnyx');
const client = new Telnyx(process.env.TELNYX_API_KEY);

async function sendWithRetry(to, from, text, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await client.messages.send({ from, to, text });
    } catch (err) {
      if (err.rawType === '40318') {
        const wait = Math.min(2 ** attempt * 1000, 30000);
        console.log(`Queue full, retrying in ${wait}ms (attempt ${attempt + 1})`);
        await new Promise(r => setTimeout(r, wait));
      } else {
        throw err;
      }
    }
  }
  throw new Error(`Failed to send to ${to} after ${maxRetries} retries`);
}

HTTP API request rate limits (separate from message throughput). Carrier-specific throughput for 10DLC campaigns. Distribute messages across multiple numbers for higher throughput. Monitor delivery status and diagnose throughput issues.

Error Codes

Source: https://developers.telnyx.com/docs/messaging/messages/error-codes.md

Complete reference for errors returned by the Telnyx Messaging API. Errors fall into three categories: API request errors (returned immediately), delivery errors (reported via webhooks), and configuration errors (number/profile issues). For general Telnyx API errors (authentication, rate limiting, etc.), see the API Error Codes reference.

Delivery errors (40xxx)

These errors occur after the message is accepted by the API but fails during delivery. They appear in message detail records and message.finalized webhooks.

Carrier rejections

Code	Error	Cause	Action
`40001`	Not routable	Destination is a landline or non-routable number	Verify the recipient can receive SMS/MMS
`40002`	Blocked as spam (temporary)	Carrier spam filter triggered	Reduce sending rate; review message content for spam patterns
`40003`	Blocked as spam (permanent)	Sending number permanently blocked by carrier	Use a different sending number; contact support for appeal
`40004`	Rejected by destination	Recipient carrier rejecting for unknown reason	Retry after delay; contact support if persistent
`40005`	Message expired	Message TTL expired before delivery	Increase validity period or check carrier delays
`40006`	Recipient unavailable	Recipient’s carrier server is down	Retry with exponential backoff
`40008`	Undeliverable	Carrier did not accept the message	Check number validity; try alternate route
`40009`	Invalid message body	Message content rejected	Check for invalid characters or encoding issues; see Message Encoding
`40011`	Rate limit exceeded (upstream)	Exceeded carrier throughput limit	Reduce sending rate; see Rate Limiting
`40012`	Invalid destination number	Carrier rejected the destination number	Verify E.164 format and number validity
`40013`	Invalid source number	Carrier rejected the sending number	Check that your number is active and messaging-enabled
`40014`	Expired in queue	Message sat in queue past validity period	Check for throughput bottlenecks; increase sending capacity
`40015`	Internal spam filter	Telnyx internal spam filter triggered	Review message content; contact support if false positive

10DLC-specific errors

Code	Error	Cause	Action
`40010`	Not 10DLC registered	Sending number lacks 10DLC campaign registration	Register for 10DLC
`40016`	T-Mobile sending limit	Exceeded T-Mobile throughput for this campaign	Reduce rate or improve brand vetting score for higher limits
`40017`	AT&T spam rejection	AT&T flagged message as spam	Review content; avoid URL shorteners and spam-like patterns
`40018`	AT&T sending limit	Exceeded AT&T throughput for this campaign	Reduce rate or improve brand vetting score
`40019`	AT&T invalid tag data	Incorrect 10DLC tagging information	Verify campaign and number assignment; troubleshoot 10DLC
`40020`	Artificial traffic inflation	2FA traffic blocked for 24 hours	Wait 24 hours; review for fraud patterns on your numbers

Toll-free errors

Code	Error	Cause	Action
`40329`	Toll-free not verified	Number hasn’t passed toll-free verification	Complete toll-free verification
`40330`	Toll-free not provisioned	Number not fully provisioned for messaging	Wait for provisioning to complete; contact support

API request errors (403xx)

These errors are returned immediately in the API response when the message request is invalid.

Sender/recipient errors

Code	Error	Cause	Action
`40300`	Blocked (STOP)	Recipient sent STOP — opt-out in effect	Do not retry; wait for recipient to opt back in
`40301`	Unsupported message type	Cannot send between these number types	Check source and destination number capabilities
`40305`	Invalid ‘from’ address	Sending number not associated with messaging profile	Assign the number to your messaging profile
`40306`	Alpha sender not configured	Alphanumeric sender ID not set on profile	Configure alpha sender on your messaging profile
`40307`	Alpha sender mismatch	From address doesn’t match configured alpha sender	Use the exact alpha sender configured on the profile
`40308`	Invalid ‘from’ for MMS	MMS requires US long code or short code	Use an MMS-capable number
`40309`	Invalid destination region	Destination country not in profile whitelist	Add the destination region to your messaging profile
`40310`	Invalid ‘to’ address	Destination number is invalid	Verify E.164 format: `+[country code][number]`
`40319`	Incompatible message type	Source and destination types incompatible	Check number type compatibility
`40320`	Temporarily unusable sender	Sending number in pending/transitional state	Wait for number provisioning to complete
`40321`	No usable numbers in pool	Number pool empty or all numbers unhealthy	Add numbers to pool or check number health
`40325`	Invalid alpha sender ID	Alphanumeric sender ID format is invalid	Use 1–11 alphanumeric characters

Content errors

Code	Error	Cause	Action
`40302`	Message too large	SMS exceeds maximum segment count	Shorten message or send as MMS
`40304`	Invalid content combination	Mixed SMS/MMS content parameters	Use `text` for SMS; `media_urls` (with optional `text`) for MMS
`40316`	No content	Message has no text or media	Include `text` and/or `media_urls`
`40317`	Invalid MMS content	Too many media items or total size > 1 MB	Reduce to ≤10 URLs and ≤1 MB total
`40322`	Blocked content	Message contains prohibited content	Remove flagged content
`40328`	SMS too large (warning)	Message splits into too many parts	Consider sending as MMS instead

Profile/configuration errors

Code	Error	Cause	Action
`40311`	Invalid profile secret	`X-Profile-Secret` header is wrong	Check your messaging profile secret
`40312`	Profile disabled	Messaging profile is disabled	Re-enable in Mission Control
`40313`	Missing profile secret	`X-Profile-Secret` header required but not sent	Include the header in your request
`40314`	Messaging disabled	Messaging disabled on your account	Contact Telnyx support
`40315`	Unhealthy sender	Sending number has poor health metrics	Check number success/spam rates; consider replacing
`40318`	Queue full	Internal message queue at capacity	Back off and retry after a delay
`40323`	Activation failed	Could not enable messaging on number	Contact support
`40331`	Missing whitelist	No whitelisted destinations on profile	Add destination regions to your messaging profile
`40333`	Spend limit reached	Messaging profile cost limit hit	Increase spend limit or wait for reset

Number provisioning errors (401xx)

Code	Error	Cause	Action
`40100`	Not messaging enabled	Number not configured for messaging	Enable messaging in Mission Control
`40150`	Not in voice registry	Toll-free number missing from registry	Contact support
`40151`	Enablement pending elsewhere	Another provider is enabling messaging	Wait for transfer to complete
`40155`	LOA required	Letter of Authorization needed	Submit LOA through support

Handle errors in code

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"

try:
    message = telnyx.Message.create(
        from_="+18005550100",
        to="+18005550101",
        text="Hello!",
        messaging_profile_id="YOUR_PROFILE_ID"
    )
    print(f"Sent: {message.id}")

except telnyx.error.InvalidRequestError as e:
    # API request errors (40xxx)
    error = e.json_body.get("errors", [{}])[0]
    code = error.get("code", "unknown")
    detail = error.get("detail", "No details")

    if code == "40300":
        print(f"Recipient opted out (STOP). Do not retry.")
    elif code == "40333":
        print(f"Spend limit reached. Increase limit or wait for reset.")
    elif code == "40310":
        print(f"Invalid destination number. Check E.164 format.")
    else:
        print(f"Error {code}: {detail}")

except telnyx.error.AuthenticationError:
    print("Invalid API key")

Node

const telnyx = require("telnyx")("YOUR_API_KEY");

try {
  const message = await telnyx.messages.create({
    from: "+18005550100",
    to: "+18005550101",
    text: "Hello!",
    messaging_profile_id: "YOUR_PROFILE_ID",
  });
  console.log(`Sent: ${message.data.id}`);
} catch (err) {
  const error = err.rawType || "unknown";
  const detail = err.message;

  switch (error) {
    case "40300":
      console.log("Recipient opted out (STOP). Do not retry.");
      break;
    case "40333":
      console.log("Spend limit reached.");
      break;
    case "40310":
      console.log("Invalid destination number.");
      break;
    default:
      console.log(`Error ${error}: ${detail}`);
  }
}

Ruby

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

begin
  message = Telnyx::Message.create(
    from: "+18005550100",
    to: "+18005550101",
    text: "Hello!",
    messaging_profile_id: "YOUR_PROFILE_ID"
  )
  puts "Sent: #{message.id}"

rescue Telnyx::InvalidRequestError => e
  error = e.json_body&.dig(:errors, 0) || {}
  code = error[:code] || "unknown"
  detail = error[:detail] || "No details"

  case code
  when "40300"
    puts "Recipient opted out. Do not retry."
  when "40333"
    puts "Spend limit reached."
  else
    puts "Error #{code}: #{detail}"
  end
end

package main

import (
    "context"
    "fmt"
    "strings"

    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient("YOUR_API_KEY")

    _, err := client.Messages.Create(context.Background(), &telnyx.MessageParams{
        From:               "+18005550100",
        To:                 "+18005550101",
        Text:               "Hello!",
        MessagingProfileID: "YOUR_PROFILE_ID",
    })
    if err != nil {
        if strings.Contains(err.Error(), "40300") {
            fmt.Println("Recipient opted out. Do not retry.")
        } else if strings.Contains(err.Error(), "40333") {
            fmt.Println("Spend limit reached.")
        } else {
            fmt.Printf("Error: %v\n", err)
        }
        return
    }
    fmt.Println("Message sent successfully")
}

curl

# Check response for errors
response=$(curl -s -w "\n%{http_code}" -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+18005550100",
    "to": "+18005550101",
    "text": "Hello!"
  }')

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -n -1)

if [ "$http_code" != "200" ]; then
  error_code=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('errors',[{}])[0].get('code','unknown'))")
  echo "Error $error_code (HTTP $http_code)"
  echo "$body" | python3 -m json.tool
fi

Handle delivery errors via webhooks

Delivery errors arrive asynchronously in message.finalized webhooks:

Python

@app.route("/webhooks", methods=["POST"])
def webhooks():
    body = request.json
    event_type = body["data"]["event_type"]

    if event_type == "message.finalized":
        payload = body["data"]["payload"]
        status = payload["to"][0]["status"]

        if status == "delivery_failed" or status == "sending_failed":
            errors = payload.get("errors", [])
            for error in errors:
                code = error.get("code", "unknown")
                detail = error.get("detail", "")
                print(f"Delivery failed [{code}]: {detail}")

                # Decide whether to retry
                if code in ("40006", "40008"):
                    print("Temporary error — retry with exponential backoff")
                elif code in ("40003", "40300", "40001", "40010", "40314", "40322"):
                    print("Permanent error — do not retry")
                elif code in ("40002", "40011", "40016", "40017", "40018"):
                    print("Intervention required — review content/rate, then retry")
                else:
                    print("Review error and decide")

    return "", 200

Retriable vs permanent errors

Most delivery errors require you to change something before retrying — blindly retrying the same message with the same configuration will not resolve the issue and may result in further blocking.

Category	Codes	Action
Auto-retriable (genuinely temporary)	`40006`, `40008`	Carrier-side issue — retry with exponential backoff (1s, 2s, 4s, 8s…). `40006`: recipient carrier is down. `40008`: general undeliverable, may resolve on retry.
Retriable after intervention (fix first)	`40002`, `40005`, `40011`, `40014`, `40016`, `40017`, `40018`, `40318`	These errors indicate a problem with your sending rate, content, or throughput. Reduce sending rate, review message content for spam patterns, or resolve queue pressure before retrying. Automatic retry without changes will likely fail again.
Temporary hold	`40020`, `40320`	`40020`: 2FA traffic blocked for 24 hours — wait, do not retry. `40320`: sender in transitional state — wait for provisioning to complete.
Permanent (do not retry)	`40001`, `40003`, `40010`, `40300`, `40314`, `40322`	Fix root cause before attempting again. These will not resolve on their own.
Action required (config/compliance)	`40010`, `40015`, `40019`, `40315`, `40329`, `40333`	Resolve the underlying configuration or compliance issue, then send again.

Understand and handle API and carrier rate limits. Query delivery status and error details for sent messages. Diagnose 10DLC registration and delivery issues. Configure and manage messaging profile spend limits.

Smart Encoding

Source: https://developers.telnyx.com/docs/messaging/messages/smart-encoding.md

Smart encoding automatically replaces Unicode characters with visually similar GSM-7 characters. This keeps your messages in the more efficient GSM-7 encoding, reducing segment counts and costs. Smart encoding applies to SMS only. MMS and RCS messages use UTF-8 encoding by default and are not affected.

Why use smart encoding

SMS messages using GSM-7 encoding fit 160 characters per segment. When a message contains even one Unicode character outside GSM-7, the entire message switches to UTF-16 encoding, which only fits 70 characters per segment. A single smart quote (") or em dash (—) can more than double your messaging costs. Example:

Message	Encoding	Segments	Cost impact
`Hello, how are you?` (150 chars)	GSM-7	1	Base cost
`Hello, how are you?` (150 chars with `"smart quotes"`)	UTF-16	3	3× cost
`Hello, how are you?` (same, smart encoding ON)	GSM-7	1	Base cost

Smart encoding is especially valuable when your message text originates from word processors, CMS platforms, or mobile keyboards that silently insert Unicode characters like curly quotes, em dashes, or non-breaking spaces.

How it works

When smart encoding is enabled:

Your message text is scanned for Unicode characters that have GSM-7 equivalents.
Matching characters are automatically replaced (e.g., " → ", — → -, … → ...).
The final encoding (GSM-7 or UTF-16) is determined after all substitutions.
The segment count is recalculated based on the transformed text.
The API response includes metadata about the transformation.

Webhooks return the original text. The text field in delivery webhooks contains your original message, not the smart-encoded version. This ensures your application’s message tracking stays consistent.

Enable smart encoding

You can enable smart encoding at two levels: on a messaging profile (applies to all messages) or on a per-request basis.

On a messaging profile

Enable smart encoding as a default for all messages sent through a profile.

curl

curl -X PATCH https://api.telnyx.com/v2/messaging_profiles/{profile_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "smart_encoding": true
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messagingProfiles.update(
  'your_messaging_profile_id',
  { smart_encoding: true }
);

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messaging_profiles.update(
    "your_messaging_profile_id",
    smart_encoding=True,
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messaging_profiles.update(
  "your_messaging_profile_id",
  smart_encoding: true
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.MessagingProfiles.Update(
    context.TODO(),
    "your_messaging_profile_id",
    telnyx.MessagingProfileUpdateParams{
      SmartEncoding: telnyx.Bool(true),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messagingprofiles.MessagingProfileUpdateParams;
import com.telnyx.sdk.models.messagingprofiles.MessagingProfileUpdateResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessagingProfileUpdateParams params = MessagingProfileUpdateParams.builder()
            .smartEncoding(true)
            .build();

        MessagingProfileUpdateResponse response = client
            .messagingProfiles()
            .update("your_messaging_profile_id", params);

        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessagingProfileService();
var response = await service.UpdateAsync(
    "your_messaging_profile_id",
    new MessagingProfileUpdateOptions
    {
        SmartEncoding = true
    }
);

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\MessagingProfile::Update(
    'your_messaging_profile_id',
    ['smart_encoding' => true]
);

print_r($response);

Navigate to Messaging > Messaging Profiles in the portal. Click on the messaging profile you want to update. Toggle Smart Encoding to enabled. Click Save to apply the change.

Per-request control

Override the profile setting on individual messages using the encoding parameter:

Value	Behavior
`auto`	Follow the profile’s `smart_encoding` setting (default).
`gsm7`	Force GSM-7 encoding. Smart encoding is applied. Returns `400` if the message contains characters that cannot be converted to GSM-7 (e.g., emoji).
`ucs2`	Force UCS-2 encoding. Skips smart encoding entirely.

The request-level encoding parameter takes precedence over the messaging profile’s smart_encoding setting.

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!",
    "encoding": "auto"
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!',
  encoding: 'auto',
});

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.send(
    from_="+15551234567",
    to="+15559876543",
    text="Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!",
    encoding="auto",
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: "+15559876543",
  text: "Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!",
  encoding: "auto"
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From:     "+15551234567",
    To:       "+15559876543",
    Text:     "Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!",
    Encoding: telnyx.String("auto"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendParams params = MessageSendParams.builder()
            .from("+15551234567")
            .to("+15559876543")
            .text("Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!")
            .encoding("auto")
            .build();

        MessageSendResponse response = client.messages().send(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!",
    Encoding = "auto"
});

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => "Don\u{2019}t miss our \u{201c}flash sale\u{201d} \u{2014} 50% off!",
    'encoding' => 'auto'
]);

print_r($response);

Response metadata

When smart encoding is applied, the API response includes detailed metadata:

{
  "data": {
    "id": "8a0c35c0-5eed-4c0e-b1f0-abc123456789",
    "type": "SMS",
    "encoding": "GSM-7",
    "parts": 1,
    "smart_encoding": {
      "smart_encoding_applied": true,
      "final_encoding": "gsm7",
      "segment_count": 1,
      "character_count": 155,
      "replaced_character_count": 3,
      "length_change": 2
    }
  }
}

Field	Description
`smart_encoding_applied`	Whether any characters were replaced.
`final_encoding`	The encoding used after transformation (`gsm7` or `ucs2`).
`segment_count`	Number of segments after smart encoding.
`character_count`	Message length after transformation.
`replaced_character_count`	Number of unique characters that were substituted.
`length_change`	Difference in length (positive means message grew, e.g., `…` → `...`).

The parts field in the top-level response reflects the segment count after smart encoding, so you always see the actual billing impact.

Checking the response

curl

# Send and inspect the smart_encoding metadata
curl -s -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!"
  }' | jq '.data.smart_encoding'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!',
});

if (response.data.smart_encoding?.smart_encoding_applied) {
  console.log('Smart encoding applied!');
  console.log(`Encoding: ${response.data.smart_encoding.final_encoding}`);
  console.log(`Segments: ${response.data.smart_encoding.segment_count}`);
  console.log(`Characters replaced: ${response.data.smart_encoding.replaced_character_count}`);
}

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.send(
    from_="+15551234567",
    to="+15559876543",
    text="Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!",
)

smart = response.data.smart_encoding
if smart and smart.smart_encoding_applied:
    print(f"Encoding: {smart.final_encoding}")
    print(f"Segments: {smart.segment_count}")
    print(f"Characters replaced: {smart.replaced_character_count}")

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: "+15559876543",
  text: "Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!"
)

smart = response.data.smart_encoding
if smart&.smart_encoding_applied
  puts "Encoding: #{smart.final_encoding}"
  puts "Segments: #{smart.segment_count}"
  puts "Characters replaced: #{smart.replaced_character_count}"
end

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From: "+15551234567",
    To:   "+15559876543",
    Text: "Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!",
  })
  if err != nil {
    panic(err.Error())
  }
  if response.Data.SmartEncoding != nil && response.Data.SmartEncoding.SmartEncodingApplied {
    fmt.Printf("Encoding: %s\n", response.Data.SmartEncoding.FinalEncoding)
    fmt.Printf("Segments: %d\n", response.Data.SmartEncoding.SegmentCount)
    fmt.Printf("Replaced: %d\n", response.Data.SmartEncoding.ReplacedCharacterCount)
  }
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendParams params = MessageSendParams.builder()
            .from("+15551234567")
            .to("+15559876543")
            .text("Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!")
            .build();

        MessageSendResponse response = client.messages().send(params);

        var smart = response.data().smartEncoding();
        if (smart != null && smart.smartEncodingApplied()) {
            System.out.println("Encoding: " + smart.finalEncoding());
            System.out.println("Segments: " + smart.segmentCount());
            System.out.println("Replaced: " + smart.replacedCharacterCount());
        }
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Don\u2019t miss our \u201cflash sale\u201d \u2014 50% off!"
});

var smart = response.Data.SmartEncoding;
if (smart?.SmartEncodingApplied == true)
{
    Console.WriteLine($"Encoding: {smart.FinalEncoding}");
    Console.WriteLine($"Segments: {smart.SegmentCount}");
    Console.WriteLine($"Replaced: {smart.ReplacedCharacterCount}");
}

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => "Don\u{2019}t miss our \u{201c}flash sale\u{201d} \u{2014} 50% off!"
]);

$smart = $response->smart_encoding;
if ($smart && $smart->smart_encoding_applied) {
    echo "Encoding: " . $smart->final_encoding . "\n";
    echo "Segments: " . $smart->segment_count . "\n";
    echo "Replaced: " . $smart->replaced_character_count . "\n";
}

Precedence rules

Smart encoding behavior is determined by a combination of your messaging profile setting and the per-request encoding parameter:

Profile `smart_encoding`	Request `encoding`	Behavior
`true`	(not set)	Smart encoding applied
`false`	(not set)	Smart encoding not applied
`true`	`auto`	Smart encoding applied
`false`	`auto`	Smart encoding not applied
`true` or `false`	`gsm7`	Smart encoding applied, must result in GSM-7 or returns `400`
`true` or `false`	`ucs2`	Smart encoding skipped, forced UCS-2

The request-level encoding parameter always takes precedence over the messaging profile setting.

Character substitutions

Smart encoding replaces 200+ Unicode characters with GSM-7 equivalents. The tables below show all supported substitutions grouped by category.

Unicode	Glyph	Description	Replacement
U+00AB	«	Left-pointing double angle quotation mark	”
U+00BB	»	Right-pointing double angle quotation mark	”
U+201C	”	Left double quotation mark	”
U+201D	”	Right double quotation mark	”
U+02BA	ʺ	Modifier letter double prime	”
U+02EE	ˮ	Modifier letter double apostrophe	”
U+201F	‟	Double high-reversed-9 quotation mark	”
U+275D	❝	Heavy double turned comma quotation mark ornament	”
U+275E	❞	Heavy double comma quotation mark ornament	”
U+301D	〝	Reversed double prime quotation mark	”
U+301E	〞	Double prime quotation mark	”
U+FF02	＂	Fullwidth quotation mark	”
U+201E	„	Double low quotation mark	”

Unicode	Glyph	Description	Replacement
U+2018	’	Left single quotation mark	’
U+2019	’	Right single quotation mark	’
U+02BB	ʻ	Modifier letter turned comma	’
U+02C8	ˈ	Modifier letter vertical line	’
U+02BC	ʼ	Modifier letter apostrophe	’
U+02BD	ʽ	Modifier letter reversed comma	’
U+02B9	ʹ	Modifier letter prime	’
U+201B	‛	Single high-reversed-9 quotation mark	’
U+FF07	＇	Fullwidth apostrophe	’
U+00B4	´	Acute accent	’
U+02CA	ˊ	Modifier letter acute accent	’
U+0060	`	Grave accent	’
U+02CB	ˋ	Modifier letter grave accent	’
U+275B	❛	Heavy single turned comma quotation mark ornament	’
U+275C	❜	Heavy single comma quotation mark ornament	’
U+0313	̓	Combining comma above	’
U+0314	̔	Combining reversed comma above	’
U+FE10	︐	Presentation form for vertical comma	’
U+FE11	︑	Presentation form for vertical ideographic comma	’

Unicode	Glyph	Description	Replacement
U+2014	—	Em dash	-
U+2013	–	En dash	-
U+23BC	⎼	Horizontal scan line-7	-
U+23BD	⎽	Horizontal scan line-9	-
U+2015	―	Horizontal bar	-
U+FE63	﹣	Small hyphen-minus	-
U+FF0D	－	Fullwidth hyphen-minus	-
U+2010	‐	Hyphen	-
U+2022	•	Bullet	-
U+2043	⁃	Hyphen bullet	-

Unicode	Glyph	Description	Replacement
U+00F7	÷	Division sign	/
U+00BC	¼	Vulgar fraction one quarter	1/4
U+00BD	½	Vulgar fraction one half	1/2
U+00BE	¾	Vulgar fraction three quarters	3/4
U+29F8	⧸	Big solidus	/
U+0337	̷	Combining short solidus overlay	/
U+0338	̸	Combining long solidus overlay	/
U+2044	⁄	Fraction slash	/
U+2215	∕	Division slash	/
U+FF0F	／	Fullwidth solidus	/

Unicode	Glyph	Description	Replacement
U+29F9	⧹	Big reverse solidus	\
U+29F5	⧵	Reverse solidus operator	\
U+20E5		Combining reverse solidus overlay	\
U+FE68	﹨	Small reverse solidus	\
U+FF3C	＼	Fullwidth reverse solidus	\

Unicode	Glyph	Description	Replacement
U+0332	̲	Combining low line	_
U+FF3F	＿	Fullwidth low line	_
U+2017	‗	Double low line	_
U+20D2	⃒	Combining long vertical line overlay	\|
U+20D3	⃓	Combining short vertical line overlay	\|
U+2223	∣	Divides	\|
U+FF5C	｜	Fullwidth vertical line	\|
U+23B8	⎸	Left vertical box line	\|
U+23B9	⎹	Right vertical box line	\|
U+23D0	⏐	Vertical line extension	\|
U+239C	⎜	Left parenthesis extension	\|
U+239F	⎟	Right parenthesis extension	\|

Unicode	Glyph	Description	Replacement
U+FE6B	﹫	Small commercial at sign	@
U+FF20	＠	Fullwidth commercial at sign	@
U+FE69	﹩	Small dollar sign	$
U+FF04	＄	Fullwidth dollar sign	$
U+01C3	ǃ	Latin letter retroflex click	!
U+FE15	︕	Presentation form for vertical exclamation mark	!
U+FE57	﹗	Small exclamation mark	!
U+FF01	！	Fullwidth exclamation mark	!
U+203C	‼	Double exclamation mark	!!
U+FE5F	﹟	Small number sign	#
U+FF03	＃	Fullwidth number sign	#
U+FE6A	﹪	Small percent sign	%
U+FF05	％	Fullwidth percent sign	%
U+FE60	﹠	Small ampersand	&
U+FF06	＆	Fullwidth ampersand	&
U+2026	…	Horizontal ellipsis	…

Unicode	Glyph	Description	Replacement
U+201A	‚	Single low-9 quotation mark	,
U+0326	̦	Combining comma below	,
U+FE50	﹐	Small comma	,
U+3001	、	Ideographic comma	,
U+FE51	﹑	Small ideographic comma	,
U+FF0C	，	Fullwidth comma	,
U+FF64	､	Halfwidth ideographic comma	,

Unicode	Glyph	Description	Replacement
U+2768	❨	Medium left parenthesis ornament	(
U+276A	❪	Medium flattened left parenthesis ornament	(
U+FE59	﹙	Small left parenthesis	(
U+FF08	（	Fullwidth left parenthesis	(
U+27EE	⟮	Mathematical left flattened parenthesis	(
U+2985	⦅	Left white parenthesis	(
U+2769	❩	Medium right parenthesis ornament	)
U+276B	❫	Medium flattened right parenthesis ornament	)
U+FE5A	﹚	Small right parenthesis	)
U+FF09	）	Fullwidth right parenthesis	)
U+27EF	⟯	Mathematical right flattened parenthesis	)
U+2986	⦆	Right white parenthesis	)
U+2774	❴	Medium left curly bracket ornament	{
U+FE5B	﹛	Small left curly bracket	{
U+FF5B	｛	Fullwidth left curly bracket	{
U+2775	❵	Medium right curly bracket ornament	}
U+FE5C	﹜	Small right curly bracket	}
U+FF5D	｝	Fullwidth right curly bracket	}
U+FF3B	［	Fullwidth left square bracket	[
U+FF3D	］	Fullwidth right square bracket	]

Unicode	Glyph	Description	Replacement
U+204E	⁎	Low asterisk	*
U+2217	∗	Asterisk operator	*
U+229B	⊛	Circled asterisk operator	*
U+2722	✢	Four teardrop-spoked asterisk	*
U+2723	✣	Four balloon-spoked asterisk	*
U+2724	✤	Heavy four balloon-spoked asterisk	*
U+2725	✥	Four club-spoked asterisk	*
U+2731	✱	Heavy asterisk	*
U+2732	✲	Open center asterisk	*
U+2733	✳	Eight spoked asterisk	*
U+273A	✺	Sixteen pointed asterisk	*
U+273B	✻	Teardrop-spoked asterisk	*
U+273C	✼	Open center teardrop-spoked asterisk	*
U+273D	✽	Heavy teardrop-spoked asterisk	*
U+2743	❃	Heavy teardrop-spoked pinwheel asterisk	*
U+2749	❉	Balloon-spoked asterisk	*
U+274A	❊	Eight teardrop-spoked propeller asterisk	*
U+274B	❋	Heavy eight teardrop-spoked propeller asterisk	*
U+29C6	⧆	Squared asterisk	*
U+FE61	﹡	Small asterisk	*
U+FF0A	＊	Fullwidth asterisk	*

Unicode	Glyph	Description	Replacement
U+02D6	˖	Modifier letter plus sign	+
U+FE62	﹢	Small plus sign	+
U+FF0B	＋	Fullwidth plus sign	+
U+FE64	﹤	Small less-than sign	`<`
U+FF1C	＜	Fullwidth less-than sign	`<`
U+0347	͇	Combining equals sign below	=
U+A78A	꞊	Modifier letter short equals sign	=
U+FE66	﹦	Small equals sign	=
U+FF1D	＝	Fullwidth equals sign	=
U+FE65	﹥	Small greater-than sign	`>`
U+FF1E	＞	Fullwidth greater-than sign	`>`
U+2039	‹	Single left-pointing angle quotation mark	`<`
U+203A	›	Single right-pointing angle quotation mark	`>`
U+3002	。	Ideographic full stop	.
U+FE52	﹒	Small full stop	.
U+FF0E	．	Fullwidth full stop	.
U+FF61	｡	Halfwidth ideographic full stop	.
U+02D0	ː	Modifier letter triangular colon	:
U+02F8	˸	Modifier letter raised colon	:
U+2982	⦂	Z notation type colon	:
U+A789	꞉	Modifier letter colon	:
U+FE13	︓	Presentation form for vertical colon	:
U+FF1A	：	Fullwidth colon	:
U+204F	⁏	Reversed semicolon	;
U+FE14	︔	Presentation form for vertical semicolon	;
U+FE54	﹔	Small semicolon	;
U+FF1B	；	Fullwidth semicolon	;
U+FE16	︖	Presentation form for vertical question mark	?
U+FE56	﹖	Small question mark	?
U+FF1F	？	Fullwidth question mark	?

Unicode	Glyph	Description	Replacement
U+FF10	０	Fullwidth digit zero	0
U+FF11	１	Fullwidth digit one	1
U+FF12	２	Fullwidth digit two	2
U+FF13	３	Fullwidth digit three	3
U+FF14	４	Fullwidth digit four	4
U+FF15	５	Fullwidth digit five	5
U+FF16	６	Fullwidth digit six	6
U+FF17	７	Fullwidth digit seven	7
U+FF18	８	Fullwidth digit eight	8
U+FF19	９	Fullwidth digit nine	9

Fullwidth uppercase (U+FF21–U+FF3A) → A–Z Fullwidth lowercase (U+FF41–U+FF5A) → a–z Small capital letters:

Unicode	Glyph	Description	Replacement
U+1D00	ᴀ	Latin letter small capital A	A
U+0299	ʙ	Latin letter small capital B	B
U+1D04	ᴄ	Latin letter small capital C	C
U+1D05	ᴅ	Latin letter small capital D	D
U+1D07	ᴇ	Latin letter small capital E	E
U+A730	ꜰ	Latin letter small capital F	F
U+0262	ɢ	Latin letter small capital G	G
U+029C	ʜ	Latin letter small capital H	H
U+026A	ɪ	Latin letter small capital I	I
U+1D0A	ᴊ	Latin letter small capital J	J
U+1D0B	ᴋ	Latin letter small capital K	K
U+029F	ʟ	Latin letter small capital L	L
U+1D0D	ᴍ	Latin letter small capital M	M
U+0274	ɴ	Latin letter small capital N	N
U+1D0F	ᴏ	Latin letter small capital O	O
U+1D18	ᴘ	Latin letter small capital P	P
U+0280	ʀ	Latin letter small capital R	R
U+A731	ꜱ	Latin letter small capital S	S
U+1D1B	ᴛ	Latin letter small capital T	T
U+1D1C	ᴜ	Latin letter small capital U	U
U+1D20	ᴠ	Latin letter small capital V	V
U+1D21	ᴡ	Latin letter small capital W	W
U+028F	ʏ	Latin letter small capital Y	Y
U+1D22	ᴢ	Latin letter small capital Z	Z

Greek capital letters that visually resemble Latin letters are substituted:

Unicode	Glyph	Description	Replacement
U+0391	Α	Greek capital letter Alpha	A
U+0392	Β	Greek capital letter Beta	B
U+0395	Ε	Greek capital letter Epsilon	E
U+0397	Η	Greek capital letter Eta	H
U+0399	Ι	Greek capital letter Iota	I
U+039A	Κ	Greek capital letter Kappa	K
U+039C	Μ	Greek capital letter Mu	M
U+039D	Ν	Greek capital letter Nu	N
U+039F	Ο	Greek capital letter Omicron	O
U+03A1	Ρ	Greek capital letter Rho	P
U+03A4	Τ	Greek capital letter Tau	T
U+03A7	Χ	Greek capital letter Chi	X
U+03A5	Υ	Greek capital letter Upsilon	Y
U+0396	Ζ	Greek capital letter Zeta	Z

Unicode	Glyph	Description	Replacement
U+02C6	ˆ	Modifier letter circumflex accent	^
U+0302	̂	Combining circumflex accent	^
U+FF3E	＾	Fullwidth circumflex accent	^
U+1DCD	᷍	Combining double circumflex above	^
U+02DC	˜	Small tilde	~
U+02F7	˷	Modifier letter low tilde	~
U+0303	̃	Combining tilde	~
U+0330	̰	Combining tilde below	~
U+0334	̴	Combining tilde overlay	~
U+223C	∼	Tilde operator	~
U+FF5E	～	Fullwidth tilde	~

These characters are replaced with a standard space or removed:

Unicode	Description	Replacement
U+00A0	No-break space	(space)
U+2000	En quad	(space)
U+2001	Em quad	(space)
U+2002	En space	(space)
U+2003	Em space	(space)
U+2004	Three-per-em space	(space)
U+2005	Four-per-em space	(space)
U+2006	Six-per-em space	(space)
U+2007	Figure space	(space)
U+2008	Punctuation space	(space)
U+2009	Thin space	(space)
U+200A	Hair space	(space)
U+200B	Zero width space	(removed)
U+202F	Narrow no-break space	(space)
U+205F	Medium mathematical space	(space)
U+3000	Ideographic space	(space)
U+FEFF	Zero width no-break space	(removed)
U+2028	Line separator	(removed)
U+2029	Paragraph separator	(removed)
U+2060	Word joiner	(removed)

These control characters are removed or transformed:

Unicode	Description	Replacement
U+0009	Tab	7 spaces
U+0000	Null	(removed)
U+0003	End of text	(removed)
U+0004	End of transmission	(removed)
U+0010	Escape	(removed)
U+0011	Device control one	(removed)
U+0012	Device control two	(removed)
U+0013	Device control three	(removed)
U+0014	Device control four	(removed)
U+0017	End of transmission block	(removed)
U+0019	End of medium	(removed)
U+0080	C1 control codes	(removed)
U+008D	Reverse line feed	(removed)
U+0090	Device control string	(removed)
U+009B	Control sequence introducer	(removed)
U+009F	Application program command	(removed)

Tab characters (U+0009) are converted to 7 spaces, which can significantly increase message length and affect segment count.

Edge cases

Some substitutions increase message length. For example:

Horizontal ellipsis (…) becomes three periods (...) — adds 2 characters
Tab (U+0009) becomes 7 spaces — adds 6 characters
Vulgar fractions like ½ become 1/2 — adds 2 characters

The segment count is calculated after these replacements, so a message near the 160-character limit may become multi-part after transformation. If your message contains both replaceable Unicode characters and non-replaceable ones (like emojis), smart encoding still applies all possible substitutions. However, the non-replaceable characters will keep the message in UTF-16 encoding. This is still beneficial — fewer Unicode characters means a shorter UTF-16 message and potentially fewer segments. The characters ~, ^, |, \, {, }, [, ] are part of the GSM-7 extended set and count as 2 characters each when calculating segment length. Smart encoding accounts for this when determining the final segment count. Zero-width characters (like U+200B zero-width space) are removed entirely. If your message consists entirely of zero-width or control characters that all get removed, the API returns a 400 error — messages cannot be empty after transformation. If you set encoding=gsm7 on a request but the message contains characters that cannot be represented in GSM-7 (e.g., emoji), the API returns a 400 error rather than silently dropping characters.

Limitations

SMS only — MMS and RCS use UTF-8 encoding by default and are not affected by smart encoding.
Not all characters convert — Emojis and non-Latin scripts (e.g., Chinese, Arabic, Cyrillic) have no GSM-7 equivalents and will still trigger UTF-16 encoding.
Visual differences — Substitutions may slightly alter the appearance of your message. Review the character tables above to understand what changes will occur.
Length may increase — Some substitutions produce longer output (e.g., … → ...). Always check the response metadata for the actual segment count.

Learn about GSM-7, UTF-16, and segment calculations. Get started with the Telnyx Messaging API. API reference for updating messaging profile settings. API reference for sending messages with encoding options.

Group Messaging

Source: https://developers.telnyx.com/docs/messaging/messages/group-messaging.md

Send group MMS messages to multiple recipients in a single API call. Group messaging uses the MMS protocol to create multi-party conversations where all participants can see and reply to each other — just like a group text on your phone.

Prerequisites

A Telnyx account
A Messaging Profile with an MMS-enabled phone number
An API key

How group messaging works

Group messaging builds on the MMS protocol to enable multi-party conversations:

You send a message to the /v2/messages/group_mms endpoint with multiple to numbers
Telnyx delivers the message to all recipients as a group MMS conversation
When any recipient replies, all participants (including your Telnyx number) receive the reply
You receive inbound group messages via webhooks with a cc field listing all participants

Group messaging constraints:

Maximum of 8 recipients per conversation (plus the sender)
MMS protocol only — all messages are billed at MMS rates
US and Canada destinations only
Requires a v2 webhook version on your messaging profile for inbound messages
Charged per recipient — standard MMS rates plus carrier passthrough fees apply

Send a group message

Export your API key as an environment variable:

export TELNYX_API_KEY="YOUR_API_KEY"

Send a group MMS to multiple recipients. You can include text, media, or both.

curl

curl -X POST https://api.telnyx.com/v2/messages/group_mms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": ["+15559876543", "+15558765432"],
    "text": "Hey team, check out this photo!",
    "media_urls": ["https://example.com/photo.jpg"]
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.send(
    from_="+15551234567",
    to=["+15559876543", "+15558765432"],
    text="Hey team, check out this photo!",
    media_urls=["https://example.com/photo.jpg"]
)

print(response.data)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: ['+15559876543', '+15558765432'],
  text: 'Hey team, check out this photo!',
  media_urls: ['https://example.com/photo.jpg']
});

console.log(response.data);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: ["+15559876543", "+15558765432"],
  text: "Hey team, check out this photo!",
  media_urls: ["https://example.com/photo.jpg"]
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From:      "+15551234567",
    To:        []string{"+15559876543", "+15558765432"},
    Text:      "Hey team, check out this photo!",
    MediaURLs: []string{"https://example.com/photo.jpg"},
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;
import java.util.List;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendParams params = MessageSendParams.builder()
            .from("+15551234567")
            .to(List.of("+15559876543", "+15558765432"))
            .text("Hey team, check out this photo!")
            .mediaUrls(List.of("https://example.com/photo.jpg"))
            .build();

        MessageSendResponse response = client.messages().send(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = new[] { "+15559876543", "+15558765432" },
    Text = "Hey team, check out this photo!",
    MediaUrls = new[] { "https://example.com/photo.jpg" }
});

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => ['+15559876543', '+15558765432'],
    'text' => 'Hey team, check out this photo!',
    'media_urls' => ['https://example.com/photo.jpg']
]);

print_r($response);

curl

curl -X POST https://api.telnyx.com/v2/messages/group_mms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": ["+15559876543", "+15558765432"],
    "text": "Hey team, lunch at noon?"
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.send(
    from_="+15551234567",
    to=["+15559876543", "+15558765432"],
    text="Hey team, lunch at noon?"
)

print(response.data)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: ['+15559876543', '+15558765432'],
  text: 'Hey team, lunch at noon?'
});

console.log(response.data);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: ["+15559876543", "+15558765432"],
  text: "Hey team, lunch at noon?"
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From: "+15551234567",
    To:   []string{"+15559876543", "+15558765432"},
    Text: "Hey team, lunch at noon?",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;
import java.util.List;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendParams params = MessageSendParams.builder()
            .from("+15551234567")
            .to(List.of("+15559876543", "+15558765432"))
            .text("Hey team, lunch at noon?")
            .build();

        MessageSendResponse response = client.messages().send(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = new[] { "+15559876543", "+15558765432" },
    Text = "Hey team, lunch at noon?"
});

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => ['+15559876543', '+15558765432'],
    'text' => 'Hey team, lunch at noon?'
]);

print_r($response);

Response

A successful response includes per-recipient status:

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "403188fd-58c5-4557-a8de-1700a358d768",
    "type": "MMS",
    "messaging_profile_id": "1e0df9c5-8716-4bcf-8fb2-9f6d9527fd95",
    "from": "+15551234567",
    "to": [
      {
        "phone_number": "+15559876543",
        "status": "queued",
        "carrier": "T-MOBILE USA, INC.",
        "line_type": "Wireless"
      },
      {
        "phone_number": "+15558765432",
        "status": "queued",
        "carrier": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS",
        "line_type": "Wireless"
      }
    ],
    "text": "Hey team, check out this photo!",
    "media": [
      {
        "url": "https://example.com/photo.jpg",
        "content_type": null,
        "sha256": null,
        "size": null
      }
    ],
    "encoding": "GSM-7",
    "parts": 1,
    "cost": {
      "amount": "0.0800",
      "currency": "USD"
    }
  }
}

Save the id to correlate delivery webhooks with your group message.

Receive group messages

When someone replies to the group conversation, you receive a message.received webhook. The cc field lists all other participants in the conversation:

{
  "data": {
    "event_type": "message.received",
    "id": "0d7c4fbe-d075-435f-b71b-694391743967",
    "occurred_at": "2023-08-08T13:03:05.129+00:00",
    "payload": {
      "cc": [
        "+15558765432",
        "+15557654321",
        "+15551234567"
      ],
      "direction": "inbound",
      "encoding": "UCS-2",
      "from": {
        "carrier": "AT&T",
        "line_type": "Wireless",
        "phone_number": "+15559876543"
      },
      "id": "9d12c9d0-5172-429a-8fb9-cc9da297717f",
      "media": [],
      "messaging_profile_id": "1e0df9c5-8716-4bcf-8fb2-9f6d9527fd95",
      "record_type": "message",
      "text": "Sounds good, see you at noon!",
      "to": [
        {
          "carrier": "Telnyx",
          "line_type": "Wireless",
          "phone_number": "+15551234567",
          "status": "webhook_delivered"
        }
      ],
      "type": "MMS"
    },
    "record_type": "event"
  }
}

Key fields for inbound group messages:

Field	Description
`from.phone_number`	The participant who sent the reply
`to`	Your Telnyx number(s) in the conversation
`cc`	All other participants in the group conversation

Webhooks and delivery tracking

Group messages generate individual webhook events and detail records for each recipient:

Per-recipient webhooks: You receive a separate message.finalized event for each recipient with their individual delivery status
group_message_id: A unique identifier returned in the API response, webhooks, and detail records that lets you correlate all individual records back to the original group message
Non-Telnyx recipient status: Handset delivery confirmation is not available for non-Telnyx recipients — their status will show as unknown

{
  "data": {
    "event_type": "message.finalized",
    "id": "b40653f5-91cd-46b1-9542-0c092bd29795",
    "occurred_at": "2023-08-08T10:29:36.090+00:00",
    "payload": {
      "direction": "outbound",
      "from": {
        "phone_number": "+15551234567"
      },
      "group_message_id": "403189d4-b1d6-4993-b263-6470e5224430",
      "id": "403189d4-b1d6-4993-b263-6470e5224430",
      "to": [
        {
          "phone_number": "+15559876543",
          "status": "delivered"
        }
      ],
      "text": "Hey team, check out this photo!",
      "type": "MMS"
    },
    "record_type": "event"
  }
}

Comparison with other providers

Feature	Telnyx	Twilio	Vonage
Group MMS support	✅ Native, single API call	⚠️ Requires Conversations API	❌ Not natively supported
Max participants	8 + sender	10 total	N/A
Dedicated endpoint	✅ `/v2/messages/group_mms`	❌ Requires Conversations setup	N/A
Setup complexity	Single POST request	Multi-step (create conversation, add participants)	N/A
Per-recipient tracking	✅ Individual webhooks	✅ Via Conversations events	N/A
US/Canada support	✅	✅	N/A

Troubleshooting

Verify all to numbers are valid US or Canadian wireless numbers
Group MMS requires MMS-capable handsets — landlines and some VoIP numbers won’t receive them
Check that you haven’t exceeded the 8-recipient limit
Ensure your messaging profile uses v2 webhook version — go to Messaging, edit your profile, and confirm the webhook version
Verify your webhook URL is accessible and returning 200 OK

This is expected for non-Telnyx recipients. The MMS protocol does not reliably support delivery receipts across all carriers. Only Telnyx-to-Telnyx messages will show confirmed delivery status.

Next steps

New to Telnyx messaging? Start here Handle delivery confirmations and inbound messages Learn about long codes, toll-free, and short codes Full messaging API documentation

Alphanumeric Sender ID

Source: https://developers.telnyx.com/docs/messaging/messages/alphanumeric-sender-id.md

Alphanumeric Sender IDs allow you to send SMS messages using a custom text identifier (like your brand name) instead of a phone number. This makes messages instantly recognizable to recipients—they see “TELNYX” instead of a random number. Alphanumeric Sender IDs are one-way only. Recipients cannot reply to messages sent from alphanumeric senders.

Format requirements

Your alphanumeric sender ID must follow these rules:

Requirement	Value
Length	1–11 characters
Allowed characters	Letters (A-Z, a-z), numbers (0-9), spaces
Must contain	At least one letter

Country restrictions: Alphanumeric senders cannot send to the United States, Canada, or Puerto Rico. Use a long code or toll-free number for these destinations.

Before you begin

To use alphanumeric sender IDs, you need:

A Telnyx account with Level 2 verification
A Messaging Profile configured with your alphanumeric sender ID
An API key

Some countries require sender ID pre-registration. Check with Telnyx support for destination-specific requirements.

Send a message

Use the send message endpoint with your alphanumeric sender ID in the from field.

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "YourBrand",
    "to": "+447700900123",
    "text": "Your order has shipped!",
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
  }'

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"

telnyx.Message.create(
    from_="YourBrand",
    to="+447700900123",
    text="Your order has shipped!",
    messaging_profile_id="YOUR_MESSAGING_PROFILE_ID"
)

Node

import Telnyx from 'telnyx';

const telnyx = new Telnyx('YOUR_API_KEY');

const message = await telnyx.messages.create({
  from: 'YourBrand',
  to: '+447700900123',
  text: 'Your order has shipped!',
  messaging_profile_id: 'YOUR_MESSAGING_PROFILE_ID'
});

console.log(message.data);

Ruby

require 'telnyx'

Telnyx.api_key = 'YOUR_API_KEY'

Telnyx::Message.create(
  from: 'YourBrand',
  to: '+447700900123',
  text: 'Your order has shipped!',
  messaging_profile_id: 'YOUR_MESSAGING_PROFILE_ID'
)

PHP

\Telnyx\Telnyx::setApiKey('YOUR_API_KEY');

\Telnyx\Message::Create([
  'from' => 'YourBrand',
  'to' => '+447700900123',
  'text' => 'Your order has shipped!',
  'messaging_profile_id' => 'YOUR_MESSAGING_PROFILE_ID'
]);

Java

import com.telnyx.sdk.ApiClient;
import com.telnyx.sdk.Configuration;
import com.telnyx.sdk.auth.HttpBearerAuth;
import com.telnyx.sdk.model.CreateMessageRequest;
import com.telnyx.sdk.api.MessagesApi;

public class SendAlphanumeric {
    public static void main(String[] args) {
        ApiClient client = Configuration.getDefaultApiClient();
        client.setBasePath("https://api.telnyx.com/v2");

        HttpBearerAuth auth = (HttpBearerAuth) client.getAuthentication("bearerAuth");
        auth.setBearerToken("YOUR_API_KEY");

        MessagesApi api = new MessagesApi(client);
        CreateMessageRequest request = new CreateMessageRequest()
            .from("YourBrand")
            .to("+447700900123")
            .text("Your order has shipped!");

        api.createMessage(request);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey("YOUR_API_KEY");

var service = new MessagingSenderIdService();
var response = await service.CreateAsync(new NewMessagingSenderId
{
    From = "YourBrand",
    To = "+447700900123",
    Text = "Your order has shipped!"
});

Replace:

YOUR_API_KEY with your API key
YourBrand with your alphanumeric sender ID (1–11 characters)
YOUR_MESSAGING_PROFILE_ID with your messaging profile ID

US and Canada fallback

If you need to reach US or Canadian recipients, configure a fallback long code on your messaging profile. Telnyx will automatically use this number instead of the alphanumeric sender for restricted destinations. Configure this in the Messaging Portal or via the Messaging Profiles API.

Limitations

Feature	Supported
SMS	Yes
MMS	No
Inbound messages	No
US/CA/PR destinations	No (use fallback)

Rate limits

Account level	Rate limit
Level 1 (unverified)	6 messages/minute
Level 2 (verified)	60 messages/minute

Need higher throughput? Contact sales@telnyx.com.

Failover behavior

Telnyx attempts to deliver your message whenever possible. If alphanumeric delivery fails for a destination:

If a US fallback long code is configured, Telnyx uses that number
Otherwise, Telnyx may use a generic alphanumeric sender ID to complete delivery

Common errors

Error	Cause	Solution
`InvalidFromAddress`	Invalid sender format	Use 1–11 characters with at least one letter
`AlphaSenderNotConfigured`	No alphanumeric sender on profile	Configure sender ID on your messaging profile
`UnsupportedDestination`	Sending to US/CA/PR	Use a long code or configure a fallback number

Next steps

Create and configure messaging profiles via API Complete messaging quickstart guide Compare alphanumeric, long code, toll-free, and short codes Full send message API documentation

International Compliance

Source: https://developers.telnyx.com/docs/messaging/messages/international-sms-compliance.md

Sending SMS internationally requires compliance with country-specific regulations for sender IDs, opt-in consent, content restrictions, and registration requirements. This guide covers the top 10 international messaging destinations and their specific rules. Quick links: Country-by-country reference · Sender ID types · Opt-in requirements · Content restrictions · Pre-registration Regulations change frequently. This guide reflects requirements as of early 2026. Always verify current requirements with Telnyx support before launching messaging in a new country.

Sender ID types by country

Not every sender type works in every country. Here’s what’s supported in the top international destinations:

Country	Alphanumeric ID	Long Code	Short Code	Toll-Free	Pre-Registration
🇺🇸 United States	❌	✅ (10DLC)	✅	✅	10DLC required
🇨🇦 Canada	❌	✅	✅	✅	Short code approval
🇬🇧 United Kingdom	✅	✅	✅	—	Recommended
🇩🇪 Germany	✅	✅	✅	—	No
🇫🇷 France	✅	✅	✅	—	OACP required
🇪🇸 Spain	✅	✅	✅	—	No
🇦🇺 Australia	✅	✅	✅	—	Sender ID registration
🇮🇳 India	✅ (registered)	❌	❌	—	DLT mandatory
🇧🇷 Brazil	✅	✅	✅	—	No
🇲🇽 Mexico	✅	✅	✅	—	No

US/Canada note: Alphanumeric sender IDs are not supported for US and Canadian destinations. Use 10DLC, toll-free, or short codes.

Countries requiring pre-registration

Several countries require sender ID or entity registration before you can send messages. Failing to register results in blocked traffic or filtered messages.

Mandatory registration

India requires Distributed Ledger Technology (DLT) registration for all A2P SMS. This is the most complex international registration requirement. What you need:

Entity registration on a DLT platform (JioConnect, Vodafone DLT, Airtel DLT, or BSNL DLT)
Header (sender ID) registration — your alphanumeric sender ID must be approved
Template registration — every message template must be pre-approved
Content category — transactional, promotional, or service

Registration steps:

Register as a business entity on one of the DLT platforms
Submit your sender ID (called “header”) for approval
Create and submit message templates
Provide Telnyx with your DLT Entity ID, registered headers, and template IDs

Message categories:

Category	Allowed Hours	DND Filtering	Example
Transactional	24/7	Exempt	OTP, order confirmations
Service (Implicit)	24/7	Exempt	Account updates to existing customers
Promotional	9 AM – 9 PM IST	Applies	Marketing, offers, discounts

Promotional messages to users on the Do Not Disturb (DND) registry will be blocked. Transactional and service messages are exempt from DND filtering. Template format:

Dear {#var#}, your order {#var#} has been shipped.
Track at {#var#}. Delivery by {#var#}.

Variables are marked with {#var#} and the template must match exactly at delivery time. France requires registration through the Off-net Application-to-Person (OACP) framework for commercial SMS. Requirements:

Sender ID must be registered with French carriers
Opt-out must include “STOP” at no cost to the recipient
Commercial messages restricted to 8 AM – 8 PM local time
No commercial SMS on Sundays or public holidays
CNIL (French data authority) consent rules apply

Registration process:

Submit sender ID registration through Telnyx support
Provide business documentation (SIRET number for French businesses)
Allow 5–10 business days for approval

Unregistered sender IDs may be silently filtered by French carriers. Australia’s ACMA requires sender ID registration for A2P messaging. Requirements:

Alphanumeric sender IDs must be registered with carriers
Messages must include opt-out instructions
Commercial messages must comply with the Spam Act 2003
Sender must have consent (express or inferred)

Registration:

Submit sender ID through Telnyx support
Provide Australian Business Number (ABN) or equivalent
Typical approval: 3–5 business days

Singapore’s SMS Sender ID Registry (SSIR) requires all organizations to register sender IDs. Requirements:

Mandatory SSIR registration since January 2023
Unregistered alphanumeric sender IDs display as “Likely-SCAM”
Registration through SGNIC (Singapore Network Information Centre)

Process:

Register on the SSIR portal (sgnic.sg)
Submit sender ID with business documentation
Link registered sender ID to Telnyx account via support

Recommended (not mandatory) registration

Country	Registration	Benefit
🇬🇧 United Kingdom	Sender ID pre-registration	Higher delivery rates, reduced filtering
🇩🇪 Germany	None required	—
🇪🇸 Spain	None required	—
🇧🇷 Brazil	Sender ID registration	Better deliverability
🇲🇽 Mexico	None required	—

Opt-in requirements by region

The EU’s GDPR and ePrivacy Directive set the baseline for all EU/EEA countries: Recipients must actively opt in to receive messages. Pre-checked boxes are not valid consent under GDPR. Consent must specify what types of messages the user will receive. “We may contact you” is too vague. Users must be able to opt out at any time, and the process must be as easy as opting in. Maintain records of when and how consent was obtained. You must be able to prove consent if challenged. GDPR-compliant consent example:

☐ I agree to receive appointment reminders and order updates from [Company]
  via SMS to the phone number provided. Message frequency: up to 4 msg/month.
  Reply STOP to unsubscribe. Msg & data rates may apply.

Country variations within the EU:

Germany: Requires “double opt-in” (confirmation SMS after initial signup) as best practice
France: CNIL requires explicit, separate consent for marketing SMS
Spain: AEPD allows “soft opt-in” for existing customers (similar products/services only)
Italy: Garante requires clear separation between service and marketing consent

North America

Requirement	United States	Canada
Governing law	TCPA + CTIA guidelines	CASL
Consent type	Express written (marketing) / Express (transactional)	Express or implied
Opt-out mechanism	STOP keyword mandatory	Unsubscribe mechanism required
Record retention	Recommended 4+ years	Duration of consent
Pre-registration	10DLC / toll-free verification	Short code approval

Asia-Pacific

Country	Key requirement
🇮🇳 India	DLT registration + template approval. DND registry filtering for promotional.
🇦🇺 Australia	Express consent required (Spam Act 2003). Include sender identity + opt-out.
🇸🇬 Singapore	SSIR registration. PDPA consent rules. No SMS between 9 PM – 9 AM without consent.
🇯🇵 Japan	Act on Specified Commercial Transactions. Opt-out link required. Sender identification mandatory.
🇰🇷 South Korea	Pre-approved templates only. 080 opt-out number required for commercial messages.

Latin America

Country	Key requirement
🇧🇷 Brazil	LGPD consent required. No messages between 9 PM – 9 AM. Include opt-out.
🇲🇽 Mexico	LFPDPPP consent. Include sender identity. Opt-out mechanism required.
🇨🇴 Colombia	SIC consent requirements. Habeas Data law. Pre-registration recommended.
🇦🇷 Argentina	PDPA consent. National Do Not Call Registry must be checked.

Content restrictions

Universally restricted content

These content types are restricted or prohibited in most countries:

Content type	Status	Notes
Cannabis / CBD	🚫 Prohibited in most countries	Even where locally legal, carriers often block
Gambling	⚠️ Heavily regulated	Requires specific licensing in most jurisdictions
Adult content	🚫 Prohibited	Blocked by most carriers globally
Phishing / fraud	🚫 Prohibited	Immediate account termination
Financial services	⚠️ Regulated	Must comply with local financial advertising laws
Healthcare / pharma	⚠️ Regulated	Prescription drug messaging restricted in many countries
Political campaigns	⚠️ Varies by country	Some countries ban political SMS entirely

Country-specific restrictions

Financial promotions: Must be approved by an FCA-authorized firm
Age-gated content: Must use age verification for alcohol, gambling
Charity messaging: Regulated by the Fundraising Regulator
Marketing hours: No legal restriction, but industry best practice is 8 AM – 9 PM
UWG (Competition Law): Strict consent requirements for all commercial messages
Heilmittelwerbegesetz: Restricts pharmaceutical advertising
Glücksspielstaatsvertrag: Strict gambling advertising rules
Double opt-in: Expected best practice for marketing consent
Loi Hamon: Right to opt out of all commercial solicitation
Time restrictions: No commercial SMS 8 PM – 8 AM, Sundays, or public holidays
CNIL enforcement: Active enforcement with significant fines
Language: Commercial messages should be in French
Promotional hours: 9 AM – 9 PM IST only (mandatory, not best practice)
DND registry: Promotional messages blocked to DND-registered numbers
Template approval: Every message must match a pre-approved template
Scrubbing: Numbers are checked against DND registry before delivery
LGPD compliance: Explicit consent with specific purpose
Quiet hours: 9 PM – 9 AM (industry standard)
Consumer code: Price/offer messages must include full terms
Language: Messages should be in Portuguese

Country-by-country reference

🇬🇧 United Kingdom

Setting	Value
Sender types	Alphanumeric (recommended), long code, short code
Alphanumeric length	3–11 characters
Regulation	PECR + UK GDPR
Regulator	ICO (Information Commissioner’s Office)
Pre-registration	Recommended (improves deliverability)
Opt-out	STOP keyword or unsubscribe link
Time restrictions	None (best practice: 8 AM – 9 PM)

Send with alphanumeric sender ID:

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "YourBrand",
    "to": "+447700900123",
    "text": "Hi! Your delivery is scheduled for tomorrow between 2-4 PM. Reply STOP to opt out.",
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
  }'

Python

import telnyx
import os

telnyx.api_key = os.environ["TELNYX_API_KEY"]

message = telnyx.Message.create(
    from_="YourBrand",
    to="+447700900123",
    text="Hi! Your delivery is scheduled for tomorrow between 2-4 PM. Reply STOP to opt out.",
    messaging_profile_id="YOUR_MESSAGING_PROFILE_ID",
)
print(f"Message ID: {message.id}")

Node

import Telnyx from "telnyx";

const telnyx = new Telnyx(process.env.TELNYX_API_KEY);

const { data: message } = await telnyx.messages.create({
  from: "YourBrand",
  to: "+447700900123",
  text: "Hi! Your delivery is scheduled for tomorrow between 2-4 PM. Reply STOP to opt out.",
  messaging_profile_id: "YOUR_MESSAGING_PROFILE_ID",
});
console.log(`Message ID: ${message.id}`);

Ruby

require "telnyx"

Telnyx.api_key = ENV["TELNYX_API_KEY"]

message = Telnyx::Message.create(
  from: "YourBrand",
  to: "+447700900123",
  text: "Hi! Your delivery is scheduled for tomorrow between 2-4 PM. Reply STOP to opt out.",
  messaging_profile_id: "YOUR_MESSAGING_PROFILE_ID"
)
puts "Message ID: #{message.id}"

Java

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageCreateParams;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

var message = client.messages().create(MessageCreateParams.builder()
    .from("YourBrand")
    .to("+447700900123")
    .text("Hi! Your delivery is scheduled for tomorrow between 2-4 PM. Reply STOP to opt out.")
    .messagingProfileId("YOUR_MESSAGING_PROFILE_ID")
    .build());
System.out.println("Message ID: " + message.id());

.NET

using Telnyx;

var client = new TelnyxClient(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var message = await client.Messages.CreateAsync(new MessageCreateParams
{
    From = "YourBrand",
    To = "+447700900123",
    Text = "Hi! Your delivery is scheduled for tomorrow between 2-4 PM. Reply STOP to opt out.",
    MessagingProfileId = "YOUR_MESSAGING_PROFILE_ID"
});
Console.WriteLine($"Message ID: {message.Id}");

PHP

$telnyx = new \Telnyx\TelnyxClient(getenv('TELNYX_API_KEY'));

$message = $telnyx->messages->create([
    'from' => 'YourBrand',
    'to' => '+447700900123',
    'text' => 'Hi! Your delivery is scheduled for tomorrow between 2-4 PM. Reply STOP to opt out.',
    'messaging_profile_id' => 'YOUR_MESSAGING_PROFILE_ID',
]);
echo "Message ID: " . $message->id . "\n";

package main

import (
    "context"
    "fmt"
    "github.com/team-telnyx/telnyx-go"
    "github.com/team-telnyx/telnyx-go/option"
)

func main() {
    client := telnyx.NewClient(option.WithAPIKey("YOUR_API_KEY"))

    message, err := client.Messages.New(context.TODO(), telnyx.MessageNewParams{
        From: telnyx.String("YourBrand"),
        To:   telnyx.String("+447700900123"),
        Text: telnyx.String("Hi! Your delivery is scheduled for tomorrow between 2-4 PM. Reply STOP to opt out."),
        MessagingProfileID: telnyx.String("YOUR_MESSAGING_PROFILE_ID"),
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Message ID: %s\n", message.ID)
}

🇮🇳 India

Setting	Value
Sender types	Alphanumeric only (6 characters, registered header)
Regulation	TRAI + DLT framework
Regulator	TRAI (Telecom Regulatory Authority of India)
Pre-registration	Mandatory — DLT entity, header, and template registration
Opt-out	Handled via DLT/DND registry
Time restrictions	Promotional: 9 AM – 9 PM IST only

India requires both sender ID registration and message template approval before any messages can be sent. Contact Telnyx support to initiate India DLT registration.

🇩🇪 Germany

Setting	Value
Sender types	Alphanumeric, long code
Regulation	GDPR + UWG (Competition Act) + TTDSG
Regulator	BfDI (Federal Data Protection Commissioner)
Pre-registration	Not required
Opt-out	Must be free and easy (STOP keyword or link)
Time restrictions	None legally, best practice 8 AM – 9 PM

🇫🇷 France

Setting	Value
Sender types	Alphanumeric (registered via OACP), long code, short code
Regulation	GDPR + Code des postes et des communications
Regulator	CNIL + ARCEP
Pre-registration	Required — OACP sender ID registration
Opt-out	”STOP” at no cost to recipient (mandatory)
Time restrictions	8 AM – 8 PM, no Sundays/holidays (mandatory for commercial)

🇦🇺 Australia

Setting	Value
Sender types	Alphanumeric (registered), long code, short code
Regulation	Spam Act 2003 + Privacy Act 1988
Regulator	ACMA
Pre-registration	Required (sender ID registration)
Opt-out	Functional unsubscribe within 5 business days
Time restrictions	None legally, best practice 9 AM – 8 PM AEST

🇧🇷 Brazil

Setting	Value
Sender types	Alphanumeric, long code, short code
Regulation	LGPD + Consumer Protection Code
Regulator	ANPD (National Data Protection Authority)
Pre-registration	Recommended
Opt-out	Easy mechanism required
Time restrictions	9 PM – 9 AM quiet hours (industry standard)

🇲🇽 Mexico

Setting	Value
Sender types	Alphanumeric, long code, short code
Regulation	LFPDPPP (Federal Data Protection Law)
Regulator	INAI
Pre-registration	Not required
Opt-out	Mechanism required in privacy notice
Time restrictions	None legally

Best practices for international messaging

Review this guide and contact Telnyx support for any country not listed. Requirements vary significantly and change frequently. Alphanumeric sender IDs are preferred in most international markets (except US/Canada). They build brand recognition and improve open rates. Send messages in the recipient’s language. Many countries require or strongly recommend this for commercial messaging. Even where not legally required, sending during business hours dramatically reduces complaints and opt-outs. Universal best practice. Use language appropriate to the country (e.g., “STOP” in English-speaking countries, “ARRÊT” in France). Store when and how each recipient consented. GDPR requires you to prove consent if challenged. Keep records for at least 4 years. Use Message Detail Records to track delivery rates per country. Sudden drops may indicate registration issues or content filtering.

Handling multi-country messaging

For platforms sending to multiple countries, implement country-aware routing:

Python

import telnyx
import os

telnyx.api_key = os.environ["TELNYX_API_KEY"]

# Country-specific configuration
COUNTRY_CONFIG = {
    "US": {
        "from": "+12025551234",  # 10DLC registered number
        "profile": "us-messaging-profile-id",
    },
    "GB": {
        "from": "YourBrand",  # Alphanumeric sender ID
        "profile": "intl-messaging-profile-id",
    },
    "IN": {
        "from": "YRBRAND",  # 6-char registered DLT header
        "profile": "india-messaging-profile-id",
    },
    "DEFAULT": {
        "from": "YourBrand",
        "profile": "intl-messaging-profile-id",
    },
}

def send_international_sms(to: str, text: str, country_code: str):
    """Send an SMS with country-appropriate sender and profile."""
    config = COUNTRY_CONFIG.get(country_code, COUNTRY_CONFIG["DEFAULT"])

    message = telnyx.Message.create(
        from_=config["from"],
        to=to,
        text=text,
        messaging_profile_id=config["profile"],
    )
    return message

# Usage
send_international_sms("+447700900123", "Your order shipped!", "GB")
send_international_sms("+12025559876", "Your order shipped!", "US")
send_international_sms("+919876543210", "Your order shipped!", "IN")

Node

import Telnyx from "telnyx";

const telnyx = new Telnyx(process.env.TELNYX_API_KEY);

const COUNTRY_CONFIG = {
  US: { from: "+12025551234", profile: "us-messaging-profile-id" },
  GB: { from: "YourBrand", profile: "intl-messaging-profile-id" },
  IN: { from: "YRBRAND", profile: "india-messaging-profile-id" },
  DEFAULT: { from: "YourBrand", profile: "intl-messaging-profile-id" },
};

async function sendInternationalSms(to, text, countryCode) {
  const config = COUNTRY_CONFIG[countryCode] || COUNTRY_CONFIG.DEFAULT;

  const { data: message } = await telnyx.messages.create({
    from: config.from,
    to,
    text,
    messaging_profile_id: config.profile,
  });
  return message;
}

// Usage
await sendInternationalSms("+447700900123", "Your order shipped!", "GB");
await sendInternationalSms("+12025559876", "Your order shipped!", "US");

Next steps

Set up branded sender IDs for international messaging. Handle character encoding for international scripts (Arabic, Chinese, etc.). Understand delivery errors including country-specific rejections. US-specific registration for A2P messaging.

MMS Converter

Source: https://developers.telnyx.com/docs/messaging/messages/mms-converter.md

While your message’s source number may support sending MMS, the destination number might not support receiving it. Normally, this will prevent you from sending MMS to this destination. When MMS converter is enabled on your messaging profile, however, your MMS will be converted to an SMS message by Telnyx and then sent to the destination. Messages sent as SMS are unaffected by this feature and will be sent as usual. The resultant webhooks for messages sent with this feature enabled will indicate the protocol that was used to send the message. For example: when an MMS message is sent and fallback happens, the webhook will indicate that an SMS message was sent, and when an MMS message is sent and fallback doesn’t happen, the webhook will indicate that an MMS message was sent. If fallback happens, the destination will receive an SMS formatted to contain the media URLs specified in the request. Each media URL will appear on its own line, immediately after the message body, if any.

Examples

Note how the media URL(s) appear on the destination exactly as provided in the request. No shortlinking or other transformations are applied on your behalf.

Message body and one media URL

If your request includes:

"text": "message body that\nis potentially spread across multiple lines"
"media_urls": ["https://example.com/image.png"]

The message received on the destination will look like this:

message body that
is potentially spread across multiple lines
https://example.com/image.png

Message body and two media URLs

If your request includes:

"text": "message body"
"media_urls": ["https://example.com/one.png", "https://example.com/two.png"]

The message received on the destination will look like this:

message body
https://example.com/one.png
https://example.com/two.png

Only one media URL

If your request doesn’t set text and includes:

"media_urls": ["https://example.com/image.png"]

The message received on the destination will look like this:

https://example.com/image.png

Enable MMS converter

This behavior is not enabled by default; if you want to make use of this feature then you must enable it first. This is controlled at the messaging profile level by an optional boolean field called mms_fall_back_to_sms, which you can either set at creation time or update later if you’d like to change an existing messaging profile.

MMS Media & Transcoding

Source: https://developers.telnyx.com/docs/messaging/messages/mms-transcoding.md

MMS messages let you send images, videos, and other media files alongside text. This guide covers supported media types, carrier size limits, and how to use Telnyx’s automatic transcoding to ensure delivery. MMS is supported on Long Code, Toll-Free, and Short Code numbers in the US and Canada. International MMS support varies by carrier.

Send an MMS message

Include one or more media_urls in your message request to send an MMS:

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Check out this image!",
    "media_urls": ["https://example.com/image.jpg"]
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messages.send(
    from_="+15551234567",
    to="+15559876543",
    text="Check out this image!",
    media_urls=["https://example.com/image.jpg"],
)

print(response.data)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Check out this image!',
  media_urls: ['https://example.com/image.jpg'],
});

console.log(response.data);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: "+15559876543",
  text: "Check out this image!",
  media_urls: ["https://example.com/image.jpg"]
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From:      "+15551234567",
    To:        "+15559876543",
    Text:      "Check out this image!",
    MediaURLs: []string{"https://example.com/image.jpg"},
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;

import java.util.List;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var params = MessageSendParams.builder()
            .from("+15551234567")
            .to("+15559876543")
            .text("Check out this image!")
            .mediaUrls(List.of("https://example.com/image.jpg"))
            .build();

        var response = client.messages().send(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Check out this image!",
    MediaUrls = new List { "https://example.com/image.jpg" }
});

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => 'Check out this image!',
    'media_urls' => ['https://example.com/image.jpg']
]);

print_r($response);

You can include up to 10 media URLs per MMS message. Each URL must be publicly accessible — Telnyx fetches the media at send time.

Supported media types

Category	Formats	Notes
Images	JPEG, PNG, GIF, BMP, TIFF, WebP	Most widely supported across carriers
Video	MP4, 3GP, MOV	H.264 codec recommended
Audio	MP3, WAV, AMR, OGG	Limited carrier support
Documents	PDF, vCard (.vcf), iCal (.ics)	Limited carrier support

Animated GIFs are not supported for transcoding. If you send animated GIFs, ensure they are under the carrier size limit — they will not be resized.

Carrier size limits

Each US carrier imposes different maximum MMS message sizes based on the sender type. Messages exceeding these limits will be rejected by the carrier.

Carrier	Long Code	Toll-Free	Short Code
AT&T	1 MB	600 KB	600 KB
T-Mobile	1.5 MB	600 KB	1 MB
Verizon	1 MB	600 KB	1.2 MB

The safe maximum across all carriers and sender types is 600 KB. To guarantee delivery to all recipients regardless of carrier, keep your total media under this limit — or enable transcoding.

Automatic transcoding

Telnyx can automatically resize media to comply with carrier size limits. When enabled, oversized images and videos are resized before delivery.

How transcoding works

You send an MMS with media that exceeds the destination carrier’s size limit
Telnyx detects the destination carrier and its size restriction
Media is resized to fit within the limit:
- Images → converted to JPEG
- Videos → converted to H.264 MP4
The resized media is delivered to the recipient

Transcoding reduces media quality to meet size constraints. For best results, optimize your media before sending.

Enable transcoding

Enable mms_transcoding on your messaging profile to apply it to all MMS sent through that profile.

curl

curl -X PATCH https://api.telnyx.com/v2/messaging_profiles/{profile_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "mms_transcoding": true
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messaging_profiles.update(
    "your_messaging_profile_id",
    mms_transcoding=True,
)

print(response.data)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messagingProfiles.update(
  'your_messaging_profile_id',
  { mms_transcoding: true }
);

console.log(response.data);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messaging_profiles.update(
  "your_messaging_profile_id",
  mms_transcoding: true
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.MessagingProfiles.Update(
    context.TODO(),
    "your_messaging_profile_id",
    telnyx.MessagingProfileUpdateParams{
      MMSTranscoding: telnyx.Bool(true),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messagingprofiles.MessagingProfileUpdateParams;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var params = MessagingProfileUpdateParams.builder()
            .mmsTranscoding(true)
            .build();

        var response = client.messagingProfiles()
            .update("your_messaging_profile_id", params);

        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessagingProfileService();
var response = await service.UpdateAsync(
    "your_messaging_profile_id",
    new MessagingProfileUpdateOptions
    {
        MmsTranscoding = true
    }
);

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\MessagingProfile::Update(
    'your_messaging_profile_id',
    ['mms_transcoding' => true]
);

print_r($response);

Navigate to Messaging > Messaging Profiles in the portal. Click on the messaging profile you want to update. Toggle MMS Transcoding to enabled. Click Save to apply.

Best practices

Pre-optimize your media for the best balance of quality and deliverability:

Images: Resize to 640×480 or smaller, use JPEG at 80% quality
Videos: Compress to H.264, keep under 30 seconds, target 480p
Target size: Stay under 600 KB for universal carrier compatibility

This gives you control over quality rather than relying on automatic transcoding. Media URLs must be publicly accessible — Telnyx fetches them at send time. Ensure:

URLs don’t require authentication
URLs respond quickly (timeouts cause delivery failures)
URLs return the correct Content-Type header
URLs use HTTPS for security

Inbound MMS media URLs in webhooks are ephemeral — they expire after a short period. Always download and store important media to your own storage (e.g., AWS S3) immediately upon receiving the webhook. See the Send & Receive MMS tutorial for a complete implementation. If your message doesn’t include media, send it as SMS instead of MMS. SMS is:

Cheaper — MMS messages cost more than SMS
Faster — No media download/processing overhead
More reliable — Fewer points of failure

Only use MMS when you actually need to include media content.

Full tutorial for building an MMS application with media storage. Customize the layout of your MMS media with SMIL templates. Get started with the Telnyx Messaging API. API reference for sending messages with media.

Schedule Messages

Source: https://developers.telnyx.com/docs/messaging/messages/schedule-message.md

Schedule SMS and MMS messages to send at a specific time in the future. Use scheduled messaging for appointment reminders, marketing campaigns, time-zone-aware notifications, and any scenario where precise delivery timing matters.

Prerequisites

A Telnyx account
A Messaging Profile with an assigned phone number
An API key

How scheduled messaging works

When you schedule a message, Telnyx stores it and delivers it at the specified time. Here’s how it works:

You send a request with a send_at timestamp set in the future
Telnyx validates the request and returns a message resource with status: "scheduled"
At the scheduled time (accurate to the minute), Telnyx sends the message
Standard webhooks fire as the message is processed and delivered

Scheduling constraints:

send_at must be at least 5 minutes in the future
send_at must be no more than 5 days in the future
Scheduling accuracy is up to 1 minute
Maximum of 1 million scheduled messages at any given time

Schedule a message

You can schedule messages using either endpoint:

POST /v2/messages — The standard send endpoint, with the send_at parameter added
POST /v2/messages/schedule — A dedicated scheduling endpoint with the same parameters

Both endpoints accept identical parameters. The examples below use /v2/messages with send_at. Export your API key as an environment variable:

export TELNYX_API_KEY="YOUR_API_KEY"

The send_at field requires an ISO 8601 formatted datetime string in UTC. For example:

2026-02-15T14:30:00Z — February 15, 2026 at 2:30 PM UTC
2026-02-14T09:00:00-08:00 — February 14, 2026 at 9:00 AM PST

Time zone tip: Always convert your desired delivery time to UTC, or include the UTC offset. Messages are delivered based on the UTC time you specify, not the recipient’s local time zone.

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Reminder: Your appointment is tomorrow at 10 AM.",
    "send_at": "2026-02-15T14:30:00Z"
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.send(
    from_="+15551234567",
    to="+15559876543",
    text="Reminder: Your appointment is tomorrow at 10 AM.",
    send_at="2026-02-15T14:30:00Z"
)

print(response.data)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Reminder: Your appointment is tomorrow at 10 AM.',
  send_at: '2026-02-15T14:30:00Z'
});

console.log(response.data);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: "+15559876543",
  text: "Reminder: Your appointment is tomorrow at 10 AM.",
  send_at: "2026-02-15T14:30:00Z"
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From:   "+15551234567",
    To:     "+15559876543",
    Text:   "Reminder: Your appointment is tomorrow at 10 AM.",
    SendAt: "2026-02-15T14:30:00Z",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendParams params = MessageSendParams.builder()
            .from("+15551234567")
            .to("+15559876543")
            .text("Reminder: Your appointment is tomorrow at 10 AM.")
            .sendAt("2026-02-15T14:30:00Z")
            .build();

        MessageSendResponse response = client.messages().send(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Reminder: Your appointment is tomorrow at 10 AM.",
    SendAt = "2026-02-15T14:30:00Z"
});

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => 'Reminder: Your appointment is tomorrow at 10 AM.',
    'send_at' => '2026-02-15T14:30:00Z'
]);

print_r($response);

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Check out our weekend sale!",
    "subject": "Weekend Sale",
    "media_urls": ["https://example.com/sale-banner.jpg"],
    "send_at": "2026-02-15T14:30:00Z"
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.send(
    from_="+15551234567",
    to="+15559876543",
    text="Check out our weekend sale!",
    subject="Weekend Sale",
    media_urls=["https://example.com/sale-banner.jpg"],
    send_at="2026-02-15T14:30:00Z"
)

print(response.data)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.send({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Check out our weekend sale!',
  subject: 'Weekend Sale',
  media_urls: ['https://example.com/sale-banner.jpg'],
  send_at: '2026-02-15T14:30:00Z'
});

console.log(response.data);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "+15551234567",
  to: "+15559876543",
  text: "Check out our weekend sale!",
  subject: "Weekend Sale",
  media_urls: ["https://example.com/sale-banner.jpg"],
  send_at: "2026-02-15T14:30:00Z"
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From:      "+15551234567",
    To:        "+15559876543",
    Text:      "Check out our weekend sale!",
    Subject:   "Weekend Sale",
    MediaURLs: []string{"https://example.com/sale-banner.jpg"},
    SendAt:    "2026-02-15T14:30:00Z",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;
import java.util.List;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendParams params = MessageSendParams.builder()
            .from("+15551234567")
            .to("+15559876543")
            .text("Check out our weekend sale!")
            .subject("Weekend Sale")
            .mediaUrls(List.of("https://example.com/sale-banner.jpg"))
            .sendAt("2026-02-15T14:30:00Z")
            .build();

        MessageSendResponse response = client.messages().send(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "+15551234567",
    To = "+15559876543",
    Text = "Check out our weekend sale!",
    Subject = "Weekend Sale",
    MediaUrls = new[] { "https://example.com/sale-banner.jpg" },
    SendAt = "2026-02-15T14:30:00Z"
});

Console.WriteLine(response.Data);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '+15551234567',
    'to' => '+15559876543',
    'text' => 'Check out our weekend sale!',
    'subject' => 'Weekend Sale',
    'media_urls' => ['https://example.com/sale-banner.jpg'],
    'send_at' => '2026-02-15T14:30:00Z'
]);

print_r($response);

Response

A successful response returns the message with status: "scheduled":

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+15551234567"
    },
    "to": [
      {
        "phone_number": "+15559876543",
        "status": "scheduled"
      }
    ],
    "text": "Reminder: Your appointment is tomorrow at 10 AM.",
    "send_at": "2026-02-15T14:30:00Z"
  }
}

Save the id — you’ll need it to retrieve or cancel the scheduled message.

Retrieve a scheduled message

Check the status of a scheduled message with GET /v2/messages/{id}:

curl

curl -X GET https://api.telnyx.com/v2/messages/b0c7e8cb-6227-4c74-9f32-c7f80c30934b \
  -H "Authorization: Bearer $TELNYX_API_KEY"

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.retrieve("b0c7e8cb-6227-4c74-9f32-c7f80c30934b")

print(response.data)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.retrieve(
  'b0c7e8cb-6227-4c74-9f32-c7f80c30934b'
);

console.log(response.data);

The retrieve endpoint can only access messages created within the last 10 days. For older messages, generate an MDR report.

Cancel a scheduled message

Cancel a message that hasn’t been sent yet with DELETE /v2/messages/{id}:

curl

curl -X DELETE https://api.telnyx.com/v2/messages/b0c7e8cb-6227-4c74-9f32-c7f80c30934b \
  -H "Authorization: Bearer $TELNYX_API_KEY"

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.delete("b0c7e8cb-6227-4c74-9f32-c7f80c30934b")

print(response.data)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.del(
  'b0c7e8cb-6227-4c74-9f32-c7f80c30934b'
);

console.log(response.data);

Cancellation rules:

The message must have status: "scheduled"
The send_at time must be more than 1 minute in the future
Once a message begins sending, it cannot be cancelled

Webhooks

Scheduled messages trigger the same messaging webhooks as immediate messages. The webhook sequence is:

message.sent — Fires when the message is sent at the scheduled time
message.finalized — Fires when delivery is confirmed or fails

{
  "data": {
    "event_type": "message.sent",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "occurred_at": "2026-02-15T14:30:01Z",
    "payload": {
      "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
      "direction": "outbound",
      "type": "SMS",
      "from": {
        "phone_number": "+15551234567"
      },
      "to": [
        {
          "phone_number": "+15559876543",
          "status": "sent"
        }
      ],
      "text": "Reminder: Your appointment is tomorrow at 10 AM."
    }
  }
}

Use cases

Schedule reminders 24 hours before an appointment:

Python

from datetime import datetime, timedelta, timezone
import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

appointment_time = datetime(2026, 2, 16, 10, 0, tzinfo=timezone.utc)
reminder_time = appointment_time - timedelta(hours=24)

response = client.messages.send(
    from_="+15551234567",
    to="+15559876543",
    text=f"Reminder: Your appointment is tomorrow at {appointment_time.strftime('%I:%M %p')} UTC.",
    send_at=reminder_time.isoformat()
)

print(f"Reminder scheduled for {reminder_time.isoformat()}, message ID: {response.data.id}")

Send marketing messages during business hours in each recipient’s time zone:

Python

from datetime import datetime, timezone, timedelta
import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

recipients = [
    {"number": "+15551234567", "tz_offset": -5},  # EST
    {"number": "+15559876543", "tz_offset": -8},  # PST
    {"number": "+15557654321", "tz_offset": -6},  # CST
]

for recipient in recipients:
    # Send at 10:00 AM in each recipient's local time
    local_10am = datetime(2026, 2, 16, 10, 0, tzinfo=timezone(timedelta(hours=recipient["tz_offset"])))
    utc_time = local_10am.astimezone(timezone.utc)

    response = client.messages.send(
        from_="+15550001111",
        to=recipient["number"],
        text="Weekend flash sale! 20% off with code WEEKEND20.",
        send_at=utc_time.isoformat()
    )
    print(f"Scheduled for {recipient['number']} at {utc_time.isoformat()}")

Limits and rate limiting

Scheduling window: 5 minutes to 5 days in the future
Maximum scheduled messages: 1 million at any given time
Accuracy: Messages are sent within 1 minute of the scheduled time
Rate limits: The same rate limits apply to scheduled messages as to immediate messages — both when creating the scheduled message and when it’s sent

Comparison with other providers

Feature	Telnyx	Twilio	Vonage
Scheduling window	5 min – 5 days	15 min – 35 days	Not natively supported
Cancellation	✅ Up to 1 min before send time	✅ Up to 1 hour before send time	N/A
Dedicated endpoint	✅ `/v2/messages/schedule`	❌ Same endpoint only	N/A
Requires Messaging Service	❌ Optional	✅ Required	N/A
Additional cost	❌ Free	❌ Free	N/A
Accuracy	~1 minute	~15 minutes	N/A

Next steps

New to Telnyx messaging? Start here Handle delivery confirmations and inbound messages Understand messaging throughput limits Full API parameter documentation

Specifying SMIL Template

Source: https://developers.telnyx.com/docs/messaging/messages/smil-template.md

SMIL specifies how MMS media files are laid out in MMS. Telnyx generates SMIL automatically based on media_urls and text fields. Advanced users can add a smil_template parameter to the MMS message request. This template will then be used to generate a customized SMIL. Example of SMIL template:

Note that the template has parameters enclosed in double braces {{ }}. During the construction of SMIL these parameters will be automatically replaced with locations of text and media contents. In case of media, {{ 0 }} will be replaced with the location of the first URL in the media_urls list, {{ 1 }} will be replaced with the location of the second URL in the media_urls list, and so on. {{ text }} will be replaced with the location of the text content. The SMIL template must be set in smil_template parameter of the MMS request. It must be properly JSON-escaped:

{
  "from": "+13125551234",
  "to": "+18655551234",
  "text": "Hello from Telnyx",
  "media_urls": ["https://example.com/media.jpg"],
  "smil_template": "\n\t\n\t\t<region id=\"Text\" top=\"70%\"..."
}

Please note that many modern handsets (most notably iPhones) ignore SMIL and use their own layout algorithm.

Two-Factor Authentication (2FA)

Source: https://developers.telnyx.com/docs/messaging/messages/2fa.md

Implement SMS-based two-factor authentication (2FA) using the Telnyx Messaging API. This guide covers generating, sending, and verifying one-time passwords (OTPs) with security best practices. Consider the Verify API first. Telnyx offers a dedicated Verify API that handles OTP generation, delivery, and verification for you — including retry logic, rate limiting, and multi-channel support (SMS, voice, WhatsApp). Use this guide only if you need full control over the 2FA flow.

How SMS 2FA works

Generate and send an OTP

Generate a cryptographically secure OTP and send it via SMS:

Python

import os
import secrets
import time

from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

# In production, use a database (Redis, PostgreSQL, etc.)
otp_store = {}

OTP_LENGTH = 6
OTP_EXPIRY_SECONDS = 300  # 5 minutes

def generate_otp() -> str:
    """Generate a cryptographically secure numeric OTP."""
    # Use secrets module for secure random generation
    return "".join(secrets.choice("0123456789") for _ in range(OTP_LENGTH))

def send_otp(phone_number: str) -> dict:
    """Generate and send an OTP to the given phone number."""
    otp = generate_otp()

    # Store OTP with expiry and attempt counter
    otp_store[phone_number] = {
        "otp": otp,
        "expires_at": time.time() + OTP_EXPIRY_SECONDS,
        "attempts": 0,
        "max_attempts": 3,
    }

    # Send via Telnyx
    response = client.messages.send(
        from_=os.environ.get("TELNYX_FROM_NUMBER"),
        to=phone_number,
        text=f"Your verification code is: {otp}. It expires in 5 minutes.",
    )

    return {"message_id": response.data.id, "expires_in": OTP_EXPIRY_SECONDS}

def verify_otp(phone_number: str, submitted_otp: str) -> bool:
    """Verify the submitted OTP. Returns True if valid."""
    record = otp_store.get(phone_number)
    if not record:
        return False

    # Check expiry
    if time.time() > record["expires_at"]:
        del otp_store[phone_number]
        return False

    # Check attempts
    record["attempts"] += 1
    if record["attempts"] > record["max_attempts"]:
        del otp_store[phone_number]
        return False

    # Constant-time comparison to prevent timing attacks
    if secrets.compare_digest(record["otp"], submitted_otp):
        del otp_store[phone_number]  # One-time use
        return True

    return False

# Example usage
result = send_otp("+15559876543")
print(f"OTP sent, message ID: {result['message_id']}")

# Later, when user submits the code:
# is_valid = verify_otp("+15559876543", "123456")

Node

import Telnyx from 'telnyx';
import crypto from 'crypto';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

// In production, use Redis or a database
const otpStore = new Map();

const OTP_LENGTH = 6;
const OTP_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes

function generateOtp() {
  // Cryptographically secure numeric OTP
  const bytes = crypto.randomBytes(OTP_LENGTH);
  return Array.from(bytes).map(b => b % 10).join('');
}

async function sendOtp(phoneNumber) {
  const otp = generateOtp();

  otpStore.set(phoneNumber, {
    otp,
    expiresAt: Date.now() + OTP_EXPIRY_MS,
    attempts: 0,
    maxAttempts: 3,
  });

  const response = await client.messages.send({
    from: process.env.TELNYX_FROM_NUMBER,
    to: phoneNumber,
    text: `Your verification code is: ${otp}. It expires in 5 minutes.`,
  });

  return { messageId: response.data.id, expiresIn: OTP_EXPIRY_MS / 1000 };
}

function verifyOtp(phoneNumber, submittedOtp) {
  const record = otpStore.get(phoneNumber);
  if (!record) return false;

  if (Date.now() > record.expiresAt) {
    otpStore.delete(phoneNumber);
    return false;
  }

  record.attempts++;
  if (record.attempts > record.maxAttempts) {
    otpStore.delete(phoneNumber);
    return false;
  }

  // Constant-time comparison
  if (crypto.timingSafeEqual(
    Buffer.from(record.otp),
    Buffer.from(submittedOtp)
  )) {
    otpStore.delete(phoneNumber);
    return true;
  }

  return false;
}

// Usage
const result = await sendOtp('+15559876543');
console.log(`OTP sent, message ID: ${result.messageId}`);

Ruby

require "telnyx"
require "securerandom"

Telnyx.api_key = ENV["TELNYX_API_KEY"]

# In production, use Redis or a database
$otp_store = {}

OTP_LENGTH = 6
OTP_EXPIRY_SECONDS = 300 # 5 minutes

def generate_otp
  SecureRandom.random_number(10**OTP_LENGTH).to_s.rjust(OTP_LENGTH, "0")
end

def send_otp(phone_number)
  otp = generate_otp

  $otp_store[phone_number] = {
    otp: otp,
    expires_at: Time.now + OTP_EXPIRY_SECONDS,
    attempts: 0,
    max_attempts: 3
  }

  response = Telnyx::Message.create(
    from: ENV["TELNYX_FROM_NUMBER"],
    to: phone_number,
    text: "Your verification code is: #{otp}. It expires in 5 minutes."
  )

  { message_id: response.id, expires_in: OTP_EXPIRY_SECONDS }
end

def verify_otp(phone_number, submitted_otp)
  record = $otp_store[phone_number]
  return false unless record
  return ($otp_store.delete(phone_number); false) if Time.now > record[:expires_at]

  record[:attempts] += 1
  return ($otp_store.delete(phone_number); false) if record[:attempts] > record[:max_attempts]

  if ActiveSupport::SecurityUtils.secure_compare(record[:otp], submitted_otp)
    $otp_store.delete(phone_number)
    true
  else
    false
  end
end

result = send_otp("+15559876543")
puts "OTP sent, message ID: #{result[:message_id]}"

package main

import (
  "context"
  "crypto/rand"
  "crypto/subtle"
  "fmt"
  "math/big"
  "os"
  "sync"
  "time"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

const (
  otpLength        = 6
  otpExpirySeconds = 300
  maxAttempts      = 3
)

type OTPRecord struct {
  OTP       string
  ExpiresAt time.Time
  Attempts  int
}

var (
  otpStore = make(map[string]*OTPRecord)
  mu       sync.Mutex
)

func generateOTP() string {
  otp := make([]byte, otpLength)
  for i := range otp {
    n, _ := rand.Int(rand.Reader, big.NewInt(10))
    otp[i] = byte('0') + byte(n.Int64())
  }
  return string(otp)
}

func sendOTP(client *telnyx.Client, phone string) (string, error) {
  otp := generateOTP()

  mu.Lock()
  otpStore[phone] = &OTPRecord{
    OTP:       otp,
    ExpiresAt: time.Now().Add(otpExpirySeconds * time.Second),
  }
  mu.Unlock()

  resp, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From: os.Getenv("TELNYX_FROM_NUMBER"),
    To:   phone,
    Text: fmt.Sprintf("Your verification code is: %s. It expires in 5 minutes.", otp),
  })
  if err != nil {
    return "", err
  }
  return resp.Data.ID, nil
}

func verifyOTP(phone, submitted string) bool {
  mu.Lock()
  defer mu.Unlock()

  record, ok := otpStore[phone]
  if !ok || time.Now().After(record.ExpiresAt) {
    delete(otpStore, phone)
    return false
  }

  record.Attempts++
  if record.Attempts > maxAttempts {
    delete(otpStore, phone)
    return false
  }

  if subtle.ConstantTimeCompare([]byte(record.OTP), []byte(submitted)) == 1 {
    delete(otpStore, phone)
    return true
  }
  return false
}

func main() {
  client := telnyx.NewClient(option.WithAPIKey(os.Getenv("TELNYX_API_KEY")))
  msgID, err := sendOTP(client, "+15559876543")
  if err != nil {
    panic(err)
  }
  fmt.Printf("OTP sent, message ID: %s\n", msgID)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;

import java.security.MessageDigest;
import java.security.SecureRandom;
import java.time.Instant;
import java.util.concurrent.ConcurrentHashMap;

public final class OtpService {

    private static final int OTP_LENGTH = 6;
    private static final int OTP_EXPIRY_SECONDS = 300;
    private static final int MAX_ATTEMPTS = 3;
    private static final SecureRandom RANDOM = new SecureRandom();

    record OtpRecord(String otp, Instant expiresAt, int attempts) {
        OtpRecord withAttempt() {
            return new OtpRecord(otp, expiresAt, attempts + 1);
        }
    }

    private final ConcurrentHashMap store = new ConcurrentHashMap<>();
    private final TelnyxClient client;

    public OtpService() {
        this.client = TelnyxOkHttpClient.fromEnv();
    }

    public String generateOtp() {
        StringBuilder sb = new StringBuilder(OTP_LENGTH);
        for (int i = 0; i < OTP_LENGTH; i++) {
            sb.append(RANDOM.nextInt(10));
        }
        return sb.toString();
    }

    public String sendOtp(String phoneNumber) {
        String otp = generateOtp();
        store.put(phoneNumber, new OtpRecord(
            otp, Instant.now().plusSeconds(OTP_EXPIRY_SECONDS), 0
        ));

        var params = MessageSendParams.builder()
            .from(System.getenv("TELNYX_FROM_NUMBER"))
            .to(phoneNumber)
            .text("Your verification code is: " + otp + ". It expires in 5 minutes.")
            .build();

        var response = client.messages().send(params);
        return response.data().id();
    }

    public boolean verifyOtp(String phoneNumber, String submitted) {
        OtpRecord record = store.get(phoneNumber);
        if (record == null || Instant.now().isAfter(record.expiresAt())) {
            store.remove(phoneNumber);
            return false;
        }
        OtpRecord updated = record.withAttempt();
        store.put(phoneNumber, updated);
        if (updated.attempts() > MAX_ATTEMPTS) {
            store.remove(phoneNumber);
            return false;
        }
        if (MessageDigest.isEqual(
                record.otp().getBytes(), submitted.getBytes())) {
            store.remove(phoneNumber);
            return true;
        }
        return false;
    }

    public static void main(String[] args) {
        OtpService service = new OtpService();
        String msgId = service.sendOtp("+15559876543");
        System.out.println("OTP sent, message ID: " + msgId);
    }
}

.NET

using System;
using System.Collections.Concurrent;
using System.Security.Cryptography;
using Telnyx;

public class OtpService
{
    private const int OtpLength = 6;
    private static readonly TimeSpan OtpExpiry = TimeSpan.FromMinutes(5);
    private const int MaxAttempts = 3;

    private record OtpRecord(string Otp, DateTime ExpiresAt, int Attempts);

    private readonly ConcurrentDictionary _store = new();

    public async Task SendOtpAsync(string phoneNumber)
    {
        var otp = GenerateOtp();
        _store[phoneNumber] = new OtpRecord(otp, DateTime.UtcNow + OtpExpiry, 0);

        TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));
        var service = new MessageService();
        var response = await service.SendAsync(new MessageSendOptions
        {
            From = Environment.GetEnvironmentVariable("TELNYX_FROM_NUMBER"),
            To = phoneNumber,
            Text = $"Your verification code is: {otp}. It expires in 5 minutes."
        });

        return response.Data.Id;
    }

    public bool VerifyOtp(string phoneNumber, string submitted)
    {
        if (!_store.TryGetValue(phoneNumber, out var record))
            return false;

        if (DateTime.UtcNow > record.ExpiresAt)
        {
            _store.TryRemove(phoneNumber, out _);
            return false;
        }

        var updated = record with { Attempts = record.Attempts + 1 };
        _store[phoneNumber] = updated;

        if (updated.Attempts > MaxAttempts)
        {
            _store.TryRemove(phoneNumber, out _);
            return false;
        }

        if (CryptographicOperations.FixedTimeEquals(
            System.Text.Encoding.UTF8.GetBytes(record.Otp),
            System.Text.Encoding.UTF8.GetBytes(submitted)))
        {
            _store.TryRemove(phoneNumber, out _);
            return true;
        }

        return false;
    }

    private static string GenerateOtp()
    {
        var bytes = RandomNumberGenerator.GetBytes(OtpLength);
        return string.Concat(Array.ConvertAll(bytes, b => (b % 10).ToString()));
    }
}

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

// In production, use Redis or a database
$otpStore = [];

define('OTP_LENGTH', 6);
define('OTP_EXPIRY_SECONDS', 300);
define('MAX_ATTEMPTS', 3);

function generateOtp(): string
{
    $otp = '';
    for ($i = 0; $i < OTP_LENGTH; $i++) {
        $otp .= random_int(0, 9);
    }
    return $otp;
}

function sendOtp(string $phoneNumber): array
{
    global $otpStore;
    $otp = generateOtp();

    $otpStore[$phoneNumber] = [
        'otp' => $otp,
        'expires_at' => time() + OTP_EXPIRY_SECONDS,
        'attempts' => 0,
    ];

    $response = \Telnyx\Message::Create([
        'from' => getenv('TELNYX_FROM_NUMBER'),
        'to' => $phoneNumber,
        'text' => "Your verification code is: {$otp}. It expires in 5 minutes.",
    ]);

    return ['message_id' => $response->id, 'expires_in' => OTP_EXPIRY_SECONDS];
}

function verifyOtp(string $phoneNumber, string $submitted): bool
{
    global $otpStore;

    if (!isset($otpStore[$phoneNumber])) {
        return false;
    }

    $record = &$otpStore[$phoneNumber];

    if (time() > $record['expires_at']) {
        unset($otpStore[$phoneNumber]);
        return false;
    }

    $record['attempts']++;
    if ($record['attempts'] > MAX_ATTEMPTS) {
        unset($otpStore[$phoneNumber]);
        return false;
    }

    if (hash_equals($record['otp'], $submitted)) {
        unset($otpStore[$phoneNumber]);
        return true;
    }

    return false;
}

// Usage
$result = sendOtp('+15559876543');
echo "OTP sent, message ID: {$result['message_id']}\n";

Security best practices

Never use Math.random(), rand(), or similar non-cryptographic functions for OTP generation. Use:

Language	Secure Function
Python	`secrets.choice()` or `secrets.token_hex()`
Node	`crypto.randomBytes()`
Ruby	`SecureRandom.random_number()`
Go	`crypto/rand.Int()`
Java	`SecureRandom.nextInt()`
.NET	`RandomNumberGenerator.GetBytes()`
PHP	`random_int()`

OTPs should expire after a short window (3-5 minutes is typical). Never allow OTPs to be valid indefinitely.

Store the expiry timestamp alongside the OTP
Check expiry before validating
Delete expired OTPs proactively

Allow a maximum of 3 verification attempts per OTP. After exceeding the limit, invalidate the OTP and require the user to request a new one. This prevents brute-force attacks on short numeric codes. Always use constant-time string comparison when verifying OTPs to prevent timing attacks:

Language	Function
Python	`secrets.compare_digest()`
Node	`crypto.timingSafeEqual()`
Go	`subtle.ConstantTimeCompare()`
Java	`MessageDigest.isEqual()`
.NET	`CryptographicOperations.FixedTimeEquals()`
PHP	`hash_equals()`

Prevent abuse by limiting how frequently a user can request new OTPs:

Per phone number: Maximum 1 OTP request per 60 seconds
Per IP address: Maximum 10 OTP requests per hour
Per account: Maximum 5 OTP requests per hour

Return the same “OTP sent” response regardless of whether the number exists in your system to prevent enumeration attacks. Use numeric-only OTPs (e.g., 847291) rather than alphanumeric codes. They are:

Easier for users to type on mobile
Compatible with SMS autofill on iOS and Android
Sufficient security when combined with attempt limits and expiry

A 6-digit code has 1,000,000 possible values — with a 3-attempt limit, the probability of guessing correctly is 0.0003%. iOS and Android can automatically detect and fill OTP codes from SMS. To enable this: Android (SMS Retriever API): Include your app’s hash at the end of the message:

Your verification code is: 847291

FA+9qCX9VSu

iOS: iOS automatically detects codes from messages containing “code” or “passcode.” No special formatting needed, but keeping the OTP on its own line helps.

When to use the Verify API instead

The Telnyx Verify API is a better choice when:

Requirement	DIY (this guide)	Verify API
OTP generation & storage	You build it	Handled for you
Retry logic	You build it	Built-in
Rate limiting	You build it	Built-in
Multi-channel (SMS + Voice + WhatsApp)	Separate implementation	Single API
Delivery status tracking	Manual webhook handling	Built-in
Compliance & audit logging	You build it	Built-in

Use this guide’s DIY approach only when you need full control over the OTP flow, custom message templates, or integration with existing verification systems.

Managed OTP verification with built-in rate limiting and multi-channel support. Get started with the Verify API in minutes. Understand message throughput limits for OTP delivery. Get started with the Telnyx Messaging API.

Appointment Reminders

Source: https://developers.telnyx.com/docs/messaging/messages/appointment-reminder.md

Reduce no-shows by sending automated SMS appointment reminders with the Telnyx Messaging API. This guide covers scheduling strategies, message templates, opt-out handling, and timing best practices.

How it works

Send an appointment reminder

Python

import os
from datetime import datetime

from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

def send_reminder(to: str, patient_name: str, appointment_time: datetime, location: str):
    """Send an appointment reminder SMS."""
    formatted_time = appointment_time.strftime("%A, %B %d at %I:%M %p")

    response = client.messages.send(
        from_=os.environ.get("TELNYX_FROM_NUMBER"),
        to=to,
        text=(
            f"Hi {patient_name}, this is a reminder for your appointment "
            f"on {formatted_time} at {location}. "
            f"Reply CONFIRM to confirm or CANCEL to cancel."
        ),
    )
    return response.data

# Example
send_reminder(
    to="+15559876543",
    patient_name="Jane",
    appointment_time=datetime(2026, 3, 15, 14, 30),
    location="123 Main St, Suite 200",
)

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

async function sendReminder(to, patientName, appointmentTime, location) {
  const formatted = appointmentTime.toLocaleDateString('en-US', {
    weekday: 'long', month: 'long', day: 'numeric',
    hour: 'numeric', minute: '2-digit',
  });

  const response = await client.messages.send({
    from: process.env.TELNYX_FROM_NUMBER,
    to,
    text: `Hi ${patientName}, this is a reminder for your appointment on ${formatted} at ${location}. Reply CONFIRM to confirm or CANCEL to cancel.`,
  });

  return response.data;
}

// Example
await sendReminder(
  '+15559876543',
  'Jane',
  new Date('2026-03-15T14:30:00'),
  '123 Main St, Suite 200'
);

Ruby

require "telnyx"

Telnyx.api_key = ENV["TELNYX_API_KEY"]

def send_reminder(to:, patient_name:, appointment_time:, location:)
  formatted = appointment_time.strftime("%A, %B %d at %I:%M %p")

  Telnyx::Message.create(
    from: ENV["TELNYX_FROM_NUMBER"],
    to: to,
    text: "Hi #{patient_name}, this is a reminder for your appointment " \
          "on #{formatted} at #{location}. " \
          "Reply CONFIRM to confirm or CANCEL to cancel."
  )
end

# Example
send_reminder(
  to: "+15559876543",
  patient_name: "Jane",
  appointment_time: Time.new(2026, 3, 15, 14, 30),
  location: "123 Main St, Suite 200"
)

package main

import (
  "context"
  "fmt"
  "os"
  "time"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func sendReminder(client *telnyx.Client, to, name, location string, apptTime time.Time) error {
  formatted := apptTime.Format("Monday, January 2 at 3:04 PM")

  _, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From: os.Getenv("TELNYX_FROM_NUMBER"),
    To:   to,
    Text: fmt.Sprintf(
      "Hi %s, this is a reminder for your appointment on %s at %s. "+
        "Reply CONFIRM to confirm or CANCEL to cancel.",
      name, formatted, location,
    ),
  })
  return err
}

func main() {
  client := telnyx.NewClient(option.WithAPIKey(os.Getenv("TELNYX_API_KEY")))
  appt := time.Date(2026, 3, 15, 14, 30, 0, 0, time.Local)
  err := sendReminder(client, "+15559876543", "Jane", "123 Main St, Suite 200", appt)
  if err != nil {
    panic(err)
  }
  fmt.Println("Reminder sent!")
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public final class AppointmentReminder {
    private static final DateTimeFormatter FORMATTER =
        DateTimeFormatter.ofPattern("EEEE, MMMM d 'at' h:mm a");

    public static String sendReminder(String to, String name,
                                       LocalDateTime apptTime, String location) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();
        String formatted = apptTime.format(FORMATTER);

        var params = MessageSendParams.builder()
            .from(System.getenv("TELNYX_FROM_NUMBER"))
            .to(to)
            .text(String.format(
                "Hi %s, this is a reminder for your appointment on %s at %s. " +
                "Reply CONFIRM to confirm or CANCEL to cancel.",
                name, formatted, location))
            .build();

        var response = client.messages().send(params);
        return response.data().id();
    }

    public static void main(String[] args) {
        sendReminder("+15559876543", "Jane",
            LocalDateTime.of(2026, 3, 15, 14, 30), "123 Main St, Suite 200");
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

async Task SendReminderAsync(string to, string name, DateTime apptTime, string location)
{
    var formatted = apptTime.ToString("dddd, MMMM d 'at' h:mm tt");

    var service = new MessageService();
    await service.SendAsync(new MessageSendOptions
    {
        From = Environment.GetEnvironmentVariable("TELNYX_FROM_NUMBER"),
        To = to,
        Text = $"Hi {name}, this is a reminder for your appointment on {formatted} at {location}. " +
               "Reply CONFIRM to confirm or CANCEL to cancel."
    });
}

await SendReminderAsync("+15559876543", "Jane",
    new DateTime(2026, 3, 15, 14, 30, 0), "123 Main St, Suite 200");

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

function sendReminder(string $to, string $name, DateTime $apptTime, string $location): void
{
    $formatted = $apptTime->format('l, F j \a\t g:i A');

    \Telnyx\Message::Create([
        'from' => getenv('TELNYX_FROM_NUMBER'),
        'to' => $to,
        'text' => "Hi {$name}, this is a reminder for your appointment "
            . "on {$formatted} at {$location}. "
            . "Reply CONFIRM to confirm or CANCEL to cancel.",
    ]);
}

sendReminder('+15559876543', 'Jane',
    new DateTime('2026-03-15 14:30:00'), '123 Main St, Suite 200');

Scheduling strategies

Choose a scheduling approach based on your application’s requirements: The simplest approach — use the Telnyx API’s built-in scheduled messaging feature. No external scheduler needed.

Python

from datetime import datetime, timedelta, timezone

# Schedule reminder 24 hours before appointment
reminder_time = appointment_time - timedelta(hours=24)

response = client.messages.send(
    from_=os.environ.get("TELNYX_FROM_NUMBER"),
    to="+15559876543",
    text="Reminder: You have an appointment tomorrow at 2:30 PM.",
    send_at=reminder_time.astimezone(timezone.utc).isoformat(),
)

Pros: No infrastructure needed, simple API call Cons: Limited to single scheduled time per API call, max 7 days in advance Run a periodic job (e.g., every hour) that queries your database for upcoming appointments and sends reminders.

Python

# Example cron job (runs hourly)
from datetime import datetime, timedelta

def send_pending_reminders():
    """Find appointments in the next 24-25 hours and send reminders."""
    now = datetime.now()
    window_start = now + timedelta(hours=23)
    window_end = now + timedelta(hours=25)

    # Query your database
    appointments = db.query(
        "SELECT * FROM appointments "
        "WHERE start_time BETWEEN %s AND %s "
        "AND reminder_sent = FALSE",
        (window_start, window_end)
    )

    for appt in appointments:
        send_reminder(
            to=appt.phone,
            patient_name=appt.name,
            appointment_time=appt.start_time,
            location=appt.location,
        )
        db.execute(
            "UPDATE appointments SET reminder_sent = TRUE WHERE id = %s",
            (appt.id,)
        )

Pros: Full control, supports multiple reminder windows, database-driven Cons: Requires job scheduler infrastructure (cron, Celery, Bull, etc.) Schedule individual reminder jobs when appointments are created using a task queue like Celery (Python), Bull (Node), or Sidekiq (Ruby).

Python

from celery import Celery
from datetime import timedelta

celery_app = Celery('reminders', broker='redis://localhost:6379')

@celery_app.task
def send_scheduled_reminder(phone, name, time_str, location):
    appointment_time = datetime.fromisoformat(time_str)
    send_reminder(to=phone, patient_name=name,
                  appointment_time=appointment_time, location=location)

# When appointment is booked, schedule the reminder
def on_appointment_created(appointment):
    reminder_time = appointment.start_time - timedelta(hours=24)
    send_scheduled_reminder.apply_async(
        args=[appointment.phone, appointment.name,
              appointment.start_time.isoformat(), appointment.location],
        eta=reminder_time,
    )

Pros: Precise timing, scalable, handles cancellations Cons: Requires message queue infrastructure (Redis, RabbitMQ)

Handle replies (confirm / cancel)

Set up a webhook to receive replies and update appointment status:

Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/messaging", methods=["POST"])
def handle_webhook():
    data = request.json["data"]

    if data["event_type"] != "message.received":
        return jsonify({"status": "ignored"}), 200

    payload = data["payload"]
    from_number = payload["from"]["phone_number"]
    text = payload["text"].strip().upper()

    if text == "CONFIRM":
        # Update appointment status in your database
        db.execute(
            "UPDATE appointments SET status = 'confirmed' WHERE phone = %s "
            "AND start_time > NOW()",
            (from_number,)
        )
        # Send confirmation
        client.messages.send(
            from_=os.environ.get("TELNYX_FROM_NUMBER"),
            to=from_number,
            text="Your appointment has been confirmed. See you then!",
        )

    elif text == "CANCEL":
        db.execute(
            "UPDATE appointments SET status = 'cancelled' WHERE phone = %s "
            "AND start_time > NOW()",
            (from_number,)
        )
        client.messages.send(
            from_=os.environ.get("TELNYX_FROM_NUMBER"),
            to=from_number,
            text="Your appointment has been cancelled. "
                 "Please call us to reschedule.",
        )

    return jsonify({"status": "ok"}), 200

Node

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/messaging', async (req, res) => {
  const { data } = req.body;

  if (data.event_type !== 'message.received') {
    return res.json({ status: 'ignored' });
  }

  const fromNumber = data.payload.from.phone_number;
  const text = data.payload.text.trim().toUpperCase();

  if (text === 'CONFIRM') {
    await db.query(
      `UPDATE appointments SET status = 'confirmed'
       WHERE phone = $1 AND start_time > NOW()`,
      [fromNumber]
    );
    await client.messages.send({
      from: process.env.TELNYX_FROM_NUMBER,
      to: fromNumber,
      text: 'Your appointment has been confirmed. See you then!',
    });
  } else if (text === 'CANCEL') {
    await db.query(
      `UPDATE appointments SET status = 'cancelled'
       WHERE phone = $1 AND start_time > NOW()`,
      [fromNumber]
    );
    await client.messages.send({
      from: process.env.TELNYX_FROM_NUMBER,
      to: fromNumber,
      text: 'Your appointment has been cancelled. Please call us to reschedule.',
    });
  }

  res.json({ status: 'ok' });
});

Opt-out handling

You must honor opt-out requests. Telnyx automatically handles STOP/UNSTOP keywords for 10DLC and Toll-Free numbers, but you should also track opt-outs in your application. Telnyx automatically handles standard opt-out keywords (STOP, UNSUBSCRIBE, CANCEL, END, QUIT) for US long codes and toll-free numbers. When a user texts STOP:

Telnyx sends an automatic reply confirming the opt-out
Future messages to that number are blocked at the carrier level
You receive a message.received webhook with the STOP keyword

See Advanced Opt-In/Out for customization options. In addition to Telnyx’s automatic handling, track opt-outs in your database to prevent scheduling reminders for opted-out users:

def handle_opt_out(phone_number: str):
    """Mark a phone number as opted out."""
    db.execute(
        "UPDATE patients SET sms_opted_out = TRUE WHERE phone = %s",
        (phone_number,)
    )
    # Cancel any pending reminders
    db.execute(
        "DELETE FROM scheduled_reminders WHERE phone = %s AND sent = FALSE",
        (phone_number,)
    )

def can_send_reminder(phone_number: str) -> bool:
    """Check if we can send a reminder to this number."""
    result = db.query(
        "SELECT sms_opted_out FROM patients WHERE phone = %s",
        (phone_number,)
    )
    return result and not result.sms_opted_out

Timing best practices

24 hours before: Primary reminder — enough time to cancel/reschedule
2-3 hours before: Final reminder for same-day appointments
Avoid late night/early morning: Only send between 9 AM and 8 PM in the recipient’s local time zone For high-value appointments (medical, legal), send two reminders:

48 or 24 hours before — gives time to reschedule
2-3 hours before — final confirmation

For routine appointments (salon, auto service), a single reminder 24 hours before is usually sufficient. Always calculate reminder times in the recipient’s local time zone. Sending a reminder at 3 AM is worse than not sending one at all.

from zoneinfo import ZoneInfo

# Store patient timezone in your database
patient_tz = ZoneInfo(patient.timezone)  # e.g., "America/New_York"
local_time = reminder_time.astimezone(patient_tz)

# Only send between 9 AM and 8 PM local time
if 9 <= local_time.hour < 20:
    send_reminder(...)
else:
    # Reschedule to 9 AM local time
    next_9am = local_time.replace(hour=9, minute=0)
    if next_9am < local_time:
        next_9am += timedelta(days=1)
    schedule_reminder_at(next_9am, ...)

SMS has character limits. Keep reminders under 160 characters (1 segment) when possible to minimize costs. Include only essential info:

Patient name
Date and time
Location (short form)
Reply instructions

Message templates

Healthcare:

Hi {name}, reminder: your appointment with Dr. {provider} is on {date} at {time}.
Reply CONFIRM or CANCEL. Call {phone} to reschedule.

Dental:

{name}, your dental cleaning at {practice} is tomorrow at {time}.
Please arrive 10 min early. Reply C to confirm, X to cancel.

Salon / Spa:

Hi {name}! Your {service} appointment is {date} at {time}.
Reply YES to confirm or call {phone} to reschedule.

Auto Service:

{name}, your vehicle service at {shop} is scheduled for {date} at {time}.
Reply OK to confirm.

Legal / Financial:

Reminder: Your meeting with {advisor} is on {date} at {time} at {location}.
Please bring required documents. Reply CONFIRM to confirm.

Use the Telnyx API to schedule messages for future delivery. Customize opt-in/out behavior for your messaging profile. Receive inbound messages and delivery status updates. Understand throughput limits for bulk reminder sending.

Send & Receive MMS

Source: https://developers.telnyx.com/docs/messaging/messages/send-receive-mms.md

Send multimedia messages (images, video, audio, vCards) via the Telnyx API and process inbound MMS attachments from webhooks.

Prerequisites

A Telnyx account with API key
A messaging profile with a phone number enabled for MMS
A webhook endpoint to receive inbound messages (see ngrok setup)

MMS is supported on US/Canada long codes, toll-free, and short codes. For media format details and carrier limits, see MMS Media & Transcoding.

Send an MMS

Include media_urls in your message request. You can send up to 10 media files per message.

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"

message = telnyx.Message.create(
    from_="+18005550100",
    to="+18005550101",
    text="Here's the photo you requested!",
    media_urls=["https://example.com/image.jpg"],
    messaging_profile_id="YOUR_MESSAGING_PROFILE_ID"
)

print(f"Message ID: {message.id}")
print(f"Status: {message.to[0]['status']}")

Node

const telnyx = require("telnyx")("YOUR_API_KEY");

const message = await telnyx.messages.create({
  from: "+18005550100",
  to: "+18005550101",
  text: "Here's the photo you requested!",
  media_urls: ["https://example.com/image.jpg"],
  messaging_profile_id: "YOUR_MESSAGING_PROFILE_ID",
});

console.log(`Message ID: ${message.data.id}`);
console.log(`Status: ${message.data.to[0].status}`);

Ruby

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

message = Telnyx::Message.create(
  from: "+18005550100",
  to: "+18005550101",
  text: "Here's the photo you requested!",
  media_urls: ["https://example.com/image.jpg"],
  messaging_profile_id: "YOUR_MESSAGING_PROFILE_ID"
)

puts "Message ID: #{message.id}"
puts "Status: #{message.to[0]['status']}"

Java

import com.telnyx.sdk.*;
import com.telnyx.sdk.api.MessagesApi;
import com.telnyx.sdk.model.*;
import java.util.Arrays;

ApiClient client = Configuration.getDefaultApiClient();
client.setBearerToken("YOUR_API_KEY");

MessagesApi api = new MessagesApi(client);
CreateMessageRequest req = new CreateMessageRequest()
    .from("+18005550100")
    .to("+18005550101")
    .text("Here's the photo you requested!")
    .mediaUrls(Arrays.asList("https://example.com/image.jpg"))
    .messagingProfileId("YOUR_MESSAGING_PROFILE_ID");

MessageResponse resp = api.createMessage(req);
System.out.println("Message ID: " + resp.getData().getId());

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey("YOUR_API_KEY");

var service = new MessagingSenderIdService();
var options = new NewMessage
{
    From = "+18005550100",
    To = "+18005550101",
    Text = "Here's the photo you requested!",
    MediaUrls = new List { "https://example.com/image.jpg" },
    MessagingProfileId = "YOUR_MESSAGING_PROFILE_ID"
};

var message = service.Create(options);
Console.WriteLine($"Message ID: {message.Id}");

PHP

$telnyx = new \Telnyx\Telnyx("YOUR_API_KEY");

$message = \Telnyx\Message::create([
    "from" => "+18005550100",
    "to" => "+18005550101",
    "text" => "Here's the photo you requested!",
    "media_urls" => ["https://example.com/image.jpg"],
    "messaging_profile_id" => "YOUR_MESSAGING_PROFILE_ID"
]);

echo "Message ID: " . $message->id . "\n";

package main

import (
    "context"
    "fmt"
    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient("YOUR_API_KEY")

    message, err := client.Messages.Create(context.Background(), &telnyx.MessageParams{
        From:                "+18005550100",
        To:                  "+18005550101",
        Text:                "Here's the photo you requested!",
        MediaURLs:           []string{"https://example.com/image.jpg"},
        MessagingProfileID:  "YOUR_MESSAGING_PROFILE_ID",
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Message ID: %s\n", message.ID)
}

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+18005550100",
    "to": "+18005550101",
    "text": "Here'\''s the photo you requested!",
    "media_urls": ["https://example.com/image.jpg"],
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
  }'

Send multiple media files

Include multiple URLs in media_urls. Total payload must stay under carrier limits.

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+18005550100",
    "to": "+18005550101",
    "text": "Product photos attached",
    "media_urls": [
      "https://example.com/photo1.jpg",
      "https://example.com/photo2.jpg",
      "https://example.com/photo3.jpg"
    ],
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
  }'

Media URLs must be publicly accessible. Telnyx downloads the media at send time — if the URL requires authentication or returns an error, the message will fail.

Receive an MMS

Inbound MMS messages arrive as webhooks to your messaging profile’s webhook URL. The media array contains attachment details.

Webhook payload

{
  "data": {
    "event_type": "message.received",
    "payload": {
      "from": { "phone_number": "+18005550101" },
      "to": [{ "phone_number": "+18005550100" }],
      "text": "Check out this photo!",
      "media": [
        {
          "url": "https://media.telnyx.com/abc123/image.jpg",
          "content_type": "image/jpeg",
          "size": 245760
        }
      ]
    }
  }
}

Media URLs are ephemeral. Telnyx-hosted media links expire. Download and store attachments in your own storage immediately upon receipt.

Process inbound MMS

Python

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

TELNYX_API_KEY = os.getenv("TELNYX_API_KEY")
MEDIA_DIR = "./received_media"
os.makedirs(MEDIA_DIR, exist_ok=True)

@app.route("/webhooks", methods=["POST"])
def webhooks():
    body = request.json
    event_type = body["data"]["event_type"]

    if event_type != "message.received":
        return jsonify({"status": "ignored"}), 200

    payload = body["data"]["payload"]
    from_number = payload["from"]["phone_number"]
    text = payload.get("text", "")
    media = payload.get("media", [])

    print(f"From: {from_number} | Text: {text} | Attachments: {len(media)}")

    # Download each attachment
    saved_files = []
    for item in media:
        resp = requests.get(item["url"])
        ext = item["content_type"].split("/")[-1]
        filename = f"{MEDIA_DIR}/{from_number}_{len(saved_files)}.{ext}"
        with open(filename, "wb") as f:
            f.write(resp.content)
        saved_files.append(filename)
        print(f"  Saved: {filename} ({item['size']} bytes)")

    return jsonify({"status": "ok", "files": len(saved_files)}), 200

if __name__ == "__main__":
    app.run(port=8000)

Node

const express = require("express");
const axios = require("axios");
const fs = require("fs");
const path = require("path");

const app = express();
app.use(express.json());

const MEDIA_DIR = "./received_media";
fs.mkdirSync(MEDIA_DIR, { recursive: true });

app.post("/webhooks", async (req, res) => {
  const { event_type, payload } = req.body.data;

  if (event_type !== "message.received") {
    return res.json({ status: "ignored" });
  }

  const from = payload.from.phone_number;
  const text = payload.text || "";
  const media = payload.media || [];

  console.log(`From: ${from} | Text: ${text} | Attachments: ${media.length}`);

  for (let i = 0; i < media.length; i++) {
    const resp = await axios.get(media[i].url, { responseType: "arraybuffer" });
    const ext = media[i].content_type.split("/").pop();
    const filename = path.join(MEDIA_DIR, `${from}_${i}.${ext}`);
    fs.writeFileSync(filename, resp.data);
    console.log(`  Saved: ${filename} (${media[i].size} bytes)`);
  }

  res.json({ status: "ok", files: media.length });
});

app.listen(8000, () => console.log("Listening on port 8000"));

Ruby

require "sinatra"
require "net/http"
require "json"
require "fileutils"

MEDIA_DIR = "./received_media"
FileUtils.mkdir_p(MEDIA_DIR)

post "/webhooks" do
  body = JSON.parse(request.body.read)
  event_type = body.dig("data", "event_type")

  return { status: "ignored" }.to_json unless event_type == "message.received"

  payload = body.dig("data", "payload")
  from = payload.dig("from", "phone_number")
  media = payload.fetch("media", [])

  puts "From: #{from} | Attachments: #{media.length}"

  media.each_with_index do |item, i|
    uri = URI(item["url"])
    resp = Net::HTTP.get(uri)
    ext = item["content_type"].split("/").last
    filename = "#{MEDIA_DIR}/#{from}_#{i}.#{ext}"
    File.binwrite(filename, resp)
    puts "  Saved: #{filename}"
  end

  { status: "ok" }.to_json
end

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "path/filepath"
    "strings"
)

const mediaDir = "./received_media"

type Webhook struct {
    Data struct {
        EventType string `json:"event_type"`
        Payload   struct {
            From  struct{ PhoneNumber string `json:"phone_number"` } `json:"from"`
            Text  string `json:"text"`
            Media []struct {
                URL         string `json:"url"`
                ContentType string `json:"content_type"`
                Size        int    `json:"size"`
            } `json:"media"`
        } `json:"payload"`
    } `json:"data"`
}

func handler(w http.ResponseWriter, r *http.Request) {
    var wh Webhook
    json.NewDecoder(r.Body).Decode(&wh)

    if wh.Data.EventType != "message.received" {
        json.NewEncoder(w).Encode(map[string]string{"status": "ignored"})
        return
    }

    from := wh.Data.Payload.From.PhoneNumber
    fmt.Printf("From: %s | Attachments: %d\n", from, len(wh.Data.Payload.Media))

    for i, item := range wh.Data.Payload.Media {
        resp, _ := http.Get(item.URL)
        defer resp.Body.Close()
        ext := strings.Split(item.ContentType, "/")[1]
        filename := filepath.Join(mediaDir, fmt.Sprintf("%s_%d.%s", from, i, ext))
        f, _ := os.Create(filename)
        io.Copy(f, resp.Body)
        f.Close()
        fmt.Printf("  Saved: %s\n", filename)
    }

    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

func main() {
    os.MkdirAll(mediaDir, 0755)
    http.HandleFunc("/webhooks", handler)
    fmt.Println("Listening on port 8000")
    http.ListenAndServe(":8000", nil)
}

curl

# Simulate receiving — inspect your webhook logs
# The webhook POST body contains media URLs you can download:

curl -o attachment.jpg "https://media.telnyx.com/abc123/image.jpg"

Reply with media

Echo received media back to the sender, or reply with different media:

Python

import telnyx
import os

telnyx.api_key = os.getenv("TELNYX_API_KEY")

def handle_mms_webhook(payload):
    """Reply to inbound MMS with the same media + a text response."""
    from_number = payload["from"]["phone_number"]
    to_number = payload["to"][0]["phone_number"]
    media = payload.get("media", [])

    # Reply with the same media echoed back
    media_urls = [item["url"] for item in media]

    reply = telnyx.Message.create(
        from_=to_number,
        to=from_number,
        text=f"Thanks! Received {len(media)} attachment(s).",
        media_urls=media_urls if media_urls else None,
        messaging_profile_id="YOUR_MESSAGING_PROFILE_ID"
    )

    print(f"Reply sent: {reply.id}")

Node

const telnyx = require("telnyx")(process.env.TELNYX_API_KEY);

async function handleMmsWebhook(payload) {
  const from = payload.from.phone_number;
  const to = payload.to[0].phone_number;
  const media = payload.media || [];
  const mediaUrls = media.map((m) => m.url);

  const reply = await telnyx.messages.create({
    from: to,
    to: from,
    text: `Thanks! Received ${media.length} attachment(s).`,
    media_urls: mediaUrls.length ? mediaUrls : undefined,
    messaging_profile_id: "YOUR_MESSAGING_PROFILE_ID",
  });

  console.log(`Reply sent: ${reply.data.id}`);
}

Supported media types

Type	Formats	Max Size
Images	JPEG, PNG, GIF, BMP, WebP	1 MB (carrier-dependent)
Video	MP4, 3GP	600 KB (carrier-dependent)
Audio	MP3, AMR, WAV, OGG	600 KB (carrier-dependent)
Files	vCard (.vcf), PDF	600 KB

Telnyx automatically transcodes oversized media when possible. For details on carrier-specific limits and transcoding behavior, see MMS Media & Transcoding.

Store media externally (optional)

For production use, store received media in your own cloud storage rather than relying on ephemeral Telnyx URLs.

Python

import boto3
import requests
from urllib.parse import urlparse

s3 = boto3.client("s3")
BUCKET = "your-mms-bucket"

def save_to_s3(media_url, from_number, index):
    resp = requests.get(media_url)
    content_type = resp.headers.get("content-type", "application/octet-stream")
    ext = content_type.split("/")[-1]
    key = f"mms/{from_number}/{index}.{ext}"

    s3.put_object(
        Bucket=BUCKET,
        Key=key,
        Body=resp.content,
        ContentType=content_type
    )
    return f"s3://{BUCKET}/{key}"

Python

from google.cloud import storage
import requests

gcs = storage.Client()
bucket = gcs.bucket("your-mms-bucket")

def save_to_gcs(media_url, from_number, index):
    resp = requests.get(media_url)
    content_type = resp.headers.get("content-type", "application/octet-stream")
    ext = content_type.split("/")[-1]

    blob = bucket.blob(f"mms/{from_number}/{index}.{ext}")
    blob.upload_from_string(resp.content, content_type=content_type)
    return blob.public_url

Troubleshooting

Cause: The media URL was unreachable, or the recipient’s carrier doesn’t support MMS. Fix:

Verify the media URL is publicly accessible (no auth required)
Check message detail records for error details
Confirm the recipient’s number supports MMS

Cause: Total media payload exceeds carrier limits. Fix:

Compress images before sending (aim for < 600 KB each)
Enable automatic transcoding (on by default)
See carrier size limits

Cause: Telnyx media URLs are temporary. You waited too long to download. Fix: Download media immediately in your webhook handler. Store in your own S3/GCS bucket. Cause: Some number types (e.g., alphanumeric sender IDs) don’t support MMS. Fix: Use a US/Canada long code, toll-free, or short code with MMS enabled in your messaging profile.

Next steps

Carrier limits, supported formats, and automatic transcoding. Set up and secure your webhook endpoint. SMS sending guide with all SDK examples. Send MMS to multiple recipients.

Zapier Integration

Source: https://developers.telnyx.com/docs/messaging/messages/zapier-integration.md

Connect Telnyx SMS messaging to 7,000+ apps using Zapier — no code required. Build automated workflows that send messages, forward inbound SMS, and respond to triggers from other services. When to use Zapier vs. the API: Zapier is ideal for simple automations, prototyping, and connecting to third-party services without code. For high-volume messaging, complex logic, or production-critical workflows, use the Telnyx Messaging API directly.

Prerequisites

A Telnyx account with a messaging-enabled phone number
A Messaging Profile configured with a webhook URL
A Zapier account (free tier available)
Your Telnyx v2 API Key

Connect Telnyx to Zapier

Go to the Telnyx Zapier integration page and click Connect. Enter your Telnyx v2 API key when prompted. This gives Zapier permission to send and receive messages on your behalf. After authenticating, Zapier displays all phone numbers on your Telnyx account. Select the number you want to use for sending. Zapier does not support selecting a messaging profile directly — it lists individual numbers from your account. The number you choose must be assigned to a messaging profile with a webhook URL configured for inbound triggers to work.

Available triggers and actions

Type	Name	Description
Trigger	Receive a Message	Fires when an SMS/MMS is received on your Telnyx number
Action	Send SMS	Sends an SMS message from your Telnyx number

Example workflows

Send SMS alerts from any app

Connect any Zapier trigger to Telnyx SMS to send notifications: Popular combinations:

Google Sheets → new row → send SMS (e.g., new lead notification)
Shopify → new order → send SMS confirmation
Google Calendar → event starting → send SMS reminder
Stripe → payment received → send SMS receipt
Typeform → new response → send SMS follow-up

Setup:

Create a new Zap and select your trigger app (e.g., Google Sheets)
Configure the trigger event (e.g., “New Spreadsheet Row”)
Add Telnyx as the action and select Send SMS
Map fields from the trigger into the message:
- Source Number: Select a Telnyx number from the dropdown — this is a fixed number from your account, not a mapped field from the trigger
- Destination Number: Use a field from the trigger (e.g., a phone number column from Google Sheets) or enter a fixed number
- Message Content: Compose your message using trigger data
Test and turn on the Zap

Forward inbound SMS to your phone

Route messages received on your Telnyx number to your personal phone — useful for monitoring business numbers. Setup:

Create a new Zap with Telnyx → Receive a Message as the trigger
Add Telnyx → Send SMS as the action
Configure the action:
- Source Number: Your Telnyx number
- Destination Number: Your personal number
- Message Content: Use trigger fields:
  FWD FROM: {{From Phone Number}} BODY: {{Text}}
Test and turn on the Zap

You can also forward to email, Slack, or any other Zapier-supported app instead of (or in addition to) SMS.

Automatically reply to inbound messages

Set up automatic replies for inbound messages — useful for business hours notices, keyword responses, or acknowledgments. Setup:

Create a new Zap with Telnyx → Receive a Message as the trigger
(Optional) Add a Filter by Zapier step to only reply to certain messages — for example, filter where {{Text}} contains “HOURS” or “INFO”. Note: filtering requires a Zapier paid plan (Professional or higher)
Add Telnyx → Send SMS as the action
Configure the action:
- Source Number: Your Telnyx number
- Destination Number: Use {{From Phone Number}} from the trigger (replies to sender)
- Message Content: Your auto-reply message
Test and turn on the Zap

Be careful with auto-responders — they can create infinite loops if two Telnyx numbers with auto-responders message each other. Use filters to prevent this.

Limitations

Zapier checks for new triggers on a schedule based on your plan:

Zapier Plan	Polling Interval
Free	Every 15 minutes
Starter	Every 15 minutes
Professional	Every 2 minutes
Team / Company	Every 1 minute

This means inbound messages may not trigger actions immediately. For real-time processing, use the Telnyx Messaging API with webhooks directly. The Telnyx Zapier integration supports SMS only. MMS media attachments are not included in the trigger data, and the Send SMS action does not support media_urls. For MMS, use the Messaging API directly. Each Telnyx Send SMS action step uses a single sender number selected from your account. To send from different numbers in the same Zap, add multiple Telnyx action steps — each with a different sender number. The Zapier integration does not provide delivery status (sent, delivered, failed). For delivery tracking, use the API with webhooks or Message Detail Records. Standard Telnyx rate limits apply to messages sent via Zapier. If your Zap sends messages faster than your sender type allows, messages will be queued or rejected.

Troubleshooting

Ensure phone numbers include the country code with + prefix:

✅ +15551234567
❌ 5551234567
❌ (555) 123-4567

Verify your Telnyx number is assigned to the correct messaging profile
Check that the messaging profile has a webhook URL configured
Ensure the Zap is turned on (not paused)
Check Zapier’s task history for errors
On free plans, polling may take up to 15 minutes
Verify your API key is a v2 key from the Telnyx Portal
Ensure the key has not been revoked or expired
Try removing the Telnyx connection in Zapier and re-adding it

Check the error in Zapier’s task history. Common causes:

40333: Spend limit reached — increase your daily spend limit
40318: Queue full — you’re sending too fast for your sender type
40300: Invalid from number — ensure the source number is assigned to a messaging profile in the Telnyx Portal

If two numbers with auto-responders message each other, they create an infinite loop. Fix by:

Adding a Zapier Filter step that checks if the sender is your own number
Using a delay step to rate-limit responses
Checking for duplicate messages within a time window

Use the Telnyx API directly for full messaging control. Real-time message delivery via webhooks (no polling delay). Browse all Telnyx Zapier integrations and templates. Configure the messaging profile used by your Zapier integration.

Vercel Chat SDK

Source: https://developers.telnyx.com/docs/messaging/messages/chat-sdk-adapter.md

@telnyx/chat-sdk-adapter is the official Telnyx adapter for the Vercel Chat SDK — Vercel’s TypeScript framework for building chatbots that work across Slack, Microsoft Teams, Discord, Telegram, WhatsApp, email, and now SMS/MMS through Telnyx. Write bot logic once and route messages through any supported channel. The adapter is maintained by Telnyx at team-telnyx/telnyx-chat-sdk-adapter and listed as a vendor-official adapter on chat-sdk.dev/adapters. When to use this adapter: building an AI- or rules-driven SMS bot inside a Next.js app and wanting the same handler API you already use for other chat platforms. For general-purpose, high-volume messaging outside a Chat SDK app, use the Telnyx Messaging API directly.

Prerequisites

A Telnyx account with a messaging-enabled phone number (E.164 format)
A Messaging Profile with a webhook URL configured
Your Telnyx v2 API key
The Ed25519 Public Key from the messaging profile (for webhook signature verification)
Node.js >=18

Install

pnpm add @telnyx/chat-sdk-adapter chat

Also install a state adapter — @chat-adapter/state-memory for development, @chat-adapter/state-redis for production:

pnpm add @chat-adapter/state-memory

Quick start

import { createTelnyxAdapter } from "@telnyx/chat-sdk-adapter";
import { createMemoryState } from "@chat-adapter/state-memory";
import { Chat } from "chat";

const telnyx = createTelnyxAdapter({
  messagingProfileId: "40017a7b-...", // recommended — see "Dedicated messaging profile"
  // apiKey:      "KEY..."              // or set TELNYX_API_KEY
  // phoneNumber: "+15551234567"        // or set TELNYX_FROM_NUMBER
  // publicKey:   "vFo7Hk..."           // or set TELNYX_PUBLIC_KEY
});

const chat = new Chat({
  userName: "sms-bot",
  adapters: { telnyx },
  state: createMemoryState(),
});

chat.onNewMention(async (thread, message) => {
  await thread.subscribe();
  await thread.post(`Got your text: ${message.text}`);
});

chat.onSubscribedMessage(async (thread, message) => {
  await thread.post(`Reply: ${message.text}`);
});

await chat.initialize();

In your webhook route handler, forward the request to chat.webhooks.telnyx:

// app/api/webhooks/telnyx/route.ts (Next.js App Router)
export async function POST(request: Request) {
  return chat.webhooks.telnyx(request);
}

Point your messaging profile’s webhook URL at https:///api/webhooks/telnyx.

Configuration

Environment variables

Variable	Required	Description
`TELNYX_API_KEY`	Yes	Your v2 API key
`TELNYX_FROM_NUMBER`	Yes	E.164 phone number the bot sends from
`TELNYX_PUBLIC_KEY`	Recommended	Ed25519 public key from the messaging profile. Base64 or hex — auto-detected. If unset, webhook signatures are not verified — never run without it in production.
`BOT_USERNAME`	No	Bot display name. Defaults to `"bot"`.

`TelnyxAdapterConfig`

interface TelnyxAdapterConfig {
  apiKey?: string;
  phoneNumber?: string;            // E.164
  publicKey?: string;              // base64 or hex, auto-detected
  messagingProfileId?: string;     // strongly recommended (see below)
  userName?: string;
  extraTags?: string[];            // merged into outbound `tags` array
  disableAttributionTags?: boolean;
  logger?: Logger;
}

Recommended: Dedicated messaging profile

Create a dedicated Messaging Profile for each bot and pass its ID as messagingProfileId. We recommend prefixing the profile name with [Chat SDK] (for example, [Chat SDK] support-bot-prod) so it’s easy to find in Mission Control and in usage reports. A dedicated profile gives you:

Per-profile usage analytics, so bot traffic is separated from the rest of your account
Per-profile spend limits, which cap bot spend without affecting other workloads
An isolated webhook URL and failover URL
An isolated Ed25519 public key — the one you pass as publicKey belongs to the profile, not the account

Webhook setup

In the Telnyx Mission Control portal, open the messaging profile you created for the bot. Under Inbound Settings, set the Webhook URL to your server’s endpoint (for example, https://bot.example.com/api/webhooks/telnyx). Set Webhook API version to 2. Under Messaging → Security, copy the Public Key for the profile. Pass it as publicKey (or set TELNYX_PUBLIC_KEY). Telnyx shows this key in base64; the adapter accepts it as-is. Assign one or more phone numbers to the profile. The number you set as TELNYX_FROM_NUMBER must belong to this profile. Incoming webhooks are validated against the telnyx-signature-ed25519 and telnyx-timestamp headers. Requests with a timestamp older than 300 seconds, or with an invalid signature, are rejected with 401.

Capabilities

Capability	Supported	Notes
Inbound SMS / MMS	Yes	via Ed25519-verified webhooks
Outbound SMS	Yes	via `POST /v2/messages`
Outbound MMS	Yes	automatic upgrade when a posted message has attachments with public URLs
Rate-limit handling	Yes	`429` responses surface as `AdapterRateLimitError` with `Retry-After`
Structured errors	Yes	Telnyx error codes, titles, and details are parsed into `AuthenticationError` / `NetworkError` messages
Direct messages	Yes	a thread is one pair of phone numbers; `isDM()` returns `true`
Typing indicators	No	no-op; SMS has no typing concept
Reactions	No	SMS has no reactions
Edit / delete	No	SMS messages are final once sent
Message history API	No	Telnyx does not expose a thread-scoped history API — use a persistent Chat SDK state adapter

Thread model

A thread is a pair of E.164 phone numbers. The thread ID format is telnyx::, for example telnyx:+15551234567:+15559876543. openDM(phoneNumber) returns the thread ID for a given recipient so you can post proactively.

Attribution

Outbound messages carry two ecosystem-observability signals:

User-Agent header on every outbound API call: @telnyx/chat-sdk-adapter/ (vercel-chat-sdk).
tags on every outbound message: ["vercel-chat-sdk", "vercel-chat-sdk:"], merged with any user-supplied tags.

These tags appear in Telnyx webhook event payloads (message.sent, message.finalized, message.received) in the data.payload.tags field. User-supplied extraTags are merged after the attribution tags. Set disableAttributionTags: true to opt out; extraTags is unaffected.

const telnyx = createTelnyxAdapter({
  extraTags: ["env:prod", "team:support"],
  // disableAttributionTags: true,
});

Pair with the Telnyx AI SDK provider

Use this adapter alongside @telnyx/ai-sdk-provider — the Telnyx provider for the Vercel AI SDK — to build a full AI-powered SMS agent on Telnyx inference. The Chat SDK handles message I/O; the AI SDK handles LLM, embeddings, and speech. One account, one API key, two packages.

Resources

Spend Limits

Source: https://developers.telnyx.com/docs/messaging/messages/configurable-spend-limits.md

Messaging profiles can be configured with a daily spending limit to prevent unexpected costs from bugs, traffic spikes, or human error. When the limit is reached, outbound messages are rejected until the limit resets at midnight UTC.

Set up spend limits

Enable the daily_spend_limit_enabled flag and set a daily_spend_limit value (in USD) on your messaging profile:

curl

curl -X PATCH https://api.telnyx.com/v2/messaging_profiles/{profile_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "daily_spend_limit_enabled": true,
    "daily_spend_limit": "10.00"
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messaging_profiles.update(
    "your_messaging_profile_id",
    daily_spend_limit_enabled=True,
    daily_spend_limit="10.00",
)

print(f"Spend limit set: ${response.data.daily_spend_limit}")

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const response = await client.messagingProfiles.update(
  'your_messaging_profile_id',
  {
    daily_spend_limit_enabled: true,
    daily_spend_limit: '10.00',
  }
);

console.log(`Spend limit set: $${response.data.daily_spend_limit}`);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messaging_profiles.update(
  "your_messaging_profile_id",
  daily_spend_limit_enabled: true,
  daily_spend_limit: "10.00"
)

puts "Spend limit set: $#{response.data.daily_spend_limit}"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.MessagingProfiles.Update(
    context.TODO(),
    "your_messaging_profile_id",
    telnyx.MessagingProfileUpdateParams{
      DailySpendLimitEnabled: telnyx.Bool(true),
      DailySpendLimit:        telnyx.String("10.00"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Spend limit set: $%s\n", response.Data.DailySpendLimit)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messagingprofiles.MessagingProfileUpdateParams;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var params = MessagingProfileUpdateParams.builder()
            .dailySpendLimitEnabled(true)
            .dailySpendLimit("10.00")
            .build();

        var response = client.messagingProfiles()
            .update("your_messaging_profile_id", params);

        System.out.println("Spend limit set: $" + response.data().dailySpendLimit());
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessagingProfileService();
var response = await service.UpdateAsync(
    "your_messaging_profile_id",
    new MessagingProfileUpdateOptions
    {
        DailySpendLimitEnabled = true,
        DailySpendLimit = "10.00"
    }
);

Console.WriteLine($"Spend limit set: ${response.Data.DailySpendLimit}");

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\MessagingProfile::Update(
    'your_messaging_profile_id',
    [
        'daily_spend_limit_enabled' => true,
        'daily_spend_limit' => '10.00'
    ]
);

echo "Spend limit set: \${$response->daily_spend_limit}\n";

The daily_spend_limit value is a string representing USD (e.g., "0.50", "10.00", "100.00"). It applies per messaging profile — use separate profiles for different budgets.

When the limit is reached

Once spending exceeds the configured limit, Telnyx:

Rejects new messages with HTTP 429 and error code 40333
Sends a webhook to your configured URL
Sends an email notification to your account

Error response

{
  "errors": [
    {
      "code": "40333",
      "title": "Messaging profile spend limit reached",
      "detail": "The daily spend limit configured on this messaging profile has been reached",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/40333"
      }
    }
  ]
}

Webhook payload

{
  "data": {
    "event_type": "messaging-profile.spend-limit-reached",
    "id": "d21a2887-8007-4bb6-bd7d-f2874829918e",
    "occurred_at": "2024-08-20T19:17:08.918+00:00",
    "payload": {
      "configured_limit": "10.00",
      "current_cost": "10.02",
      "profile_id": "be3eb60a-a346-470a-886c-ab4e421711bd"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhook-url"
  }
}

There may be a short delay between reaching the limit and enforcement. A small number of additional messages may be sent during this window, causing current_cost to slightly exceed configured_limit.

Handle the spend limit webhook

Process the webhook to alert your team and gracefully handle the blocked state:

Python

from flask import Flask, request, jsonify
import logging

app = Flask(__name__)
logger = logging.getLogger(__name__)

@app.route("/webhooks/messaging", methods=["POST"])
def handle_webhook():
    data = request.json["data"]

    if data["event_type"] == "messaging-profile.spend-limit-reached":
        payload = data["payload"]
        logger.warning(
            "Spend limit reached! Profile: %s, Limit: $%s, Current: $%s",
            payload["profile_id"],
            payload["configured_limit"],
            payload["current_cost"],
        )

        # Alert your team (Slack, PagerDuty, email, etc.)
        alert_team(
            title="SMS Spend Limit Reached",
            message=f"Profile {payload['profile_id']} hit ${payload['configured_limit']} limit. "
                    f"Current spend: ${payload['current_cost']}. "
                    f"Messages are being rejected.",
        )

        # Optionally: queue messages for retry after midnight UTC
        # or switch to a backup profile

    return jsonify({"status": "ok"}), 200

Node

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/messaging', (req, res) => {
  const { data } = req.body;

  if (data.event_type === 'messaging-profile.spend-limit-reached') {
    const { profile_id, configured_limit, current_cost } = data.payload;

    console.warn(
      `Spend limit reached! Profile: ${profile_id}, ` +
      `Limit: $${configured_limit}, Current: $${current_cost}`
    );

    // Alert your team
    alertTeam({
      title: 'SMS Spend Limit Reached',
      message: `Profile ${profile_id} hit $${configured_limit} limit. ` +
               `Current spend: $${current_cost}. Messages are being rejected.`,
    });
  }

  res.json({ status: 'ok' });
});

Track spending

Monitor your messaging spend to take action before hitting the limit:

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

def check_spend(profile_id: str) -> dict:
    """Check current spend against the configured limit."""
    profile = client.messaging_profiles.retrieve(profile_id)

    limit = float(profile.data.daily_spend_limit or 0)
    enabled = profile.data.daily_spend_limit_enabled

    return {
        "profile_id": profile_id,
        "limit_enabled": enabled,
        "daily_limit": limit,
    }

def send_with_spend_check(profile_id: str, to: str, from_: str, text: str):
    """Send a message with pre-send spend checking."""
    try:
        response = client.messages.send(from_=from_, to=to, text=text)
        return {"status": "sent", "message_id": response.data.id}
    except Exception as e:
        error_code = getattr(e, "code", None)
        if error_code == "40333":
            return {"status": "blocked", "reason": "spend_limit_reached"}
        raise

# Check profile status
info = check_spend("your_messaging_profile_id")
print(f"Limit enabled: {info['limit_enabled']}, Limit: ${info['daily_limit']}")

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

async function checkSpend(profileId) {
  const profile = await client.messagingProfiles.retrieve(profileId);
  return {
    profileId,
    limitEnabled: profile.data.daily_spend_limit_enabled,
    dailyLimit: parseFloat(profile.data.daily_spend_limit || '0'),
  };
}

async function sendWithSpendCheck(profileId, to, from, text) {
  try {
    const response = await client.messages.send({ from, to, text });
    return { status: 'sent', messageId: response.data.id };
  } catch (err) {
    if (err.rawType === '40333') {
      return { status: 'blocked', reason: 'spend_limit_reached' };
    }
    throw err;
  }
}

Reset and override

The running spend total resets automatically at midnight UTC each day. After reset, messages can be sent until the limit is exceeded again. Changing the daily_spend_limit or daily_spend_limit_enabled values does not reset the running total. Only the midnight UTC reset clears accumulated spend. If you’ve hit the limit but need to send urgent messages, temporarily disable the limit:

# 1. Disable the limit
client.messaging_profiles.update(
    profile_id, daily_spend_limit_enabled=False
)

# 2. Send urgent messages
client.messages.send(from_=from_number, to=to_number, text="Urgent message")

# 3. Re-enable the limit
client.messaging_profiles.update(
    profile_id, daily_spend_limit_enabled=True
)

Re-enabling does not reset the counter. If you were at

10.00 of a

10.00 limit, re-enabling will immediately block again. Either increase the limit or wait for the midnight UTC reset. Raise the daily_spend_limit to allow more messages until the new limit is reached:

# Increase from $10 to $25
client.messaging_profiles.update(
    profile_id,
    daily_spend_limit="25.00"
)

This takes effect immediately — if current spend is

10.02 and the new limit is

25.00, messages will flow again until $25.00 is reached.

Best practices

Even if you don’t expect high spend, a limit prevents runaway costs from application bugs or compromised API keys. Create separate messaging profiles for transactional messages (OTP, alerts) and marketing messages, each with appropriate limits. Always handle the messaging-profile.spend-limit-reached webhook to alert your team immediately. Your application should gracefully handle the 40333 error code — queue messages for later delivery or switch to a backup profile. As your messaging volume grows, review and adjust limits to avoid unexpected blocks during peak periods.

API reference for configuring messaging profile settings. Track message costs and delivery status. Understand message throughput limits. Configure webhooks to receive spend limit notifications.

Message Detail Records

Source: https://developers.telnyx.com/docs/messaging/messages/message-detail-records.md

A Message Detail Record (MDR) describes a specific message request—including its current status, cost, and metadata. Telnyx creates an MDR when a message is submitted and updates it as the message progresses through delivery.

When to Use MDRs

Check if a message was delivered, failed, or is still in progress. Investigate delivery issues by examining message status and error codes. Confirm message costs after delivery for billing reconciliation. Retrieve message history for compliance and record-keeping.

Retrieve an MDR

Fetch a message record using its UUID. The UUID is returned when you send a message and is also included in webhook events.

curl

curl -X GET "https://api.telnyx.com/v2/messages/834f3d53-8a3c-4aa0-a733-7f2d682a72df" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const response = await client.messages.retrieve(
  '834f3d53-8a3c-4aa0-a733-7f2d682a72df'
);

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messages.retrieve(
    "834f3d53-8a3c-4aa0-a733-7f2d682a72df"
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.retrieve(
  "834f3d53-8a3c-4aa0-a733-7f2d682a72df"
)

puts response

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )

  response, err := client.Messages.Get(
    context.TODO(),
    "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.*;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageGetResponse response = client.messages()
            .get("834f3d53-8a3c-4aa0-a733-7f2d682a72df");
        System.out.println(response);
    }
}

.NET

using System;
using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var message = await service.GetAsync("834f3d53-8a3c-4aa0-a733-7f2d682a72df");

Console.WriteLine(message);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$message = \Telnyx\Message::Retrieve("834f3d53-8a3c-4aa0-a733-7f2d682a72df");

print_r($message);

Example Response

{
  "data": {
    "record_type": "message",
    "id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
    "direction": "outbound",
    "type": "SMS",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+18445550001",
      "carrier": "Telnyx",
      "line_type": "VoIP"
    },
    "to": [
      {
        "phone_number": "+18665550002",
        "status": "delivered",
        "updated_at": "2019-01-23T18:10:02.574Z"
      }
    ],
    "text": "Hello, World!",
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://www.example.com/hooks-backup",
    "use_profile_webhooks": false,
    "encoding": "GSM-7",
    "parts": 1,
    "cost": {
      "amount": "0.0050",
      "currency": "USD"
    },
    "errors": [],
    "created_at": "2019-01-23T18:10:00.000Z",
    "updated_at": "2019-01-23T18:10:02.574Z",
    "valid_until": "2019-01-23T18:25:00.000Z"
  }
}

MDR Schema

Field	Type	Description
`id`	UUID	Unique identifier for the message request
`direction`	string	`inbound` or `outbound`
`type`	string	Message type: `SMS`, `MMS`, or `RCS`
`messaging_profile_id`	UUID	The messaging profile used to send/receive
`from`	object	Sender details including `phone_number`, `carrier`, `line_type`
`to`	array	Recipients with `phone_number`, `status`, `updated_at`
`text`	string	Message body content
`media_urls`	array	Media attachment URLs (MMS only)
`encoding`	string	Character encoding: `GSM-7` or `UCS-2`
`parts`	integer	Number of message segments
`cost`	object	`amount` and `currency` (may be `null` until finalized)
`errors`	array	Error details if delivery failed
`webhook_url`	string	URL for delivery status webhooks
`webhook_failover_url`	string	Backup webhook URL
`use_profile_webhooks`	boolean	Whether to use profile-level webhooks
`created_at`	ISO 8601	When the message was submitted
`updated_at`	ISO 8601	Last status update time
`valid_until`	ISO 8601	Expiration time for pending messages

Cost may be null: When retrieved immediately after sending, cost may be null because pricing is calculated asynchronously. The final cost appears in the message.finalized webhook event.

Message Status

The status field in the to array indicates where the message is in its lifecycle.

Outbound Status Flow

Outbound Statuses

Status	Description	Final?
`queued`	Message accepted and queued for sending	No
`sent`	Delivered to carrier gateway	No
`delivered`	Carrier confirmed delivery to handset	✓ Yes
`failed`	Delivery failed (see `errors` array)	✓ Yes
`gw_timeout`	No response from gateway	✓ Yes
`dlr_timeout`	No delivery receipt from carrier	✓ Yes

Track delivery with webhooks: Rather than polling for status, configure a webhook URL to receive real-time status updates as message.sent, message.delivered, or message.finalized events.

Inbound Statuses

Status	Description
`received`	Message received by Telnyx
`delivered`	Message delivered to your webhook

Common Error Codes

When a message fails, the errors array contains details:

{
  "errors": [
    {
      "code": "40301",
      "title": "Destination number blocked",
      "detail": "The recipient has opted out of messages from this sender"
    }
  ]
}

Error Code	Description	Resolution
`40300`	Invalid destination	Verify the phone number format
`40301`	Destination blocked	Recipient has opted out—remove from list
`40310`	Carrier rejected	Message content may have triggered spam filters
`40311`	Undeliverable	Number is unreachable (landline, disconnected)
`40400`	Sender not registered	Register for 10DLC or toll-free verification
`40500`	Rate limit exceeded	Slow down sending or request higher limits

See the Error Codes Reference for the complete list.

Best Practices

Polling the MDR endpoint is inefficient and can hit rate limits. Instead, configure webhooks on your Messaging Profile to receive real-time updates:

message.sent — Message accepted by carrier
message.delivered — Confirmed delivery
message.finalized — Final status with cost

{
  "webhook_url": "https://your-app.com/webhooks/messaging",
  "webhook_failover_url": "https://your-app.com/webhooks/messaging-backup"
}

Save the id returned when you send a message. This UUID is required to retrieve the MDR later:

const response = await client.messages.send({
  from: '+15551234567',
  to: '+15559876543',
  text: 'Hello!'
});

// Store this for later tracking
const messageId = response.data.id;

The cost field is populated asynchronously. For accurate billing:

Wait for the message.finalized webhook, OR
Retrieve the MDR after a few seconds

// Cost may not be available immediately
if (message.cost === null) {
  // Wait for message.finalized webhook or retry later
}

Troubleshooting

Possible causes:

Invalid message ID format
Message ID from a different account
Message was never created (request was rejected at validation)

Solution: Verify the UUID format and check that the message send request returned a 201 status. Rejected requests don’t create MDRs. Possible causes:

Message is rate-limited and waiting in queue
Gateway connection issue

Solution: Wait a few minutes. If still queued after 5 minutes, check system status for outages. Messages stuck beyond valid_until will fail. Cause: Cost is calculated asynchronously after the message is sent. Solution: Either wait for the message.finalized webhook, or retrieve the MDR again after 5-10 seconds.

Next Steps

Get real-time delivery updates Complete sending quickstart Full error code reference Complete Messages API docs

Overview

Source: https://developers.telnyx.com/docs/messaging/messages/messaging-profiles-overview.md

A messaging profile is the central configuration object for your Telnyx messaging setup. It groups your phone numbers, defines webhook URLs, and controls features like number pooling, smart encoding, and spend limits. Every phone number you use for messaging must be assigned to a messaging profile.

What a messaging profile controls

Setting	Description	Default
Webhook URL	Where inbound messages and delivery status events are sent	None (required)
Number Pool	Distribute messages across multiple numbers automatically	Disabled
Sticky Sender	Keep the same sender number for each recipient	Disabled
Geomatch	Select sender numbers based on geographic proximity	Disabled
Smart Encoding	Replace Unicode characters with GSM-7 equivalents	Disabled
MMS Transcoding	Automatically resize media for carrier limits	Disabled
Spend Limit	Daily spend cap to prevent unexpected costs	Disabled
URL Shortening	Shorten URLs in outbound messages	Disabled

Create a messaging profile

curl

curl -X POST https://api.telnyx.com/v2/messaging_profiles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "My Messaging Profile",
    "webhook_url": "https://example.com/webhooks/messaging",
    "webhook_failover_url": "https://example.com/webhooks/messaging/failover"
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

profile = client.messaging_profiles.create(
    name="My Messaging Profile",
    webhook_url="https://example.com/webhooks/messaging",
    webhook_failover_url="https://example.com/webhooks/messaging/failover",
)

print(f"Profile created: {profile.data.id}")

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const profile = await client.messagingProfiles.create({
  name: 'My Messaging Profile',
  webhook_url: 'https://example.com/webhooks/messaging',
  webhook_failover_url: 'https://example.com/webhooks/messaging/failover',
});

console.log(`Profile created: ${profile.data.id}`);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

profile = client.messaging_profiles.create(
  name: "My Messaging Profile",
  webhook_url: "https://example.com/webhooks/messaging",
  webhook_failover_url: "https://example.com/webhooks/messaging/failover"
)

puts "Profile created: #{profile.data.id}"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  profile, err := client.MessagingProfiles.Create(
    context.TODO(),
    telnyx.MessagingProfileCreateParams{
      Name:               "My Messaging Profile",
      WebhookURL:         "https://example.com/webhooks/messaging",
      WebhookFailoverURL: telnyx.String("https://example.com/webhooks/messaging/failover"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Profile created: %s\n", profile.Data.ID)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messagingprofiles.MessagingProfileCreateParams;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var params = MessagingProfileCreateParams.builder()
            .name("My Messaging Profile")
            .webhookUrl("https://example.com/webhooks/messaging")
            .webhookFailoverUrl("https://example.com/webhooks/messaging/failover")
            .build();

        var profile = client.messagingProfiles().create(params);
        System.out.println("Profile created: " + profile.data().id());
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessagingProfileService();
var profile = await service.CreateAsync(new MessagingProfileCreateOptions
{
    Name = "My Messaging Profile",
    WebhookUrl = "https://example.com/webhooks/messaging",
    WebhookFailoverUrl = "https://example.com/webhooks/messaging/failover"
});

Console.WriteLine($"Profile created: {profile.Data.Id}");

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$profile = \Telnyx\MessagingProfile::Create([
    'name' => 'My Messaging Profile',
    'webhook_url' => 'https://example.com/webhooks/messaging',
    'webhook_failover_url' => 'https://example.com/webhooks/messaging/failover'
]);

echo "Profile created: {$profile->id}\n";

You can also create messaging profiles in the Telnyx Portal under Messaging > Messaging Profiles.

Configure profile features

Update an existing profile to enable features:

curl

curl -X PATCH https://api.telnyx.com/v2/messaging_profiles/{profile_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "geomatch": true,
      "sticky_sender": true,
      "skip_unhealthy": true
    },
    "smart_encoding": true,
    "mms_transcoding": true,
    "daily_spend_limit_enabled": true,
    "daily_spend_limit": "50.00"
  }'

Python

response = client.messaging_profiles.update(
    "your_messaging_profile_id",
    number_pool_settings={
        "geomatch": True,
        "sticky_sender": True,
        "skip_unhealthy": True,
    },
    smart_encoding=True,
    mms_transcoding=True,
    daily_spend_limit_enabled=True,
    daily_spend_limit="50.00",
)

print(f"Profile updated: {response.data.id}")

Node

const response = await client.messagingProfiles.update(
  'your_messaging_profile_id',
  {
    number_pool_settings: {
      geomatch: true,
      sticky_sender: true,
      skip_unhealthy: true,
    },
    smart_encoding: true,
    mms_transcoding: true,
    daily_spend_limit_enabled: true,
    daily_spend_limit: '50.00',
  }
);

console.log(`Profile updated: ${response.data.id}`);

Profile features explained

Every messaging profile needs a webhook URL to receive:

Inbound messages — SMS/MMS received on your numbers
Delivery status updates — sent, delivered, failed, etc.
Spend limit notifications — when daily limits are reached

Configure a failover URL as a backup in case your primary webhook is unreachable.

Setting	Description
`webhook_url`	Primary URL for all messaging events
`webhook_failover_url`	Backup URL if primary fails
`webhook_api_version`	API version for webhook payloads (`1` or `2`)

See Webhooks for implementation details. When enabled, messages sent from the profile automatically distribute across all assigned numbers. This increases throughput and helps avoid carrier filtering. Settings:

Setting	Description
`geomatch`	Select sender number closest to recipient’s area code
`sticky_sender`	Reuse the same sender number for each recipient
`skip_unhealthy`	Skip numbers with delivery issues
`long_code_weight`	Weight for long code selection (default: 1)
`toll_free_weight`	Weight for toll-free selection (default: 1)

See Number Pool for details. Automatically replaces Unicode characters (curly quotes, em dashes, etc.) with GSM-7 equivalents to keep messages in the more efficient encoding and reduce segment counts. A single curly quote can switch an entire message from GSM-7 (160 chars/segment) to UTF-16 (70 chars/segment), more than doubling costs. See Smart Encoding for the full character substitution reference. Automatically resizes images and videos to meet carrier size limits before delivery. When enabled:

Images are converted to JPEG
Videos are converted to H.264 MP4
Animated GIFs are not resized

See MMS Media & Transcoding for carrier size limits. Set a daily spending cap to prevent unexpected costs. When the limit is reached:

New messages are rejected with error 40333
A webhook notification is sent
An email alert is sent to your account

The limit resets at midnight UTC daily. See Spend Limits for configuration and webhook handling. Automatically shorten URLs in outbound messages. Shortened URLs use your configured domain and track click-through rates.

Setting	Description
`url_shortener_settings.domain`	Custom domain for shortened URLs
`url_shortener_settings.prefix`	URL prefix
`url_shortener_settings.replace_blacklist_only`	Only replace blacklisted URLs
`url_shortener_settings.send_webhooks`	Send click-tracking webhooks

Assign phone numbers

After creating a profile, assign phone numbers to it:

curl

curl -X POST https://api.telnyx.com/v2/messaging_profiles/{profile_id}/phone_numbers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"phone_number_id": "your_phone_number_id"}'

Python

# List numbers on a profile
numbers = client.messaging_profiles.list_phone_numbers(
    "your_messaging_profile_id"
)

for number in numbers.data:
    print(f"{number.phone_number} ({number.type})")

Node

// List numbers on a profile
const numbers = await client.messagingProfiles.listPhoneNumbers(
  'your_messaging_profile_id'
);

numbers.data.forEach(n => {
  console.log(`${n.phone_number} (${n.type})`);
});

You can also assign numbers to profiles in the Telnyx Portal by editing a messaging profile and selecting numbers.

Common configurations

{
  "name": "Transactional Messages",
  "webhook_url": "https://api.example.com/webhooks/sms",
  "smart_encoding": true,
  "daily_spend_limit_enabled": true,
  "daily_spend_limit": "100.00"
}

Best for: OTP codes, account alerts, order confirmations. Low volume, high priority. Smart encoding reduces costs.

{
  "name": "Marketing Campaigns",
  "webhook_url": "https://api.example.com/webhooks/marketing",
  "number_pool_settings": {
    "geomatch": true,
    "sticky_sender": true,
    "skip_unhealthy": true
  },
  "smart_encoding": true,
  "mms_transcoding": true,
  "daily_spend_limit_enabled": true,
  "daily_spend_limit": "500.00"
}

Best for: Promotional messages, newsletters. Number pool for throughput. Higher spend limit for volume.

{
  "name": "Customer Support",
  "webhook_url": "https://api.example.com/webhooks/support",
  "number_pool_settings": {
    "sticky_sender": true
  },
  "smart_encoding": true
}

Best for: Two-way conversations. Sticky sender ensures customers always see the same number.

Distribute messages across multiple numbers for higher throughput. Reduce SMS costs by replacing Unicode with GSM-7 characters. Set daily spend caps to prevent unexpected costs. Receive inbound messages and delivery status updates.

Number Pool

Source: https://developers.telnyx.com/docs/messaging/messages/number-pool.md

Number Pool automatically distributes your outbound messages across multiple phone numbers, helping you scale messaging campaigns while maintaining deliverability. Instead of specifying a single “from” number, Telnyx selects the optimal sender from your pool based on availability, health, and configured weights.

When to Use Number Pool

Distribute traffic across numbers to avoid per-number rate limits and increase total throughput. Automatically skip unhealthy numbers and spread reputation across multiple senders. Balance between long codes and toll-free numbers with configurable weights. No need to track which number to use—Telnyx handles sender selection.

How It Works

Pool creation: All long code and toll-free numbers assigned to your Messaging Profile form the pool
Sender selection: When you send a message, Telnyx picks an available number from the pool
Weight distribution: Control the ratio of long code vs. toll-free usage with weights
Health monitoring: Optionally skip numbers with poor delivery rates

Prerequisites

A Messaging Profile with at least one phone number assigned
Multiple numbers recommended for effective load distribution

Configure Number Pool

Enable Number Pool on your Messaging Profile by setting the number_pool_settings. The weights control which number types are preferred.

curl

curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "long_code_weight": 5,
      "toll_free_weight": 1,
      "skip_unhealthy": true
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const response = await client.messagingProfiles.update(
  'YOUR_PROFILE_ID',
  {
    number_pool_settings: {
      long_code_weight: 5,
      toll_free_weight: 1,
      skip_unhealthy: true
    }
  }
);

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messaging_profiles.update(
    "YOUR_PROFILE_ID",
    number_pool_settings={
        "long_code_weight": 5,
        "toll_free_weight": 1,
        "skip_unhealthy": True
    }
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messaging_profiles.update(
  "YOUR_PROFILE_ID",
  number_pool_settings: {
    long_code_weight: 5,
    toll_free_weight: 1,
    skip_unhealthy: true
  }
)

puts response

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )

  response, err := client.MessagingProfiles.Update(
    context.TODO(),
    "YOUR_PROFILE_ID",
    telnyx.MessagingProfileUpdateParams{
      NumberPoolSettings: &telnyx.NumberPoolSettingsParam{
        LongCodeWeight:  telnyx.Int(5),
        TollFreeWeight:  telnyx.Int(1),
        SkipUnhealthy:   telnyx.Bool(true),
      },
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messagingprofiles.*;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        NumberPoolSettings poolSettings = NumberPoolSettings.builder()
            .longCodeWeight(5)
            .tollFreeWeight(1)
            .skipUnhealthy(true)
            .build();

        MessagingProfileUpdateParams params = MessagingProfileUpdateParams.builder()
            .numberPoolSettings(poolSettings)
            .build();

        MessagingProfileUpdateResponse response = client.messagingProfiles()
            .update("YOUR_PROFILE_ID", params);
        System.out.println(response);
    }
}

.NET

using System;
using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessagingProfileService();
var options = new MessagingProfileUpdateOptions
{
    NumberPoolSettings = new NumberPoolSettings
    {
        LongCodeWeight = 5,
        TollFreeWeight = 1,
        SkipUnhealthy = true
    }
};

var profile = service.Update("YOUR_PROFILE_ID", options);
Console.WriteLine(profile);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$profile = \Telnyx\MessagingProfile::update("YOUR_PROFILE_ID", [
    "number_pool_settings" => [
        "long_code_weight" => 5,
        "toll_free_weight" => 1,
        "skip_unhealthy" => true
    ]
]);

print_r($profile);

Go to Messaging in the portal
Click the edit icon next to your Messaging Profile
Under Outbound, toggle on Number Pool
Configure the weights for long codes and toll-free numbers
Optionally enable Skip Unhealthy Numbers
Click Save

Configuration Options

Parameter	Type	Description
`long_code_weight`	integer	Weight for long code selection (0 removes from pool)
`toll_free_weight`	integer	Weight for toll-free selection (0 removes from pool)
`skip_unhealthy`	boolean	Skip numbers with poor delivery rates
`sticky_sender`	boolean	Reuse same number for recipient when possible
`geomatch`	boolean	Match sender to recipient’s geographic area

Weights are ratios, not percentages. With long_code_weight: 5 and toll_free_weight: 1, approximately 5 out of every 6 messages use a long code.

Send Messages with Number Pool

When sending with Number Pool, omit the from field and specify your messaging_profile_id instead. Telnyx automatically selects the optimal sender.

curl

curl -X POST "https://api.telnyx.com/v2/messages/number_pool" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": "YOUR_PROFILE_ID",
    "to": "+15559876543",
    "text": "Hello from Number Pool!"
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const response = await client.messages.sendWithNumberPool({
  messaging_profile_id: 'YOUR_PROFILE_ID',
  to: '+15559876543',
  text: 'Hello from Number Pool!'
});

console.log(`Sent from: ${response.data.from.phone_number}`);

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messages.send_with_number_pool(
    messaging_profile_id="YOUR_PROFILE_ID",
    to="+15559876543",
    text="Hello from Number Pool!"
)

print(f"Sent from: {response.data.from_.phone_number}")

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_with_number_pool(
  messaging_profile_id: "YOUR_PROFILE_ID",
  to: "+15559876543",
  text: "Hello from Number Pool!"
)

puts "Sent from: #{response.from.phone_number}"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )

  response, err := client.Messages.SendWithNumberPool(
    context.TODO(),
    telnyx.MessageSendWithNumberPoolParams{
      MessagingProfileID: "YOUR_PROFILE_ID",
      To:                 "+15559876543",
      Text:               "Hello from Number Pool!",
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Sent from: %s\n", response.Data.From.PhoneNumber)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.*;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MessageSendWithNumberPoolParams params = MessageSendWithNumberPoolParams.builder()
            .messagingProfileId("YOUR_PROFILE_ID")
            .to("+15559876543")
            .text("Hello from Number Pool!")
            .build();

        MessageSendResponse response = client.messages().sendWithNumberPool(params);
        System.out.println("Sent from: " + response.data().from().phoneNumber());
    }
}

.NET

using System;
using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessagingService();
var options = new MessageSendWithNumberPoolOptions
{
    MessagingProfileId = "YOUR_PROFILE_ID",
    To = "+15559876543",
    Text = "Hello from Number Pool!"
};

var message = service.SendWithNumberPool(options);
Console.WriteLine($"Sent from: {message.From.PhoneNumber}");

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$message = \Telnyx\Message::create([
    "messaging_profile_id" => "YOUR_PROFILE_ID",
    "to" => "+15559876543",
    "text" => "Hello from Number Pool!"
], null, "/v2/messages/number_pool");

echo "Sent from: " . $message->from->phone_number . "\n";

The response includes the actual from number that was selected:

{
  "data": {
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "from": {
      "phone_number": "+15551234567",
      "carrier": "Telnyx",
      "line_type": "long_code"
    },
    "to": [
      {
        "phone_number": "+15559876543",
        "status": "queued"
      }
    ],
    "text": "Hello from Number Pool!"
  }
}

Disable Number Pool

To disable Number Pool, set number_pool_settings to an empty object:

curl

curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number_pool_settings": {}}'

Node

await client.messagingProfiles.update('YOUR_PROFILE_ID', {
  number_pool_settings: {}
});

Python

client.messaging_profiles.update(
    "YOUR_PROFILE_ID",
    number_pool_settings={}
)

Number Pool works alongside these Messaging Profile features: Maintains consistency by using the same number for a recipient across messages. When enabled, if you’ve previously messaged a recipient, the same number is reused when available. Enable with:

{
  "number_pool_settings": {
    "long_code_weight": 1,
    "sticky_sender": true
  }
}

See Sticky Sender for details. Selects a sender number matching the recipient’s geographic area, improving deliverability and user trust by showing a local number. Enable with:

{
  "number_pool_settings": {
    "long_code_weight": 1,
    "geomatch": true
  }
}

See Geomatch for details. Monitors delivery success rates and automatically excludes numbers performing poorly. This helps maintain overall campaign deliverability. If all numbers in the pool are unhealthy, message sending will fail rather than use an unhealthy number.

Troubleshooting

Cause: All numbers are flagged as unhealthy and skip_unhealthy is enabled. Solutions:

Temporarily disable skip_unhealthy to allow sending
Add more numbers to your Messaging Profile
Investigate delivery issues on your existing numbers

Cause: Weight of one type set to 0, or only one number type assigned. Solutions:

Verify weights are non-zero for both types
Ensure you have both long codes and toll-free numbers assigned to the profile

Cause: Using the standard /v2/messages endpoint instead of /v2/messages/number_pool. Solution: Use the Number Pool send endpoint which requires messaging_profile_id instead of from.

Next Steps

Maintain sender consistency for recipients Match sender to recipient geography Understand messaging throughput limits View full Number Pool API details

Sticky Sender

Source: https://developers.telnyx.com/docs/messaging/messages/sticky-sender.md

Sticky Sender ensures the same phone number is used every time your application messages a particular recipient. This consistency builds familiarity—your customers see the same number each time, making your messages more recognizable and trustworthy. Sticky Sender is part of Number Pool settings. You must have Number Pool enabled to use Sticky Sender.

When to Use Sticky Sender

Maintain consistent sender identity throughout multi-message conversations. Appointment reminders, delivery updates, and alerts from a familiar number. Customers can save your number knowing future messages will come from the same sender. Build trust by ensuring customers recognize your number over time.

How It Works

First message: Telnyx selects a number from your pool (using weights, geomatch, or availability)
Mapping created: The recipient-to-sender pairing is stored
Future messages: The same sender is automatically used for that recipient
Mapping expires: After 8 days of no messages, the mapping resets

Mapping Behavior

Scenario	Behavior
Message sent within 8 days	Same sender reused, timer resets
No messages for 8+ days	Mapping expires, new sender assigned
Sticky Sender disabled	All mappings cleared immediately
Number removed from profile	Mappings to that number cleared
Sticky number unavailable	New number selected, new mapping created

Compare with Twilio: Sticky Sender works similarly to Twilio’s Messaging Services sticky sender feature. If you’re migrating, the concept is the same—just configure it on your Messaging Profile instead.

Prerequisites

A Messaging Profile with Number Pool enabled
At least one phone number assigned to the profile

Configure Sticky Sender

Enable Sticky Sender by updating your Messaging Profile’s number_pool_settings. The PATCH endpoint merges with your existing configuration—only the fields you include are updated. Your current weights and other Number Pool settings are preserved.

curl

curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "sticky_sender": true
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const response = await client.messagingProfiles.update(
  'YOUR_PROFILE_ID',
  {
    number_pool_settings: {
      sticky_sender: true
    }
  }
);

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messaging_profiles.update(
    "YOUR_PROFILE_ID",
    number_pool_settings={
        "sticky_sender": True
    }
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messaging_profiles.update(
  "YOUR_PROFILE_ID",
  number_pool_settings: {
    sticky_sender: true
  }
)

puts response

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )

  response, err := client.MessagingProfiles.Update(
    context.TODO(),
    "YOUR_PROFILE_ID",
    telnyx.MessagingProfileUpdateParams{
      NumberPoolSettings: &telnyx.NumberPoolSettingsParam{
        StickySender: telnyx.Bool(true),
      },
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messagingprofiles.*;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        NumberPoolSettings poolSettings = NumberPoolSettings.builder()
            .stickySender(true)
            .build();

        MessagingProfileUpdateParams params = MessagingProfileUpdateParams.builder()
            .numberPoolSettings(poolSettings)
            .build();

        MessagingProfileUpdateResponse response = client.messagingProfiles()
            .update("YOUR_PROFILE_ID", params);
        System.out.println(response);
    }
}

.NET

using System;
using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessagingProfileService();
var options = new MessagingProfileUpdateOptions
{
    NumberPoolSettings = new NumberPoolSettings
    {
        StickySender = true
    }
};

var profile = service.Update("YOUR_PROFILE_ID", options);
Console.WriteLine(profile);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$profile = \Telnyx\MessagingProfile::update("YOUR_PROFILE_ID", [
    "number_pool_settings" => [
        "sticky_sender" => true
    ]
]);

print_r($profile);

The response confirms your settings:

{
  "data": {
    "id": "YOUR_PROFILE_ID",
    "record_type": "messaging_profile",
    "name": "My Profile",
    "number_pool_settings": {
      "sticky_sender": true,
      "geomatch": false,
      "long_code_weight": 1,
      "toll_free_weight": 0,
      "skip_unhealthy": false
    }
  }
}

Go to Messaging in the portal
Click the edit icon next to your Messaging Profile
Under Outbound, toggle on Number Pool
Check the Sticky Sender checkbox
Click Save

Disable Sticky Sender

To disable Sticky Sender, set the sticky_sender field to false. This immediately clears all existing mappings.

curl

curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "sticky_sender": false
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

await client.messagingProfiles.update('YOUR_PROFILE_ID', {
  number_pool_settings: {
    sticky_sender: false
  }
});

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

client.messaging_profiles.update(
    "YOUR_PROFILE_ID",
    number_pool_settings={
        "sticky_sender": False
    }
)

Disabling Sticky Sender clears all recipient-to-sender mappings. Re-enabling it starts fresh—previous mappings are not restored.

Combining with Other Features

Sticky Sender works alongside other Number Pool settings. The priority order for number selection is:

Sticky Sender (if enabled and mapping exists)
Geomatch (if enabled and matching area code available)
Weight distribution (long code vs. toll-free preference)
Skip unhealthy (exclude poor-performing numbers)

When both are enabled:

First message: Geomatch selects a number matching the recipient’s area code
Future messages: Sticky Sender reuses that same geomatched number

This combination provides both local presence and consistency.

{
  "number_pool_settings": {
    "sticky_sender": true,
    "geomatch": true
  }
}

If a sticky sender mapping points to a number that becomes unhealthy:

The mapping is preserved
Messages still route through that number (skip_unhealthy doesn’t override sticky mappings)

To force re-selection, temporarily disable and re-enable Sticky Sender to clear mappings.

Troubleshooting

Possible causes:

Sticky Sender not enabled on the Messaging Profile
Previous mapping expired (8+ days since last message)
A phone number was removed from the profile

Solutions:

Verify Sticky Sender is enabled in your profile settings
Send messages more frequently to prevent mapping expiration
Check that all expected numbers are still assigned to the profile

Cause: Sticky Sender preserves existing mappings—adding new numbers doesn’t affect recipients who already have mappings. Solution: If you want recipients to potentially use new numbers, temporarily disable Sticky Sender to clear mappings, then re-enable it. New messages will be distributed across all available numbers. Retrieve your Messaging Profile to see current settings:

curl "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data.number_pool_settings'

Response:

{
  "sticky_sender": true,
  "geomatch": false,
  "long_code_weight": 1,
  "toll_free_weight": 0,
  "skip_unhealthy": false
}

Next Steps

Learn about number pool configuration and weights Match sender to recipient geography Send your first message with Number Pool View full Messaging Profile API details

Geomatch

Source: https://developers.telnyx.com/docs/messaging/messages/geomatch.md

Geomatch automatically selects sender numbers that share the same area code as your recipients. When enabled, Telnyx matches your outbound messages with locally-recognized numbers—boosting trust and engagement with your customers. Geomatch is part of Number Pool settings. You must have Number Pool enabled to use Geomatch.

When to Use Geomatch

Appear local to recipients—messages from familiar area codes are more likely to be read and trusted. Local numbers typically see better response rates than out-of-area or toll-free numbers. Automatically match senders across different geographic areas without manual routing logic. Build rapport with customers who prefer communicating with local business numbers. NANP only: Geomatch currently supports only North American numbers (US, Canada, Caribbean). International numbers don’t participate in geomatching.

How It Works

Message sent: Your app sends a message without specifying a from number (using Number Pool)
Area code lookup: Telnyx identifies the recipient’s area code
Pool search: Telnyx searches your number pool for a matching area code
Selection: If found, that number is used; otherwise, a number with a different area code is selected

Prerequisites

A Messaging Profile with Number Pool enabled
Phone numbers from multiple area codes assigned to the profile (for effective geomatching)

Configure Geomatch

Enable Geomatch by updating your Messaging Profile’s number_pool_settings.

curl

curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "long_code_weight": 1,
      "geomatch": true
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const response = await client.messagingProfiles.update(
  'YOUR_PROFILE_ID',
  {
    number_pool_settings: {
      long_code_weight: 1,
      geomatch: true
    }
  }
);

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messaging_profiles.update(
    "YOUR_PROFILE_ID",
    number_pool_settings={
        "long_code_weight": 1,
        "geomatch": True
    }
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messaging_profiles.update(
  "YOUR_PROFILE_ID",
  number_pool_settings: {
    long_code_weight: 1,
    geomatch: true
  }
)

puts response

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )

  response, err := client.MessagingProfiles.Update(
    context.TODO(),
    "YOUR_PROFILE_ID",
    telnyx.MessagingProfileUpdateParams{
      NumberPoolSettings: &telnyx.NumberPoolSettingsParam{
        LongCodeWeight: telnyx.Int(1),
        Geomatch:       telnyx.Bool(true),
      },
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messagingprofiles.*;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        NumberPoolSettings poolSettings = NumberPoolSettings.builder()
            .longCodeWeight(1)
            .geomatch(true)
            .build();

        MessagingProfileUpdateParams params = MessagingProfileUpdateParams.builder()
            .numberPoolSettings(poolSettings)
            .build();

        MessagingProfileUpdateResponse response = client.messagingProfiles()
            .update("YOUR_PROFILE_ID", params);
        System.out.println(response);
    }
}

.NET

using System;
using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessagingProfileService();
var options = new MessagingProfileUpdateOptions
{
    NumberPoolSettings = new NumberPoolSettings
    {
        LongCodeWeight = 1,
        Geomatch = true
    }
};

var profile = service.Update("YOUR_PROFILE_ID", options);
Console.WriteLine(profile);

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$profile = \Telnyx\MessagingProfile::update("YOUR_PROFILE_ID", [
    "number_pool_settings" => [
        "long_code_weight" => 1,
        "geomatch" => true
    ]
]);

print_r($profile);

The examples include long_code_weight to ensure Number Pool is active. If you already have Number Pool configured, you can omit weight fields—PATCH requests merge with existing settings.

Go to Messaging in the portal
Click the edit icon next to your Messaging Profile
Under Outbound, toggle on Number Pool
Check the Geomatch option
Click Save

Selection Behavior

Understanding how Geomatch selects senders helps you optimize your number pool coverage.

Selection Priority

When both Geomatch and Sticky Sender are enabled:

Priority	Condition	Behavior
1	Sticky mapping exists	Use the mapped sender (geomatch ignored)
2	No mapping + matching area code available	Use geomatched number, create sticky mapping
3	No mapping + no matching area code	Use any available number, create sticky mapping

Sticky Sender takes precedence over Geomatch. Once a recipient is mapped to a sender, that sender is used regardless of area code matching.

Coverage Planning

For effective geomatching, ensure your number pool covers the area codes where your recipients are located:

Coverage Level	Description	Example
Full coverage	Numbers in all target area codes	Pool: 415, 212, 312, 305 for SF, NYC, Chicago, Miami campaigns
Regional coverage	Numbers per region, not every area code	Pool: 415 for CA, 212 for NY, 312 for IL
Minimal coverage	Single area code	Pool: Only 415 numbers (geomatch rarely activates)

Use the Phone Numbers API to audit your pool’s area code coverage. Search for numbers in missing area codes to improve geomatch rates.

Disable Geomatch

To disable Geomatch while keeping Number Pool active:

curl

curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "geomatch": false
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

await client.messagingProfiles.update('YOUR_PROFILE_ID', {
  number_pool_settings: {
    geomatch: false
  }
});

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

client.messaging_profiles.update(
    "YOUR_PROFILE_ID",
    number_pool_settings={
        "geomatch": False
    }
)

Geomatch works best combined with other Number Pool features: Maintain the same sender for each recipient. When combined with Geomatch:

First message uses geomatch selection
Subsequent messages use the “stuck” sender (even if area code no longer matches)

See Sticky Sender for details. Exclude poorly performing numbers from the pool. A geomatched number will be skipped if:

skip_unhealthy: true is enabled
The number’s deliverability rate is below 25% OR spam ratio exceeds 75%

The next best geomatch candidate is used instead. Control the ratio of long codes to toll-free numbers. Geomatch respects these weights—if you weight toll-free higher, toll-free numbers are preferred even when long codes have matching area codes. See Number Pool for configuration details.

Troubleshooting

Possible causes:

Geomatch not enabled on the profile
No numbers with matching area code in your pool
Sticky Sender is enabled and recipient already has a mapping to a different number
Matching number is unhealthy and skip_unhealthy is enabled

Solution: Verify Geomatch is enabled, then check your pool’s area code coverage. Use the portal or API to list numbers assigned to your messaging profile. Cause: Geomatch only supports NANP (North American Numbering Plan) numbers—US, Canada, and Caribbean. Solution: For international messaging, use explicit from numbers or rely on weight-based Number Pool selection. Possible causes:

Number Pool is not enabled (Geomatch requires Number Pool)
Only one number in the pool (nothing to match against)
Sending with explicit from number (bypasses Number Pool entirely)

Solution: Ensure Number Pool is enabled with at least one weight > 0, verify multiple numbers are assigned to the profile, and omit from when sending to use the pool.

Next Steps

Learn about multi-number distribution and weights Maintain consistent sender numbers per recipient Complete messaging quickstart Full Messaging Profiles API details

Short Codes

Source: https://developers.telnyx.com/docs/messaging/messages/short-code.md

Short codes are 5- or 6-digit phone numbers designed for high-volume, application-to-person (A2P) messaging. They offer the highest throughput of any sender type — up to 1,000 messages per second — and are recognized by consumers as legitimate business numbers.

When to use short codes

High-volume alerts: Time-sensitive notifications to large audiences
Two-factor authentication: OTP delivery at scale with high deliverability
Marketing campaigns: Promotional messages with keyword opt-in (e.g., “Text JOIN to 12345”)
Voting and polling: Interactive SMS campaigns
Emergency notifications: Critical alerts requiring maximum throughput | Need | Better option | |------|--------------| | Low volume (< 1,000 msgs/day) | 10DLC Long Code | | Quick setup (no 8-12 week wait) | Toll-Free | | Two-way conversations | Long Code with Sticky Sender | | International messaging | Alphanumeric Sender ID | | Budget-conscious | 10DLC (lower per-message cost) |

Short code vs. other sender types

Feature	Short Code	Toll-Free	10DLC Long Code
Throughput	Up to 1,000 MPS	20 MPS	Varies by campaign
Setup time	8-12 weeks	1-2 weeks	Days
Cost	Higher (monthly lease + per-message)	Moderate	Lowest
Carrier trust	Highest	High	Varies by vetting score
MMS support	Yes	Yes	Yes
Two-way messaging	Yes (keyword-based)	Yes	Yes
Vanity numbers	Available	No	No

Provisioning process

Navigate to Short Code in Mission Control and submit your request. Choose your type:

Type	Description	Timeline
Random	Carrier-assigned number	8-10 weeks
Vanity	Memorable number you choose (e.g., 46835 = “GOULD”)	10-12 weeks

Vanity codes are subject to availability. Request early — popular combinations may already be taken. Provide details about your messaging program:

Company information — Legal name, address, contact
Use case description — What messages you’ll send
Message content samples — Representative examples
Volume estimates — Expected daily/monthly message volume
Opt-in flow — How users subscribe (web form, keyword, etc.)
Opt-out handling — STOP keyword support
Help response — HELP keyword response content Your application is submitted to each major US carrier for review and approval:

Carrier	Review process
AT&T	Reviews content, opt-in flow, and compliance
T-Mobile	Reviews content and message flow
Verizon	Reviews content and use case
US Cellular	Reviews content

This is the longest step. Carrier certification typically takes 8-12 weeks. Each carrier reviews independently — you may get approved by some carriers before others. Plan your launch timeline accordingly. Once approved by all target carriers, your short code appears under your messaging profile. Send messages using the same Messaging API as any other number type.

Sending messages from a short code

Once provisioned, send messages the same way as any other sender type:

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "12345",
    "to": "+15559876543",
    "text": "Your verification code is 847291. It expires in 5 minutes."
  }'

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.messages.send(
    from_="12345",
    to="+15559876543",
    text="Your verification code is 847291. It expires in 5 minutes.",
)

print(f"Message sent: {response.data.id}")

Node

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const response = await client.messages.send({
  from: '12345',
  to: '+15559876543',
  text: 'Your verification code is 847291. It expires in 5 minutes.',
});

console.log(`Message sent: ${response.data.id}`);

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.send_(
  from: "12345",
  to: "+15559876543",
  text: "Your verification code is 847291. It expires in 5 minutes."
)

puts "Message sent: #{response.id}"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Send(context.TODO(), telnyx.MessageSendParams{
    From: "12345",
    To:   "+15559876543",
    Text: "Your verification code is 847291. It expires in 5 minutes.",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Message sent: %s\n", response.Data.ID)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.MessageSendParams;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var params = MessageSendParams.builder()
            .from("12345")
            .to("+15559876543")
            .text("Your verification code is 847291. It expires in 5 minutes.")
            .build();

        var response = client.messages().send(params);
        System.out.println("Message sent: " + response.data().id());
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new MessageService();
var response = await service.SendAsync(new MessageSendOptions
{
    From = "12345",
    To = "+15559876543",
    Text = "Your verification code is 847291. It expires in 5 minutes."
});

Console.WriteLine($"Message sent: {response.Data.Id}");

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::Create([
    'from' => '12345',
    'to' => '+15559876543',
    'text' => 'Your verification code is 847291. It expires in 5 minutes.',
]);

echo "Message sent: {$response->id}\n";

Short codes use ASCII 7-bit encoding by default (same character limits as GSM-7). See Message Encoding for details.

Automated responses

Short codes must handle standard keywords to pass carrier certification. Telnyx manages these automatically.

Required keywords

Keyword	Purpose	Telnyx handling
STOP (and UNSUBSCRIBE, END, QUIT, CANCEL)	Opt-out	Automatic — user is blocked from receiving messages
HELP (and INFO)	Help/support info	Automatic — sends your configured help message
Campaign keyword	Campaign opt-in	Automatic — sends your configured keyword response

Customizing responses

After carrier certification, you can customize the HELP and campaign keyword responses: Configure a custom help message that includes:

Your business name
What messages the user is subscribed to
How to get support (phone number or email)
How to opt out

Example:

Acme Corp: You're subscribed to order updates. For help, call 1-800-555-0123
or email support@acme.com. Reply STOP to unsubscribe. Msg&data rates may apply.

When a user texts your campaign keyword (e.g., “JOIN”), they receive a confirmation message. Example:

Welcome to Acme Corp alerts! You'll receive order updates and promotions.
Reply HELP for help, STOP to cancel. Msg&data rates may apply. ~4 msgs/month.

After certification, you can disable automatic responses for HELP and campaign keywords to handle them yourself via webhook. Contact support@telnyx.com to request this change. STOP responses cannot be disabled. Opt-out handling is managed at the carrier level. Once a user opts out, they are blocked from receiving messages — you cannot send a custom opt-out confirmation.

Use case examples

Keyword: N/A (API-triggered) Flow: User initiates login → your app sends OTP via short code → user enters code

Your Acme verification code is 847291. It expires in 5 minutes.
If you didn't request this, ignore this message.

Why short code: Highest deliverability, fastest delivery, trusted by carriers. Keyword: JOIN Flow: User texts JOIN to 12345 → receives welcome message → gets promotional messages

Welcome msg: Acme Corp: Thanks for joining! Get exclusive deals and updates.
Reply HELP for help, STOP to cancel. Msg&data rates may apply. ~4 msgs/month.

Promo msg: Acme Flash Sale! 30% off all items today only. Shop now: https://acme.com/sale
Reply STOP to opt out.

Keyword: ALERT Flow: User opts in → receives critical alerts (weather, school closings, etc.)

ALERT: Severe thunderstorm warning for Springfield County until 8 PM.
Seek shelter immediately. Updates at https://acme.com/alerts

Why short code: Maximum throughput (1,000 MPS) for time-critical mass notifications.

Carrier certification requirements

Failing to meet these requirements will delay or prevent certification. Prepare these items before submitting your application.

Requirement	Details
Opt-in mechanism	Clear, documented method for users to subscribe (web form, keyword, paper form)
Opt-in disclosure	Users must know what they’re subscribing to, message frequency, and that rates may apply
Opt-out support	Must honor STOP and similar keywords immediately
Help support	Must respond to HELP with business name, support contact, and opt-out instructions
Message frequency	Must disclose expected message frequency at opt-in
Content compliance	Message content must match the registered use case
Privacy policy	Published privacy policy covering SMS data collection
Terms of service	Published terms covering messaging program

Compare short codes, toll-free, long codes, and alphanumeric sender IDs. Short code throughput limits and queuing behavior. Customize opt-in and opt-out behavior. Understand ASCII 7-bit encoding used by short codes.

Hosted SMS

Source: https://developers.telnyx.com/docs/messaging/messages/hosted-sms.md

Hosted SMS lets you add messaging capabilities to phone numbers that stay with your current voice provider. Your existing voice service continues uninterrupted — Telnyx handles only the SMS and MMS routing. This is ideal for:

Landline numbers that need texting capabilities
Business numbers where you want to keep your voice provider but add programmable messaging
Gradual migration — test Telnyx messaging before a full port

Hosting a number is not the same as porting. Your voice service stays with your current provider. Only SMS/MMS traffic routes through Telnyx.

How it works

Step	What happens	Timeline
1. Eligibility check	Verify your numbers can be hosted	Instant
2. Create order	Submit a hosted SMS order	Instant
3. Verify ownership	Confirm you own the numbers via SMS code	5 minutes
4. Upload documents	Submit LOA and recent provider bill	Instant
5. Telnyx review	Our team reviews and activates	1-3 business days

Step 1: Check number eligibility

Not all numbers can be hosted. Check eligibility before creating an order.

curl

curl -X POST https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "phone_numbers": ["+13125550001", "+13125550002"]
  }'

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check",
    headers=headers,
    json={"phone_numbers": ["+13125550001", "+13125550002"]},
)
results = response.json()["phone_numbers"]
for num in results:
    status = "✓" if num["eligible"] else "✗"
    print(f"{status} {num['phone_number']}: {num['detail']}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
  'Content-Type': 'application/json',
};

const response = await axios.post(
  'https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check',
  { phone_numbers: ['+13125550001', '+13125550002'] },
  { headers }
);

response.data.phone_numbers.forEach((num) => {
  const status = num.eligible ? '✓' : '✗';
  console.log(`${status} ${num.phone_number}: ${num.detail}`);
});

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = { phone_numbers: ["+13125550001", "+13125550002"] }.to_json

response = http.request(request)
results = JSON.parse(response.body)["phone_numbers"]
results.each do |num|
  status = num["eligible"] ? "✓" : "✗"
  puts "#{status} #{num['phone_number']}: #{num['detail']}"
end

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func main() {
  data := map[string][]string{
    "phone_numbers": {"+13125550001", "+13125550002"},
  }
  body, _ := json.Marshal(data)
  req, _ := http.NewRequest("POST",
    "https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check",
    bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  numbers := result["phone_numbers"].([]interface{})
  for _, n := range numbers {
    num := n.(map[string]interface{})
    eligible := num["eligible"].(bool)
    symbol := "✗"
    if eligible {
      symbol = "✓"
    }
    fmt.Printf("%s %s: %s\n", symbol, num["phone_number"], num["detail"])
  }
}

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');

$data = ['phone_numbers' => ['+13125550001', '+13125550002']];

$ch = curl_init('https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($data),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($response['phone_numbers'] as $num) {
    $status = $num['eligible'] ? '✓' : '✗';
    echo "{$status} {$num['phone_number']}: {$num['detail']}\n";
}

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var apiKey = Environment.GetEnvironmentVariable("TELNYX_API_KEY");
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

var data = new { phone_numbers = new[] { "+13125550001", "+13125550002" } };
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check",
    content);
var result = await response.Content.ReadAsStringAsync();

using var doc = JsonDocument.Parse(result);
foreach (var num in doc.RootElement.GetProperty("phone_numbers").EnumerateArray())
{
    var eligible = num.GetProperty("eligible").GetBoolean();
    var symbol = eligible ? "✓" : "✗";
    Console.WriteLine($"{symbol} {num.GetProperty("phone_number")}: {num.GetProperty("detail")}");
}

The Portal automatically checks eligibility when you enter numbers during order creation (Step 2).

Eligibility statuses

Status	Description	Action
`eligible`	Number can be hosted	Proceed with order
`number_is_not_a_us_number`	Only US numbers supported	Use a US number
`number_can_not_be_wireless`	Wireless numbers not supported	Use a landline or VoIP number
`number_can_not_be_in_telnyx`	Already on Telnyx platform	No hosting needed — number already works
`number_can_not_hosted_with_a_telnyx_subscriber`	Already hosted by another Telnyx user	Contact support
`number_can_not_be_active_in_your_account`	Active in your account already	Check your number inventory
`number_is_not_a_valid_routing_number`	Invalid routing number	Verify the number with your provider
`number_is_not_in_e164_format`	Wrong format	Use E.164: `+1` followed by 10 digits
`billing_account_check_failed`	Billing issue	Check your account billing status
`billing_account_is_abolished`	Account closed	Contact support

Step 2: Create a hosted SMS order

curl

curl -X POST https://api.telnyx.com/v2/messaging_hosted_number_orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID",
    "phone_numbers": ["+13125550001"]
  }'

Python

response = requests.post(
    "https://api.telnyx.com/v2/messaging_hosted_number_orders",
    headers=headers,
    json={
        "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID",
        "phone_numbers": ["+13125550001"],
    },
)
order = response.json()
print(f"Order ID: {order['id']}")
print(f"Status: {order['status']}")
for num in order["phone_numbers"]:
    print(f"  {num['phone_number']}: {num['status']}")

Node

const response = await axios.post(
  'https://api.telnyx.com/v2/messaging_hosted_number_orders',
  {
    messaging_profile_id: 'YOUR_MESSAGING_PROFILE_ID',
    phone_numbers: ['+13125550001'],
  },
  { headers }
);

const order = response.data;
console.log(`Order ID: ${order.id}`);
console.log(`Status: ${order.status}`);
order.phone_numbers.forEach((n) => {
  console.log(`  ${n.phone_number}: ${n.status}`);
});

Ruby

request = Net::HTTP::Post.new(URI("https://api.telnyx.com/v2/messaging_hosted_number_orders"))
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = {
  messaging_profile_id: "YOUR_MESSAGING_PROFILE_ID",
  phone_numbers: ["+13125550001"]
}.to_json

response = Net::HTTP.start("api.telnyx.com", 443, use_ssl: true) { |http| http.request(request) }
order = JSON.parse(response.body)
puts "Order ID: #{order['id']}"
puts "Status: #{order['status']}"

Numbers are created in pending status. They stay pending until you complete verification and document upload. Go to Numbers → Hosted SMS in Mission Control. Click Add New Order. Enter the phone number(s) you want to host in E.164 format (e.g., +13125550001). The system automatically checks eligibility. Choose the messaging profile for these numbers. Click Create Order to proceed to document upload.

Step 3: Verify phone number ownership

Prove you own the numbers by receiving and entering SMS verification codes.

3a. Request verification codes

curl

curl -X POST \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/verification_codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_method": "sms",
    "phone_numbers": ["+13125550001"]
  }'

Python

response = requests.post(
    f"https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/verification_codes",
    headers=headers,
    json={
        "verification_method": "sms",
        "phone_numbers": ["+13125550001"],
    },
)
# 201 = codes sent successfully
print(f"Codes sent: {response.status_code == 201}")

Node

const response = await axios.post(
  `https://api.telnyx.com/v2/messaging_hosted_number_orders/${orderId}/verification_codes`,
  {
    verification_method: 'sms',
    phone_numbers: ['+13125550001'],
  },
  { headers }
);
console.log(`Codes sent: ${response.status === 201}`);

3b. Submit verification codes

curl

curl -X POST \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/validation_codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_codes": [
      {"phone_number": "+13125550001", "code": "87643"}
    ]
  }'

Python

response = requests.post(
    f"https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/validation_codes",
    headers=headers,
    json={
        "verification_codes": [
            {"phone_number": "+13125550001", "code": "87643"},
        ],
    },
)
result = response.json()
for num in result["phone_numbers"]:
    print(f"{num['phone_number']}: {num['status']}")

Node

const response = await axios.post(
  `https://api.telnyx.com/v2/messaging_hosted_number_orders/${orderId}/validation_codes`,
  {
    verification_codes: [
      { phone_number: '+13125550001', code: '87643' },
    ],
  },
  { headers }
);

response.data.phone_numbers.forEach((n) => {
  console.log(`${n.phone_number}: ${n.status}`);
});

A successful verification returns verified status. The number status then changes to ownership_successful.

Step 4: Upload authorization documents

After verification, upload two PDF documents:

Letter of Authorization (LOA) — signed authorization to host the number
Recent bill — from your current voice provider showing the number

curl

curl -X POST \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/actions/file_upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --form "loa=@/path/to/loa.pdf" \
  --form "bill=@/path/to/bill.pdf"

Python

import requests

with open("loa.pdf", "rb") as loa, open("bill.pdf", "rb") as bill:
    response = requests.post(
        f"https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/actions/file_upload",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"loa": loa, "bill": bill},
    )
print(f"Upload status: {response.json()['status']}")

Node

const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('loa', fs.createReadStream('loa.pdf'));
form.append('bill', fs.createReadStream('bill.pdf'));

const response = await axios.post(
  `https://api.telnyx.com/v2/messaging_hosted_number_orders/${orderId}/actions/file_upload`,
  form,
  {
    headers: {
      ...form.getHeaders(),
      Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
    },
  }
);
console.log(`Upload status: ${response.data.status}`);

After upload, the Telnyx team reviews your order and activates the number(s). This typically takes 1-3 business days.

Check order status

curl

curl -s "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '{status, phone_numbers: [.phone_numbers[] | {phone_number, status}]}'

Python

response = requests.get(
    f"https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}",
    headers=headers,
)
order = response.json()
print(f"Order status: {order['status']}")
for num in order["phone_numbers"]:
    print(f"  {num['phone_number']}: {num['status']}")

Order statuses

Status	Meaning
`pending`	Order created, awaiting verification and documents
`loa_file_successful`	Documents uploaded successfully
`successful`	Order complete — numbers are active
`failed`	Activation failed (see failure statuses)
`deleted`	Order was cancelled

Webhook notifications

Hosted SMS orders trigger webhooks to your messaging profile’s configured webhook URL. Set up a handler to track order progress in real time.

Python

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/hosted-sms", methods=["POST"])
def hosted_sms_webhook():
    event = request.json["data"]
    event_type = event["event_type"]
    payload = event["payload"]

    order_id = payload["order_id"]
    order_status = payload["order_status"]

    print(f"Event: {event_type}")
    print(f"Order {order_id}: {order_status}")

    for num in payload.get("numbers", []):
        print(f"  {num['value']}: {num['status']}")

    # Handle specific events
    if order_status == "successful":
        print("Numbers are active! Ready to send messages.")
    elif order_status == "failed":
        print("Order failed. Check number statuses for details.")

    return "", 200

Node

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/hosted-sms', (req, res) => {
  const event = req.body.data;
  const { event_type, payload } = event;

  console.log(`Event: ${event_type}`);
  console.log(`Order ${payload.order_id}: ${payload.order_status}`);

  for (const num of payload.numbers || []) {
    console.log(`  ${num.value}: ${num.status}`);
  }

  if (payload.order_status === 'successful') {
    console.log('Numbers are active! Ready to send messages.');
  } else if (payload.order_status === 'failed') {
    console.log('Order failed. Check number statuses for details.');
  }

  res.sendStatus(200);
});

Webhook event types

Event	Triggered when
`messaging_hosted_numbers_orders.created`	Order is created
`messaging_hosted_numbers_orders.updated`	Status changes (verification, LOA upload, activation, failure)
`messaging_hosted_numbers_orders.deleted`	Order is deleted
`messaging_hosted_numbers_orders.internal_transfer_detected`	Order is classified as an internal transfer
`messaging_hosted_numbers_orders.internal_transfer_approval_requested`	Internal transfer approval requested from the losing account (72h window)
`messaging_hosted_numbers_orders.internal_transfer_approved`	Losing account approved the internal transfer
`messaging_hosted_numbers_orders.internal_transfer_rejected`	Losing account rejected the internal transfer, or the receiving account cancelled the order
`messaging_hosted_numbers_orders.internal_transfer_auto_approved`	Internal transfer auto-approved (72h window elapsed or bypass enabled)

Email and Portal notifications

You can also receive email notifications: Go to Advanced Features → Notifications and click New Profile. Click New Channel, select your profile, choose Email, and enter your address. Click New Settings, select Messaging Hosted SMS Activity, and link to your profile.

Troubleshooting failed orders

Cause: The losing carrier (your current voice provider) rejected the hosting request. Common reasons:

Number is under contract with restrictions on SMS routing changes
Provider doesn’t support hosted SMS arrangements
Account information mismatch between LOA and provider records

Fix:

Contact your voice provider to understand the rejection
Verify your LOA matches the account holder name exactly
Some carriers require you to call and authorize the SMS routing change

Cause: The number’s carrier does not support hosted SMS with Telnyx. Fix:

Consider porting the number fully to Telnyx instead
Contact Telnyx support to check if the carrier has been added since your last attempt

Cause: Specific number was rejected by the losing carrier while other numbers in the order may have succeeded. Fix:

Check if this specific number has different account ownership
Create a separate order for this number after resolving with your provider

Cause: The number is already hosted on Telnyx by another account. Fix:

If you own both accounts, remove the hosting from the other account first
If not, contact Telnyx support to resolve the conflict

Cause: The activation process timed out waiting for carrier response. Fix:

Create a new order for the same number
If it fails again, contact Telnyx support — the carrier may need manual intervention

Cause: The SMS verification code wasn’t delivered to the phone number. Fix:

Ensure the number can receive SMS (landlines may need the current provider to enable it)
Check if the number has any SMS blocking enabled
Request the code again — you can retry multiple times
If the number truly cannot receive SMS, contact Telnyx support for alternative verification

Cause: The Letter of Authorization didn’t meet requirements. Common issues:

LOA not signed
Name on LOA doesn’t match the voice provider account
LOA template is outdated

Fix:

Download the latest LOA template from Telnyx support
Ensure the authorized signer matches the account holder
Upload a new LOA via the API or Portal

Known limitation: Hosted numbers may not appear in the Portal number inventory. They are accessible via the API.

# List your hosted numbers
curl -s "https://api.telnyx.com/v2/messaging_hosted_number_orders" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data[] | select(.status == "successful")'

Failed order and number statuses reference

Order statuses

Status	Description
`carrier_rejected`	Losing carrier rejected the porting request
`failed`	Order closed — contact support
`ineligible_carrier`	Number’s carrier doesn’t support hosted SMS

Number statuses

Status	Description
`failed`	Number closed — contact support
`failed_carrier_rejected`	Losing carrier rejected this number
`failed_ineligible_carrier`	Number’s carrier doesn’t support hosted SMS
`failed_number_already_hosted`	Already hosted by another Telnyx user
`failed_number_not_found`	Number not found in routing database
`failed_timeout`	Activation timed out

Next steps

Transfer hosted numbers between Telnyx accounts. Configure webhooks, opt-out settings, and number assignment. Start sending SMS and MMS once your hosted numbers are active. Compare hosted SMS with other number types (10DLC, toll-free, short code).

Internal Transfer

Source: https://developers.telnyx.com/docs/messaging/messages/hosted-sms/internal-transfer.md

Overview

Internal Hosted SMS Transfer allows you to move messaging-enabled numbers between two Telnyx accounts without going through the standard carrier porting process. This is useful when:

You manage multiple Telnyx accounts (e.g., separate voice and messaging organizations)
You need to consolidate numbers under a single account
You’re migrating messaging services from one Telnyx organization to another

Internal transfers are automatically detected when the number(s) in your hosted SMS order already belong to another Telnyx account. No additional configuration is needed — the system handles this automatically.

How it works

Internal transfers follow a modified version of the standard Hosted SMS flow with an additional approval step to protect the current number owner. The receiving account creates a standard hosted SMS order with the number(s) to transfer. The system automatically detects that the number belongs to another Telnyx account and flags the order as an internal transfer. The account that currently owns the number receives an email and portal notification with the transfer request details, including an approval link. The current owner has 72 hours to approve or reject the transfer. If no action is taken, the transfer is automatically approved after the window expires. After approval, the receiving account must complete phone number ownership verification — the same verification code process used in standard hosted SMS orders. Upload the Letter of Authorization (LOA) and the most recent bill, just like a standard hosted SMS order. Once approved, verified, and documents are submitted, the Telnyx team reviews and activates the transfer. The number’s user_id is updated to the new account, and any existing 10DLC campaign associations on the number are removed. When a number is internally transferred, any 10DLC campaign registrations associated with that number are automatically deleted. The receiving account must re-register the number with a campaign after the transfer completes.

Create an internal transfer order

Create a hosted SMS order using the same endpoint as a standard order. The system automatically detects if the number belongs to another Telnyx account.

cURL

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "phone_numbers": ["+13125550001"]
  }' \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders"

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"

order = telnyx.MessagingHostedNumberOrder.create(
    messaging_profile_id="16fd2706-8baf-433b-82eb-8c7fada847da",
    phone_numbers=["+13125550001"]
)
print(order)

Node.js

const telnyx = require('telnyx')('YOUR_API_KEY');

const order = await telnyx.messagingHostedNumberOrders.create({
  messaging_profile_id: '16fd2706-8baf-433b-82eb-8c7fada847da',
  phone_numbers: ['+13125550001']
});
console.log(order.data);

Ruby

require 'telnyx'

Telnyx.api_key = 'YOUR_API_KEY'

order = Telnyx::MessagingHostedNumberOrder.create(
  messaging_profile_id: '16fd2706-8baf-433b-82eb-8c7fada847da',
  phone_numbers: ['+13125550001']
)
puts order

Java

import com.telnyx.sdk.*;
import com.telnyx.sdk.api.HostedNumbersApi;

ApiClient client = new ApiClient();
client.setApiKey("YOUR_API_KEY");

HostedNumbersApi api = new HostedNumbersApi(client);
CreateHostedNumberOrderRequest request = new CreateHostedNumberOrderRequest()
    .messagingProfileId("16fd2706-8baf-433b-82eb-8c7fada847da")
    .addPhoneNumbersItem("+13125550001");

HostedNumberOrderResponse response = api.createHostedNumberOrder(request);
System.out.println(response);

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey("YOUR_API_KEY");

var service = new MessagingHostedNumberOrderService();
var options = new NewMessagingHostedNumberOrder
{
    MessagingProfileId = "16fd2706-8baf-433b-82eb-8c7fada847da",
    PhoneNumbers = new List { "+13125550001" }
};
var order = await service.CreateAsync(options);
Console.WriteLine(order);

PHP

require_once 'vendor/autoload.php';

Telnyx\Telnyx::setApiKey('YOUR_API_KEY');

$order = Telnyx\MessagingHostedNumberOrder::create([
    'messaging_profile_id' => '16fd2706-8baf-433b-82eb-8c7fada847da',
    'phone_numbers' => ['+13125550001']
]);
echo $order;

package main

import (
    "context"
    "fmt"
    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient("YOUR_API_KEY")

    order, err := client.MessagingHostedNumberOrders.Create(
        context.Background(),
        &telnyx.MessagingHostedNumberOrderParams{
            MessagingProfileID: "16fd2706-8baf-433b-82eb-8c7fada847da",
            PhoneNumbers:       []string{"+13125550001"},
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(order)
}

Example response

{
  "record_type": "messaging_hosted_number_order",
  "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
  "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  "status": "pending",
  "phone_numbers": [
    {
      "record_type": "messaging_hosted_number",
      "id": "bda67701-2c08-47ba-8242-f6e6b235cca8",
      "phone_number": "+13125550001",
      "status": "pending"
    }
  ]
}

The response looks identical to a standard hosted SMS order. The internal transfer detection happens server-side — the current owner of the number will receive a notification automatically.

Approve or reject a transfer

The current number owner can approve or reject the transfer using the link in their notification email, or via the API.

Approve

curl -X POST \
  --header "Authorization: Bearer CURRENT_OWNER_API_KEY" \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/approve?token=APPROVAL_TOKEN"

Reject

curl -X POST \
  --header "Authorization: Bearer CURRENT_OWNER_API_KEY" \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{order_id}/reject?token=APPROVAL_TOKEN"

The token parameter is included in the notification sent to the current owner. It is a one-time use token that expires after 72 hours. If the token expires without action, the transfer is automatically approved.

Decision	Result
Approved	Transfer proceeds. Receiving account must complete 2FA verification and document upload.
Rejected	Order is marked as `failed`. The receiving account is notified.
No action (72h)	Transfer is auto-approved. Receiving account must still complete verification.

Complete the transfer

After the transfer is approved (either explicitly or via auto-approval), the receiving account must:

Verify ownership — Send and validate verification codes for the number(s), identical to the standard verification process.
Upload documents — Submit the LOA and bill via the file upload endpoint.
Wait for activation — The Telnyx team reviews and activates the transfer.

Webhook notifications

Internal transfers generate the same webhook events as standard hosted SMS orders (.created, .updated, .deleted), plus five lifecycle-specific events that let you track classification, approval, and auto-approval separately from generic order updates.

Lifecycle event reference

Event	Fired when
`messaging_hosted_numbers_orders.internal_transfer_detected`	Order is classified as an internal transfer (fires on order creation, immediately after `.created`)
`messaging_hosted_numbers_orders.internal_transfer_approval_requested`	Approval was requested from the losing account and the 72h window has started. Includes `approval_deadline`
`messaging_hosted_numbers_orders.internal_transfer_approved`	Losing account clicked Approve
`messaging_hosted_numbers_orders.internal_transfer_rejected`	Losing account clicked Reject, or the receiving account cancelled/deleted the order
`messaging_hosted_numbers_orders.internal_transfer_auto_approved`	72h window elapsed with no response (background auto-approval), or the receiving account was on the bypass-approval allowlist

Detected (fires after `.created`)

{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.internal_transfer_detected",
    "payload": {
      "order_status": "pending",
      "numbers": [{"status": "pending", "value": "+13125550001"}]
    }
  }
}

Approval requested

{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.internal_transfer_approval_requested",
    "payload": {
      "order_status": "pending",
      "numbers": [{"status": "pending", "value": "+13125550001"}],
      "decision": "pending",
      "approval_deadline": 1714521600
    }
  }
}

Approved

{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.internal_transfer_approved",
    "payload": {
      "order_status": "pending",
      "decision": "approved"
    }
  }
}

Rejected

{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.internal_transfer_rejected",
    "payload": {
      "order_status": "failed",
      "decision": "rejected"
    }
  }
}

Auto-approved

{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.internal_transfer_auto_approved",
    "payload": {
      "order_status": "pending",
      "decision": "approved"
    }
  }
}

Transfer activated

Once approved, activation emits the standard .updated event when numbers become successful:

{
  "data": {
    "event_type": "messaging_hosted_numbers_orders.updated",
    "payload": {
      "order_status": "successful",
      "numbers": [{"status": "successful", "value": "+13125550001"}]
    }
  }
}

Key differences from standard Hosted SMS

Aspect	Standard Hosted SMS	Internal Transfer
Source	External carrier	Another Telnyx account
Detection	Manual	Automatic (system detects Telnyx-owned numbers)
Approval	Not required	Required from current owner (72h window)
Auto-approval	N/A	Yes, after 72 hours with no response
Campaign cleanup	N/A	10DLC campaigns automatically removed
Carrier porting	Yes (NNID override)	No (direct `user_id` update)
2FA verification	Required	Required (after approval)
LOA + Bill	Required	Required

Troubleshooting

If the 72-hour window passed without action, the transfer is automatically approved. Contact Telnyx Support immediately — the transfer may be reversible if activation hasn’t completed. Ensure the number can receive SMS messages. For internal transfers, the verification code is sent to the number being transferred. If the number is a landline or doesn’t have SMS capabilities on the current account, contact Telnyx Support for assistance. Check the order status for specific error details. Common causes include:

The number was deleted or deactivated on the source account before activation
The number is already hosted with another Telnyx subscriber
Billing issues on the receiving account

Use the Get Order endpoint to check the current status. This is expected behavior. When a number transfers between accounts, existing campaign associations are automatically cleaned up. Register the number with a new campaign on the receiving account after the transfer completes. See 10DLC Campaign Registration for details.

Opt-In/Out Management

Source: https://developers.telnyx.com/docs/messaging/messages/advanced-opt-in-out.md

Advanced Opt-In/Out lets you customize keyword triggers and auto-responses on your messaging profile. Configure country-specific responses, custom keywords, and track opt-out behavior via webhooks — all while maintaining CTIA & TCPA compliance.

Default behavior

Without custom configuration, Telnyx handles standard opt-in/out keywords automatically: These keywords create a block rule preventing further messages to the recipient:

Keyword	Action
`STOP`	Block messages
`STOPALL`	Block messages
`STOP ALL`	Block messages
`UNSUBSCRIBE`	Block messages
`CANCEL`	Block messages
`END`	Block messages
`QUIT`	Block messages
These keywords remove an existing block rule, allowing messages to resume:

Keyword	Action
`START`	Remove block
`UNSTOP`	Remove block

Block rules operate at the messaging profile level. If a user opts out from one number on your profile, they’re opted out from all numbers on that profile. When you attempt to message a blocked recipient, the API returns:

{
  "errors": [
    {
      "code": "40300",
      "title": "Blocked due to STOP message",
      "detail": "Messages cannot be sent from '{from}' to '{to}' due to an existing block rule."
    }
  ]
}

Create custom auto-responses

Configure custom keyword responses for opt-in, opt-out, and help messages:

curl

# Create a custom opt-in auto-response
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "start",
    "keywords": ["JOIN", "SUBSCRIBE", "YES"],
    "resp_text": "Welcome to Acme alerts! You'\''ll receive up to 4 msgs/month. Reply HELP for help, STOP to cancel. Msg&data rates may apply.",
    "country_code": "US"
  }'

# Create a custom HELP response
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "help",
    "keywords": ["HELP", "INFO"],
    "resp_text": "Acme Corp: For support call 1-800-555-0123 or email help@acme.com. Reply STOP to opt out. Msg&data rates may apply.",
    "country_code": "US"
  }'

# Create a custom opt-out response
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "stop",
    "keywords": ["STOP", "QUIT", "CANCEL"],
    "resp_text": "You have been unsubscribed from Acme alerts. Reply START to resubscribe.",
    "country_code": "US"
  }'

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
PROFILE_ID = "your_messaging_profile_id"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Custom opt-in response
response = requests.post(
    f"https://api.telnyx.com/v2/messaging_profiles/{PROFILE_ID}/autoresp_configs",
    headers=headers,
    json={
        "op": "start",
        "keywords": ["JOIN", "SUBSCRIBE", "YES"],
        "resp_text": (
            "Welcome to Acme alerts! You'll receive up to 4 msgs/month. "
            "Reply HELP for help, STOP to cancel. Msg&data rates may apply."
        ),
        "country_code": "US",
    },
)
print(f"Opt-in config created: {response.json()['data']['id']}")

# Custom HELP response
response = requests.post(
    f"https://api.telnyx.com/v2/messaging_profiles/{PROFILE_ID}/autoresp_configs",
    headers=headers,
    json={
        "op": "help",
        "keywords": ["HELP", "INFO"],
        "resp_text": (
            "Acme Corp: For support call 1-800-555-0123 or email help@acme.com. "
            "Reply STOP to opt out. Msg&data rates may apply."
        ),
        "country_code": "US",
    },
)
print(f"Help config created: {response.json()['data']['id']}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
  'Content-Type': 'application/json',
};
const profileId = 'your_messaging_profile_id';
const baseUrl = `https://api.telnyx.com/v2/messaging_profiles/${profileId}/autoresp_configs`;

// Custom opt-in response
const optIn = await axios.post(baseUrl, {
  op: 'start',
  keywords: ['JOIN', 'SUBSCRIBE', 'YES'],
  resp_text: "Welcome to Acme alerts! You'll receive up to 4 msgs/month. Reply HELP for help, STOP to cancel.",
  country_code: 'US',
}, { headers });
console.log(`Opt-in config: ${optIn.data.data.id}`);

// Custom HELP response
const help = await axios.post(baseUrl, {
  op: 'help',
  keywords: ['HELP', 'INFO'],
  resp_text: 'Acme Corp: For support call 1-800-555-0123. Reply STOP to opt out.',
  country_code: 'US',
}, { headers });
console.log(`Help config: ${help.data.data.id}`);

Ruby

require "net/http"
require "json"
require "uri"

api_key = ENV["TELNYX_API_KEY"]
profile_id = "your_messaging_profile_id"
base_url = "https://api.telnyx.com/v2/messaging_profiles/#{profile_id}/autoresp_configs"

def create_config(url, api_key, data)
  uri = URI(url)
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  request = Net::HTTP::Post.new(uri)
  request["Authorization"] = "Bearer #{api_key}"
  request["Content-Type"] = "application/json"
  request.body = data.to_json
  response = http.request(request)
  JSON.parse(response.body)
end

# Opt-in
result = create_config(base_url, api_key, {
  op: "start",
  keywords: ["JOIN", "SUBSCRIBE", "YES"],
  resp_text: "Welcome to Acme alerts! Reply HELP for help, STOP to cancel.",
  country_code: "US"
})
puts "Opt-in config: #{result['data']['id']}"

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func createAutoResponse(profileID string, data map[string]interface{}) {
  url := fmt.Sprintf("https://api.telnyx.com/v2/messaging_profiles/%s/autoresp_configs", profileID)
  body, _ := json.Marshal(data)
  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  data2 := result["data"].(map[string]interface{})
  fmt.Printf("Config created: %s\n", data2["id"])
}

func main() {
  profileID := "your_messaging_profile_id"

  createAutoResponse(profileID, map[string]interface{}{
    "op":           "start",
    "keywords":     []string{"JOIN", "SUBSCRIBE", "YES"},
    "resp_text":    "Welcome to Acme alerts! Reply HELP for help, STOP to cancel.",
    "country_code": "US",
  })
}

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');
$profileId = 'your_messaging_profile_id';
$url = "https://api.telnyx.com/v2/messaging_profiles/{$profileId}/autoresp_configs";

function createAutoResponse(string $url, string $apiKey, array $data): array
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer {$apiKey}",
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($data),
    ]);
    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $response;
}

// Opt-in
$result = createAutoResponse($url, $apiKey, [
    'op' => 'start',
    'keywords' => ['JOIN', 'SUBSCRIBE', 'YES'],
    'resp_text' => "Welcome to Acme alerts! Reply HELP for help, STOP to cancel.",
    'country_code' => 'US',
]);
echo "Opt-in config: {$result['data']['id']}\n";

Operation types

Operation (`op`)	Purpose	Default keywords
`start`	Opt-in — removes block rule	START, UNSTOP
`stop`	Opt-out — creates block rule	STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT
`help`	Help — sends info response	HELP
Custom	Any custom keyword response	(none)

Country-specific auto-responses

Configure different responses per country using ISO 3166-1 alpha-2 codes. This enables localized language support:

curl

# English (US)
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "stop",
    "keywords": ["STOP"],
    "resp_text": "You have been unsubscribed. Reply START to resubscribe.",
    "country_code": "US"
  }'

# Spanish (Mexico)
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "stop",
    "keywords": ["PARAR", "DETENER"],
    "resp_text": "Te has dado de baja. Responde INICIO para volver a suscribirte.",
    "country_code": "MX"
  }'

# French (Canada)
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "stop",
    "keywords": ["ARRET", "ARRETER"],
    "resp_text": "Vous êtes désabonné. Répondez DEBUT pour vous réabonner.",
    "country_code": "CA"
  }'

# UK English
curl -X POST \
  https://api.telnyx.com/v2/messaging_profiles/{profile_id}/autoresp_configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "op": "start",
    "keywords": ["START"],
    "resp_text": "You are now subscribed to receive messages from Acme. Reply STOP to opt out.",
    "country_code": "GB"
  }'

The feature is language agnostic — you can use keywords and responses in any language. The country_code field determines which auto-response applies based on the sender’s number origin.

Track opt-out behavior via webhooks

When a user sends an opt-in, opt-out, or help keyword, the inbound message webhook includes an autoresponse_type field:

{
  "data": {
    "event_type": "message.received",
    "payload": {
      "autoresponse_type": "STOP",
      "from": {
        "phone_number": "+15559876543"
      },
      "text": "STOP",
      "to": [
        {
          "phone_number": "+15551234567"
        }
      ]
    }
  }
}

Handle opt-out webhooks

Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/messaging", methods=["POST"])
def handle_webhook():
    data = request.json["data"]

    if data["event_type"] != "message.received":
        return jsonify({"status": "ignored"}), 200

    payload = data["payload"]
    autoresponse_type = payload.get("autoresponse_type")
    phone = payload["from"]["phone_number"]

    if autoresponse_type == "STOP":
        # User opted out — update your database
        db.execute(
            "UPDATE subscribers SET opted_out = TRUE, opted_out_at = NOW() "
            "WHERE phone = %s",
            (phone,),
        )
        print(f"User {phone} opted out")

    elif autoresponse_type == "START":
        # User opted back in
        db.execute(
            "UPDATE subscribers SET opted_out = FALSE "
            "WHERE phone = %s",
            (phone,),
        )
        print(f"User {phone} opted back in")

    elif autoresponse_type == "HELP":
        # User requested help — log for support
        print(f"User {phone} requested help")

    return jsonify({"status": "ok"}), 200

Node

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/messaging', async (req, res) => {
  const { data } = req.body;

  if (data.event_type !== 'message.received') {
    return res.json({ status: 'ignored' });
  }

  const { autoresponse_type } = data.payload;
  const phone = data.payload.from.phone_number;

  switch (autoresponse_type) {
    case 'STOP':
      await db.query(
        'UPDATE subscribers SET opted_out = TRUE WHERE phone = $1',
        [phone]
      );
      console.log(`User ${phone} opted out`);
      break;

    case 'START':
      await db.query(
        'UPDATE subscribers SET opted_out = FALSE WHERE phone = $1',
        [phone]
      );
      console.log(`User ${phone} opted back in`);
      break;

    case 'HELP':
      console.log(`User ${phone} requested help`);
      break;
  }

  res.json({ status: 'ok' });
});

The autoresponse_type field is also available in your SMS Logs via Detail Record Search reporting.

Limitations

START, STOP, and HELP are reserved keywords for their respective operations and cannot be reassigned to different operations. You can add additional keywords to each operation, but the defaults always remain active. Default operations (start, stop, help) require a minimum 20 characters for the auto-response message. This ensures compliance with carrier requirements. Each auto-response configuration supports a maximum of 20 trigger keywords. Toll-free numbers have a separate carrier-level opt-out system that Telnyx cannot customize or remove. When a user texts STOP to a toll-free number:

The carrier sends its own auto-reply:

NETWORK MSG: You replied with the word “stop” which blocks all texts sent from this number. Text back “unstop” to receive messages again.

Your custom STOP response is also sent (if configured)
The carrier block is applied independently of Telnyx’s block rule

When a user texts START or UNSTOP:

NETWORK MSG: You have replied “unstop” and will begin receiving messages again from this number.

You cannot prevent the carrier’s NETWORK MSG responses on toll-free numbers. Design your custom responses to complement (not contradict) these messages. Block rules apply at the messaging profile level, not the individual number level. If a user opts out from any number on your profile, they’re blocked from all numbers on that profile. To manage separate opt-out lists for different programs, use separate messaging profiles.

Configure the messaging profile that manages your opt-in/out rules. Set up webhooks to receive opt-in/out events. Short code keyword handling and carrier certification. Toll-free number verification and compliance.

Number Configuration

Source: https://developers.telnyx.com/docs/messaging/messages/phone-number-configuration.md

Before a phone number can send or receive messages through Telnyx, it must be assigned to a messaging profile and have messaging enabled. This guide covers the complete workflow — from purchasing a number to configuring it for messaging, assigning it to profiles, and troubleshooting common issues.

Prerequisites

A Telnyx account with API access
Your API key
At least one messaging profile created

Overview

Every phone number used for messaging needs:

A messaging profile — Controls webhook URLs, inbound settings, and features like number pool or sticky sender
Messaging enabled — The number must have messaging capabilities activated
Regulatory compliance — Depending on the number type, you may need 10DLC registration or toll-free verification

Step 1: List messaging-capable numbers

Find numbers on your account that support messaging:

curl

curl -X GET "https://api.telnyx.com/v2/messaging_phone_numbers?page[size]=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.get(
    "https://api.telnyx.com/v2/messaging_phone_numbers",
    headers=headers,
    params={"page[size]": 25},
)
numbers = response.json()
for num in numbers.get("data", []):
    profile = num.get("messaging_profile_id") or "unassigned"
    print(f"{num['phone_number']} — profile: {profile}, features: {num.get('features', {})}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
  'Content-Type': 'application/json',
};

const { data: numbers } = await axios.get(
  'https://api.telnyx.com/v2/messaging_phone_numbers',
  { headers, params: { 'page[size]': 25 } }
);

numbers.data.forEach(num => {
  const profile = num.messaging_profile_id || 'unassigned';
  console.log(`${num.phone_number} — profile: ${profile}`);
});

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.telnyx.com/v2/messaging_phone_numbers?page[size]=25")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"

response = http.request(request)
numbers = JSON.parse(response.body)
numbers["data"].each do |num|
  profile = num["messaging_profile_id"] || "unassigned"
  puts "#{num['phone_number']} — profile: #{profile}"
end

package main

import (
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  req, _ := http.NewRequest("GET",
    "https://api.telnyx.com/v2/messaging_phone_numbers?page[size]=25", nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    fmt.Println("Error:", err)
    return
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  var result map[string]interface{}
  json.Unmarshal(body, &result)

  for _, num := range result["data"].([]interface{}) {
    n := num.(map[string]interface{})
    profile := n["messaging_profile_id"]
    if profile == nil {
      profile = "unassigned"
    }
    fmt.Printf("%s — profile: %v\n", n["phone_number"], profile)
  }
}

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');

$ch = curl_init('https://api.telnyx.com/v2/messaging_phone_numbers?page[size]=25');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$numbers = json_decode($response, true);
foreach ($numbers['data'] as $num) {
    $profile = $num['messaging_profile_id'] ?? 'unassigned';
    echo "{$num['phone_number']} — profile: {$profile}\n";
}

.NET

using System.Net.Http.Headers;
using System.Text.Json;

var apiKey = Environment.GetEnvironmentVariable("TELNYX_API_KEY");
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

var response = await client.GetAsync(
    "https://api.telnyx.com/v2/messaging_phone_numbers?page%5Bsize%5D=25"
);
var body = await response.Content.ReadAsStringAsync();
var doc = JsonDocument.Parse(body);

foreach (var num in doc.RootElement.GetProperty("data").EnumerateArray())
{
    var phone = num.GetProperty("phone_number").GetString();
    var profile = num.TryGetProperty("messaging_profile_id", out var p) && p.ValueKind != JsonValueKind.Null
        ? p.GetString() : "unassigned";
    Console.WriteLine($"{phone} — profile: {profile}");
}

Java

import java.net.http.*;
import java.net.URI;

String apiKey = System.getenv("TELNYX_API_KEY");

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.telnyx.com/v2/messaging_phone_numbers?page%5Bsize%5D=25"))
    .header("Authorization", "Bearer " + apiKey)
    .GET()
    .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Step 2: Assign a number to a messaging profile

Link a phone number to a messaging profile to configure its webhook URLs and messaging behavior.

curl

curl -X PATCH "https://api.telnyx.com/v2/messaging_phone_numbers/+15551234567" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": "400174af-0a13-4e28-b4f5-example12345"
  }'

Python

phone_number = "+15551234567"
profile_id = "400174af-0a13-4e28-b4f5-example12345"

response = requests.patch(
    f"https://api.telnyx.com/v2/messaging_phone_numbers/{phone_number}",
    headers=headers,
    json={"messaging_profile_id": profile_id},
)
result = response.json()
print(f"Assigned {phone_number} to profile {result['data']['messaging_profile_id']}")

Node

const phoneNumber = '+15551234567';
const profileId = '400174af-0a13-4e28-b4f5-example12345';

const { data: result } = await axios.patch(
  `https://api.telnyx.com/v2/messaging_phone_numbers/${encodeURIComponent(phoneNumber)}`,
  { messaging_profile_id: profileId },
  { headers }
);
console.log(`Assigned ${phoneNumber} to profile ${result.data.messaging_profile_id}`);

Ruby

phone_number = "+15551234567"
profile_id = "400174af-0a13-4e28-b4f5-example12345"

uri = URI("https://api.telnyx.com/v2/messaging_phone_numbers/#{CGI.escape(phone_number)}")
request = Net::HTTP::Patch.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = { messaging_profile_id: profile_id }.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts "Assigned #{phone_number} to profile #{result['data']['messaging_profile_id']}"

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
)

func main() {
  phoneNumber := "+15551234567"
  profileID := "400174af-0a13-4e28-b4f5-example12345"

  body, _ := json.Marshal(map[string]string{
    "messaging_profile_id": profileID,
  })

  encoded := url.PathEscape(phoneNumber)
  req, _ := http.NewRequest("PATCH",
    "https://api.telnyx.com/v2/messaging_phone_numbers/"+encoded,
    bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    fmt.Println("Error:", err)
    return
  }
  defer resp.Body.Close()

  result, _ := io.ReadAll(resp.Body)
  fmt.Printf("Result: %s\n", result)
}

PHP

<?php
$phoneNumber = '+15551234567';
$profileId = '400174af-0a13-4e28-b4f5-example12345';
$encoded = urlencode($phoneNumber);

$ch = curl_init("https://api.telnyx.com/v2/messaging_phone_numbers/{$encoded}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv('TELNYX_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['messaging_profile_id' => $profileId]),
]);

$response = curl_exec($ch);
curl_close($ch);
echo "Result: {$response}\n";

.NET

var phoneNumber = Uri.EscapeDataString("+15551234567");
var profileId = "400174af-0a13-4e28-b4f5-example12345";

var content = new StringContent(
    JsonSerializer.Serialize(new { messaging_profile_id = profileId }),
    Encoding.UTF8,
    "application/json"
);

var request = new HttpRequestMessage(new HttpMethod("PATCH"),
    $"https://api.telnyx.com/v2/messaging_phone_numbers/{phoneNumber}")
{
    Content = content
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

var response = await client.SendAsync(request);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Result: {result}");

Java

import java.net.http.*;
import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

String phoneNumber = URLEncoder.encode("+15551234567", StandardCharsets.UTF_8);
String profileId = "400174af-0a13-4e28-b4f5-example12345";
String body = String.format("{\"messaging_profile_id\":\"%s\"}", profileId);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.telnyx.com/v2/messaging_phone_numbers/" + phoneNumber))
    .header("Authorization", "Bearer " + System.getenv("TELNYX_API_KEY"))
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Result: " + response.body());

Step 3: Retrieve number configuration

Check the current messaging configuration for a specific number:

curl

curl -X GET "https://api.telnyx.com/v2/messaging_phone_numbers/+15551234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.get(
    f"https://api.telnyx.com/v2/messaging_phone_numbers/{phone_number}",
    headers=headers,
)
config = response.json()["data"]
print(f"Number: {config['phone_number']}")
print(f"Profile: {config['messaging_profile_id']}")
print(f"Features: {config.get('features', {})}")
print(f"Health: {config.get('health', {})}")

Node

const { data: config } = await axios.get(
  `https://api.telnyx.com/v2/messaging_phone_numbers/${encodeURIComponent(phoneNumber)}`,
  { headers }
);
console.log('Number:', config.data.phone_number);
console.log('Profile:', config.data.messaging_profile_id);
console.log('Features:', config.data.features);

Response fields

Field	Description
`phone_number`	The E.164 formatted phone number
`messaging_profile_id`	ID of the assigned messaging profile
`type`	Number type: `long_code`, `toll_free`, `short_code`
`country_code`	Two-letter country code
`features`	Enabled features (SMS, MMS, etc.)
`health`	Number health indicators (message success rate, etc.)
`eligible_messaging_products`	Products the number can be used for

Step 4: Bulk assignment

Assign multiple numbers to a messaging profile at once using the messaging profile’s phone number assignment endpoint:

curl

# Assign multiple numbers to a profile
for number in "+15551234567" "+15559876543" "+15551112222"; do
  curl -X PATCH "https://api.telnyx.com/v2/messaging_phone_numbers/$number" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{"messaging_profile_id": "400174af-0a13-4e28-b4f5-example12345"}'
done

Python

numbers_to_assign = ["+15551234567", "+15559876543", "+15551112222"]
profile_id = "400174af-0a13-4e28-b4f5-example12345"

for number in numbers_to_assign:
    response = requests.patch(
        f"https://api.telnyx.com/v2/messaging_phone_numbers/{number}",
        headers=headers,
        json={"messaging_profile_id": profile_id},
    )
    if response.status_code == 200:
        print(f"✓ Assigned {number}")
    else:
        print(f"✗ Failed {number}: {response.json().get('errors', [])}")

Node

const numbersToAssign = ['+15551234567', '+15559876543', '+15551112222'];
const profileId = '400174af-0a13-4e28-b4f5-example12345';

for (const number of numbersToAssign) {
  try {
    await axios.patch(
      `https://api.telnyx.com/v2/messaging_phone_numbers/${encodeURIComponent(number)}`,
      { messaging_profile_id: profileId },
      { headers }
    );
    console.log(`✓ Assigned ${number}`);
  } catch (error) {
    console.log(`✗ Failed ${number}: ${error.response?.data?.errors}`);
  }
}

Messaging enablement by number type

Different number types have different requirements before they can send messages:

Number Type	Messaging Ready?	Additional Steps Required
Long code (US)	After 10DLC registration	Register brand + campaign
Toll-free (US/CA)	After verification	Submit toll-free verification
Short code	After provisioning	Short code setup
Long code (non-US)	Typically immediate	Check country-specific requirements
Alphanumeric sender ID	After registration	Alphanumeric ID setup

US long codes without 10DLC registration will experience carrier filtering and potential message blocking. Always complete 10DLC registration before sending A2P messages on US long codes.

Unassign a number from a profile

Remove a number’s messaging profile assignment:

curl

curl -X PATCH "https://api.telnyx.com/v2/messaging_phone_numbers/+15551234567" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": null
  }'

Python

response = requests.patch(
    f"https://api.telnyx.com/v2/messaging_phone_numbers/{phone_number}",
    headers=headers,
    json={"messaging_profile_id": None},
)
print(f"Unassigned {phone_number} from messaging profile")

Node

await axios.patch(
  `https://api.telnyx.com/v2/messaging_phone_numbers/${encodeURIComponent(phoneNumber)}`,
  { messaging_profile_id: null },
  { headers }
);
console.log(`Unassigned ${phoneNumber} from messaging profile`);

Unassigning a number from a messaging profile means it will no longer receive inbound message webhooks or be available for outbound messaging through that profile.

Troubleshooting

Possible causes:

The number doesn’t have messaging capabilities. Check your number order — not all numbers support SMS/MMS.
The number hasn’t finished provisioning yet. Wait a few minutes after purchase.
The number is on a different Telnyx account.

Fix: Verify the number’s capabilities via GET /v2/phone_numbers/{id} and check for messaging in the features. Cause: The from number in your send request isn’t assigned to a messaging profile. Fix: Assign the number to a profile using the assignment API, or use the messaging profile’s number pool to automatically select a number. Possible causes:

The number isn’t assigned to a messaging profile
The messaging profile doesn’t have a webhook URL configured
Your webhook endpoint is returning errors (check MDR logs)

Fix: Verify the number → profile → webhook URL chain. Test with ngrok for local development. Cause: For US long codes, messages may be filtered by carriers if 10DLC registration isn’t complete. Fix: Complete 10DLC brand and campaign registration. For toll-free, complete verification. Possible causes:

The number is already assigned to a different product (voice connection, etc.) that conflicts
The messaging profile ID is invalid
The number belongs to a different organization

Fix: Check the profile ID, verify number ownership, and ensure no conflicting product assignments.

Next steps

Create and configure messaging profiles with webhooks and features. Send your first SMS/MMS using a configured number. Use multiple numbers in a pool for automatic sender selection. Register your brand and campaign for US long code messaging.

Toll-Free Verification

Source: https://developers.telnyx.com/docs/messaging/toll-free-verification.md

Telnyx toll-free verification now supports Business Registration Number (BRN) fields to strengthen business verification and compliance. Starting February 17th, 2026, three BRN fields will be required for all new toll-free verification submissions. The following fields are required for all new toll-free verification requests:

businessRegistrationNumber
businessRegistrationType
businessRegistrationCountry

Submissions missing these fields will be rejected.

Why This Matters

U.S. wireless carriers require toll-free numbers (800, 888, 877, 866, 855, 844, 833) used for SMS/MMS to complete verification. The new BRN fields provide carriers with verified business identity information, helping to:

Reduce verification processing time
Improve approval rates
Ensure compliance with carrier policies
Prevent fraudulent messaging

New Business Registration Fields

Required Fields (February 17th, 2026)

businessRegistrationNumber

The official government-issued business registration identifier.

Property	Value
Type	String
Max Length	500 characters
Required	February 17th, 2026
Nullable	Currently yes, no after Feb 2026

Examples by Country:

Country	Type	Example Format
United States	EIN	`12-3456789` or `123456789`
Canada	Business Number	`123456789RC0001`
United Kingdom	Companies House	`12345678`
Australia	ABN	`51824753556`
Germany	VAT	`DE123456789`

Where to Find:

US: IRS EIN Lookup - Check your EIN confirmation letter or SS-4 form
Canada: CRA Business Number from your registration documents
UK: Companies House registration certificate
Australia: ABN Lookup
EU: VAT registration certificate from your national tax authority

businessRegistrationType

The type or classification of your business registration.

Property	Value
Type	String
Max Length	500 characters
Required	February 17, 2026
Nullable	Currently yes, no after Feb 2026

Common Values:

EIN - U.S. Employer Identification Number
CRA - Canadian Revenue Agency Business Number
Companies House - UK company registration
ABN - Australian Business Number
VAT - European Union VAT registration
SSN - For U.S. sole proprietors without EIN

businessRegistrationCountry

ISO 3166-1 alpha-2 country code of the authority that issued the registration.

Property	Value
Type	String
Length	Exactly 2 characters
Format	ISO 3166-1 alpha-2
Required	February 17, 2026
Nullable	Currently yes, no after Feb 2026

Validation:

Must be exactly 2 letters
Only alphabetic characters (A-Z)
Automatically converted to uppercase ("us" → "US")
Returns HTTP 400 if invalid

Example Values: US, CA, GB, AU, DE, FR, JP See complete list: ISO 3166-1 country codes

Optional Fields

These fields are optional but recommended for faster verification processing.

doingBusinessAs

DBA, trade name, or brand name if different from your legal business name.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: Legal name “Acme Corporation Inc.”, DBA “Acme Services”

entityType

Legal business entity classification.

Property	Value
Type	Enum
Required	No
Allowed Values	`SOLE_PROPRIETOR`, `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`

Value Descriptions:

Value	Description
`SOLE_PROPRIETOR`	Individual or sole proprietorship
`PRIVATE_PROFIT`	Private for-profit corporation (most common)
`PUBLIC_PROFIT`	Publicly traded for-profit company
`NON_PROFIT`	501(c) or charitable organization
`GOVERNMENT`	Government entity or agency

optInConfirmationResponse

Message sent to subscribers confirming their opt-in.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "You are now subscribed to Acme alerts. Reply STOP to unsubscribe. Msg&data rates may apply."

helpMessageResponse

Automated response when subscribers text HELP.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "Acme Support: Call 1-800-555-0123 or email help@acme.com. Reply STOP to unsubscribe."

privacyPolicyURL

URL to your business privacy policy.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "https://www.acme.com/privacy" URL format validation is not enforced. Provide a publicly accessible URL.

termsAndConditionURL

URL to your business terms and conditions.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "https://www.acme.com/terms"

ageGatedContent

Indicates if messaging content requires age verification (18+ or 21+).

Property	Value
Type	Boolean
Default	`false`
Required	No

Set to true for alcohol, tobacco, cannabis, or other age-restricted content.

optInKeywords

Keywords subscribers use to opt-in to your messaging program.

Property	Value
Type	String
Max Length	500 characters
Required	No

Example: "START, YES, SUBSCRIBE, JOIN"

API Usage

Create Verification Request with BRN Fields

Endpoint: POST /public/api/v2/requests Request with BRN Fields:

curl --request POST \
  --url https://api.telnyx.com/v2/messaging_tollfree/verification/requests \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data '{
  "businessName": "Telnyx LLC",
  "corporateWebsite": "http://example.com",
  "businessAddr1": "600 Congress Avenue",
  "businessAddr2": "14th Floor",
  "businessCity": "Austin",
  "businessState": "Texas",
  "businessZip": "78701",
  "businessContactFirstName": "John",
  "businessContactLastName": "Doe",
  "businessContactEmail": "email@example.com",
  "businessContactPhone": "+18005550100",
  "messageVolume": "100,000",
  "phoneNumbers": [
    {
      "phoneNumber": "+18773554398"
    },
    {
      "phoneNumber": "+18773554399"
    }
  ],
  "useCase": "2FA",
  "useCaseSummary": "This is a use case where Telnyx sends out 2FA codes to portal users to verify their identity in order to sign into the portal",
  "productionMessageContent": "Your Telnyx OTP is XXXX",
  "optInWorkflow": "User signs into the Telnyx portal, enters a number and is prompted to select whether they want to use 2FA verification for security purposes. If they'\''ve opted in a confirmation message is sent out to the handset",
  "optInWorkflowImageURLs": [
    {
      "url": "https://telnyx.com/sign-up"
    },
    {
      "url": "https://telnyx.com/company/data-privacy"
    }
  ],
  "additionalInformation": "",
  "isvReseller": "Yes",
  "webhookUrl": "http://example-webhook.com",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessRegistrationCountry": "US",
  "doingBusinessAs": "Acme Services",
  "entityType": "SOLE_PROPRIETOR",
  "optInConfirmationResponse": "You have successfully opted in to receive messages from Acme Corp",
  "helpMessageResponse": "Reply HELP for assistance or STOP to unsubscribe. Contact: support@example.com",
  "privacyPolicyURL": "https://example.com/privacy",
  "termsAndConditionURL": "https://example.com/terms",
  "ageGatedContent": false,
  "optInKeywords": "START, YES, SUBSCRIBE"
}'

Response (HTTP 201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verificationRequestId": "TFV-ABC123",
  "verificationStatus": "Pending",
  "businessName": "Acme Corporation",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessRegistrationCountry": "US",
  "entityType": "PRIVATE_PROFIT",
  "createdAt": "2025-10-13T12:00:00Z"
}

Retrieve Verification with BRN Fields

Endpoint: GET /public/api/v2/requests/{id}

curl -X GET https://api.telnyx.com/public/api/v2/requests/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (HTTP 200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verificationRequestId": "TFV-ABC123",
  "verificationStatus": "Approved",
  "businessName": "Acme Corporation",
  "businessRegistrationNumber": "12-3456789",
  "businessRegistrationType": "EIN",
  "businessRegistrationCountry": "US",
  "entityType": "PRIVATE_PROFIT",
  "phoneNumbers": [{"phoneNumber": "+18773554398"}],
  "createdAt": "2025-10-13T12:00:00Z",
  "updatedAt": "2025-10-15T09:30:00Z"
}

Update BRN Fields

Endpoint: PATCH /public/api/v2/requests/{id}

curl -X PATCH https://api.telnyx.com/public/api/v2/requests/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessRegistrationNumber": "98-7654321",
    "businessRegistrationCountry": "US"
  }'

Code Examples

Python

import requests

# Create verification with BRN fields
payload = {
    "businessName": "Acme Corporation",
    "corporateWebsite": "https://www.acme.com",
    "businessAddr1": "123 Main Street",
    "businessCity": "Chicago",
    "businessState": "Illinois",
    "businessZip": "60601",
    "businessContactFirstName": "John",
    "businessContactLastName": "Doe",
    "businessContactEmail": "compliance@acme.com",
    "businessContactPhone": "+18005551234",
    "messageVolume": "100,000",
    "phoneNumbers": [{"phoneNumber": "+18773554398"}],
    "useCase": "Account Notifications",
    "useCaseSummary": "Security alerts and account updates",
    "productionMessageContent": "Your Acme security code is: 123456",
    "optInWorkflow": "Users opt-in during registration",
    "optInWorkflowImageURLs": [{"url": "https://www.acme.com/opt-in.png"}],
    "additionalInformation": "Messages to verified numbers only",
    "isvReseller": "Yes",

    # BRN Fields (required Feb 2026)
    "businessRegistrationNumber": "12-3456789",
    "businessRegistrationType": "EIN",
    "businessRegistrationCountry": "US",
    "entityType": "PRIVATE_PROFIT"
}

response = requests.post(
    "https://api.telnyx.com/public/api/v2/requests",
    json=payload,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 201:
    data = response.json()
    print(f"Verification created: {data['verificationRequestId']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript/TypeScript

interface TollFreeVerificationRequest {
  businessName: string;
  corporateWebsite: string;
  businessAddr1: string;
  businessCity: string;
  businessState: string;
  businessZip: string;
  businessContactFirstName: string;
  businessContactLastName: string;
  businessContactEmail: string;
  businessContactPhone: string;
  messageVolume: string;
  phoneNumbers: Array<{ phoneNumber: string }>;
  useCase: string;
  useCaseSummary: string;
  productionMessageContent: string;
  optInWorkflow: string;
  optInWorkflowImageURLs: Array<{ url: string }>;
  additionalInformation?: string;
  isvReseller: string;

  // BRN Fields (required Feb 2026)
  businessRegistrationNumber: string;
  businessRegistrationType: string;
  businessRegistrationCountry: string;
  entityType?: 'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT';
}

async function createVerification(request: TollFreeVerificationRequest, apiKey: string) {
  const response = await fetch('https://api.telnyx.com/public/api/v2/requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(request)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Verification failed: ${JSON.stringify(error)}`);
  }

  return response.json();
}

// Example usage
const request: TollFreeVerificationRequest = {
  businessName: "Acme Corporation",
  corporateWebsite: "https://www.acme.com",
  businessAddr1: "123 Main Street",
  businessCity: "Chicago",
  businessState: "Illinois",
  businessZip: "60601",
  businessContactFirstName: "John",
  businessContactLastName: "Doe",
  businessContactEmail: "compliance@acme.com",
  businessContactPhone: "+18005551234",
  messageVolume: "100,000",
  phoneNumbers: [{ phoneNumber: "+18773554398" }],
  useCase: "Account Notifications",
  useCaseSummary: "Security alerts and account updates",
  productionMessageContent: "Your code is: 123456",
  optInWorkflow: "Users opt-in during registration",
  optInWorkflowImageURLs: [{ url: "https://www.acme.com/opt-in.png" }],
  additionalInformation: "More context";
  isvReseller: "Yes";
  businessRegistrationNumber: "12-3456789",
  businessRegistrationType: "EIN",
  businessRegistrationCountry: "US",
  entityType: "PRIVATE_PROFIT"
};

createVerification(request, 'YOUR_API_KEY')
  .then(result => console.log('Created:', result.verificationRequestId))
  .catch(error => console.error('Error:', error.message));

Error Handling

Validation Errors (HTTP 400)

Missing Required Fields (After February 2026)

Response:

{
  "errors": [
    {
      "field": "businessRegistrationNumber",
      "message": "This field is required as of February 17th 2026"
    },
    {
      "field": "businessRegistrationType",
      "message": "This field is required as of February 17th 2026"
    },
    {
      "field": "businessRegistrationCountry",
      "message": "This field is required as of February 17th 2026"
    }
  ]
}

Invalid Country Code

{
  "detail": "businessRegistrationCountry must be a 2-character ISO 3166-1 alpha-2 country code"
}

Invalid Entity Type

{
  "detail": "entityType must be one of: SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT"
}

Other Status Codes

Code	Description
200	Success (GET, PATCH)
201	Created (POST)
204	Deleted (DELETE)
400	Bad Request - Invalid data
401	Unauthorized - Invalid API key
404	Not Found - Invalid request ID
422	Unprocessable Entity - Invalid format

Migration Guide

Timeline

Period	Status	Action
Now - Dec 2025	Optional	BRN fields can be included but not required
Feb 1, 2026	Mandatory	All 3 required BRN fields must be included

Preparation Steps

1. Gather Business Registration Information Locate your:

Business registration number (EIN, VAT, ABN, etc.)
Registration type identifier
Issuing country code

2. Update Your Integration Add BRN fields to your API requests:

  const request = {
    businessName: "Acme Corp",
    corporateWebsite: "https://acme.com",
    // ... other required fields
+   businessRegistrationNumber: "12-3456789",
+   businessRegistrationType: "EIN",
+   businessRegistrationCountry: "US"
  };

3. Test Your Implementation

Submit test requests with BRN fields
Verify fields are returned in responses
Test validation error handling
Confirm country code uppercase conversion

4. Update Error Handling Prepare for validation errors after February 2026:

try {
  const result = await createVerification(request);
} catch (error) {
  if (error.status === 400) {
    console.error('Validation failed:', error.errors);
    // Handle missing BRN fields
  }
}

Backward Compatibility

Until February 17, 2026:

Requests without BRN fields continue to work
No breaking changes to existing integrations
BRN fields default to null if not provided

After February 17, 2026:

Requests without 3 required BRN fields will be rejected (HTTP 400)
Update your integration before this date

Frequently Asked Questions

When do BRN fields become mandatory?

February 17th, 2026. All new verification requests must include businessRegistrationNumber, businessRegistrationType, and businessRegistrationCountry.

Do I need to resubmit existing verifications?

No. Approved verifications before February 2026 remain valid.

Where do I find my business registration number?

US: IRS EIN confirmation letter or IRS.gov
Canada: CRA Business Number registration documents
UK: Companies House certificate
Australia: ABN Lookup
EU: VAT registration certificate

What if I’m a sole proprietor without an EIN?

U.S. sole proprietors can use their Social Security Number as businessRegistrationNumber with type SSN. Other countries may have similar individual tax identifiers.

Can I update BRN fields after submission?

Yes. Use PATCH /public/api/v2/requests/{id} to update BRN fields.

Why are country codes converted to uppercase?

For consistency. Sending "us" automatically becomes "US" in responses and storage.

Which entity type should I choose?

Choose the type matching your official business registration:

SOLE_PROPRIETOR - Individual or sole proprietorship
PRIVATE_PROFIT - Private corporation (most common)
PUBLIC_PROFIT - Publicly traded company
NON_PROFIT - 501(c) or charitable organization
GOVERNMENT - Government entity

How long does toll-free verification take?

Verification typically takes 1-2 weeks, depending on the carrier review queue and the completeness of your submission. Including accurate BRN fields can speed up the process.

What happens if my verification is rejected?

You’ll receive a webhook notification with the rejection reason. Common causes:

Incomplete or inaccurate business information
Message samples don’t match your declared use case
Missing opt-out language in sample messages
Business couldn’t be verified with the provided registration number

Fix the issues and resubmit — there’s no limit on resubmissions.

Can I send messages before verification is complete?

Unverified toll-free numbers have limited throughput and may experience carrier filtering. Complete verification to unlock full sending capabilities (up to 20 MPS).

What’s the difference between toll-free verification and 10DLC registration?

Aspect	Toll-Free Verification	10DLC Registration
Number type	Toll-free (800, 888, etc.)	Local 10-digit numbers
Timeline	1-2 weeks	Days (plus 1-7 days for vetting)
Registry	Carrier-managed	The Campaign Registry (TCR)
Throughput	Up to 20 MPS	Varies by vetting score
Cost	Per-message	Per-message + campaign fees

API reference for managing toll-free verification requests. Send messages from your verified toll-free numbers. Alternative registration path for local 10-digit numbers. Configure opt-in/out behavior including toll-free specific handling.

Support

Need help with toll-free verification?

Support Portal: support.telnyx.com
Email: support@telnyx.com
Developer Community: Join discussions and get help from other developers

Troubleshooting

Source: https://developers.telnyx.com/docs/messaging/toll-free-verification/troubleshooting.md

This guide covers common toll-free verification failures, rejection reasons, resubmission best practices, and messaging issues with toll-free numbers. Use it to diagnose problems and get your verification approved faster. Quick links: Rejection reasons · Resubmission guide · Delivery issues · Status tracking · Diagnostic checklist

Verification lifecycle

Understanding where your verification can fail helps target the right fix:

Stage	Timeline	What happens
Submission	Instant	API validates fields, returns 201 or error
Under review	1–2 weeks	Carriers review business identity and messaging use case
Decision	—	Approved (full throughput) or rejected (with reason)
Resubmission	Instant	Fix issues and resubmit — no limit on attempts

Verification rejection reasons

Rejections come from carrier review. Each has specific causes and fixes.

Business information issues

Rejection reason: Business name does not match public records. Root cause: The businessName you submitted doesn’t match what’s on file with the Secretary of State, IRS, or similar authority for your registration number. Fix:

Look up your exact legal name on your state’s Secretary of State website
Cross-reference with your EIN confirmation letter from the IRS
Include suffixes exactly: “Inc.”, “LLC”, “Corp.” — these matter
Resubmit with the corrected name

curl

curl -X PATCH https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Acme Corporation Inc."
  }'

Common mistakes:

Using a DBA/trade name instead of the legal entity name
Missing “LLC”, “Inc.”, etc.
Using an old company name after a legal name change

Rejection reason: Unable to verify business registration information. Root cause: The EIN, ABN, VAT number, or other registration number doesn’t match the business name or doesn’t exist in public records. Fix:

Verify your EIN at IRS.gov or on your SS-4 confirmation letter
Ensure the businessRegistrationType matches the number format (e.g., “EIN” for US tax IDs)
Confirm businessRegistrationCountry is correct (ISO alpha-2)
For sole proprietors using SSN, ensure the name matches exactly

curl

curl -X PATCH https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessRegistrationNumber": "12-3456789",
    "businessRegistrationType": "EIN",
    "businessRegistrationCountry": "US"
  }'

Rejection reason: Corporate website could not be verified or does not match the business. Root cause: Carriers check that the website is live, matches the business name, and has content relevant to the declared use case. Fix:

Ensure the URL is accessible (no authentication required, no redirects to a different domain)
The website must show the company name prominently
Website content should relate to the messaging use case
HTTPS is strongly preferred
Under construction / parking pages will cause rejection

Before resubmitting, verify:

# Check website is accessible
curl -sI https://yourbusiness.com | head -5

# Check it resolves to expected domain
curl -sL -o /dev/null -w '%{url_effective}' https://yourbusiness.com

Rejection reason: Contact information could not be verified. Root cause: The phone number or email provided doesn’t match public records for the business, or isn’t reachable. Fix:

Use a phone number that’s publicly associated with the business (Google listing, website, etc.)
Use a business email domain (not gmail.com, yahoo.com for corporations)
Ensure the contact person is authorized to represent the business

Rejection reason: Entity type does not match business records. Root cause: You selected PRIVATE_PROFIT but the business is registered as a nonprofit, or vice versa. Fix: Choose the correct entity type based on your actual business registration:

Entity Type	Use for
`SOLE_PROPRIETOR`	Individual / sole proprietorship
`PRIVATE_PROFIT`	Private corporation (most common)
`PUBLIC_PROFIT`	Publicly traded company
`NON_PROFIT`	501(c)(3) or charitable organization
`GOVERNMENT`	Government entity at any level

Messaging use case issues

Rejection reason: Message samples are inconsistent with the stated use case. Root cause: Your useCaseSummary says one thing (e.g., “appointment reminders”) but your sample messages show something different (e.g., marketing promotions). Fix:

Ensure every sample message directly relates to your declared use case
Include realistic content — not placeholder text
Show the full message including opt-out language
If you have multiple use cases, describe all of them in useCaseSummary

Good sample:

Hi Sarah, this is Dr. Smith's office. Your appointment is confirmed
for March 15 at 2:00 PM. Reply STOP to opt out of reminders.

Bad sample:

Test message for verification purposes.

Rejection reason: Sample messages must include opt-out instructions. Root cause: At least one sample message is missing STOP/opt-out language, or the opt-out mechanism isn’t clear. Fix:

Include “Reply STOP to unsubscribe” (or similar) in every sample
The opt-out instruction should be natural, not buried
STOP, CANCEL, UNSUBSCRIBE, QUIT, END should all work

Required format examples:

“Reply STOP to opt out.”
“Text STOP to unsubscribe.”
“Reply STOP to end messages. Msg & data rates may apply.”

Rejection reason: Declared message volume does not align with the use case. Root cause: Claiming a very high volume for a use case that typically doesn’t generate it, or vice versa. Fix:

Be honest about expected volumes — carriers cross-reference similar businesses
If volume is high, explain why (large customer base, time-sensitive notifications)
Start conservative and increase as your messaging matures

Rejection reason: Opt-in process is unclear or not documented. Root cause: You didn’t adequately describe how recipients consent to receive messages. Fix: Describe the full opt-in flow in your messageFlow field:

Where users sign up (website form, checkout flow, in-app)
What consent language they see
Whether it’s single or double opt-in
How consent records are maintained

Good example:

Customers opt in during checkout at acme.com/checkout by checking
"I agree to receive order updates and shipping notifications via SMS."
Consent is recorded with timestamp and IP address. Customers can
opt out at any time by replying STOP.

Bad example:

Users sign up on our website.

Rejection reason: Message content contains prohibited or restricted material. Root cause: Sample messages or use case involves content types that carriers restrict:

Cannabis/CBD
Adult content
Gambling (without proper licensing documentation)
High-risk financial services (payday loans, crypto trading signals)
Third-party lead generation

Fix:

If your content is genuinely prohibited, toll-free may not be the right channel
For regulated industries (gambling, financial services), include licensing documentation
Remove any references to restricted content from samples
Contact Telnyx support for guidance on restricted use cases

Resubmission process

After a rejection, you can fix the issues and resubmit. There’s no limit on resubmission attempts. Check your verification status via API or the Telnyx portal. The rejection reason tells you exactly what to fix.

curl

curl -s https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" | python3 -m json.tool

Python

import telnyx
import os

telnyx.api_key = os.environ["TELNYX_API_KEY"]

request = telnyx.TollFreeVerificationRequest.retrieve("REQUEST_ID")
print(f"Status: {request.status}")
print(f"Rejection reason: {request.rejection_reason}")

Node

import Telnyx from "telnyx";

const telnyx = new Telnyx(process.env.TELNYX_API_KEY);

const { data: request } = await telnyx.tollFreeVerification.requests.retrieve("REQUEST_ID");
console.log(`Status: ${request.status}`);
console.log(`Rejection reason: ${request.rejectionReason}`);

Update only the fields that caused the rejection. Use PATCH to update specific fields:

curl

curl -X PATCH https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Corrected Legal Name LLC",
    "messageVolume": "10000",
    "useCaseSummary": "Updated description of our messaging use case...",
    "sampleMessage1": "Updated sample with opt-out. Reply STOP to unsubscribe.",
    "sampleMessage2": "Another realistic sample. Reply STOP to opt out."
  }'

Python

import telnyx
import os

telnyx.api_key = os.environ["TELNYX_API_KEY"]

request = telnyx.TollFreeVerificationRequest.update(
    "REQUEST_ID",
    business_name="Corrected Legal Name LLC",
    message_volume="10000",
    use_case_summary="Updated description of our messaging use case...",
    sample_message1="Updated sample with opt-out. Reply STOP to unsubscribe.",
    sample_message2="Another realistic sample. Reply STOP to opt out.",
)
print(f"Updated status: {request.status}")

Node

import Telnyx from "telnyx";

const telnyx = new Telnyx(process.env.TELNYX_API_KEY);

const { data: request } = await telnyx.tollFreeVerification.requests.update("REQUEST_ID", {
  businessName: "Corrected Legal Name LLC",
  messageVolume: "10000",
  useCaseSummary: "Updated description of our messaging use case...",
  sampleMessage1: "Updated sample with opt-out. Reply STOP to unsubscribe.",
  sampleMessage2: "Another realistic sample. Reply STOP to opt out.",
});
console.log(`Updated status: ${request.status}`);

Ruby

require "telnyx"

Telnyx.api_key = ENV["TELNYX_API_KEY"]

request = Telnyx::TollFreeVerificationRequest.update(
  "REQUEST_ID",
  business_name: "Corrected Legal Name LLC",
  message_volume: "10000",
  use_case_summary: "Updated description...",
  sample_message1: "Updated sample with opt-out. Reply STOP to unsubscribe."
)
puts "Updated status: #{request.status}"

package main

import (
    "context"
    "fmt"
    "github.com/team-telnyx/telnyx-go"
    "github.com/team-telnyx/telnyx-go/option"
)

func main() {
    client := telnyx.NewClient(option.WithAPIKey("YOUR_API_KEY"))

    request, err := client.TollFreeVerification.Requests.Update(
        context.TODO(),
        "REQUEST_ID",
        telnyx.TollFreeVerificationRequestUpdateParams{
            BusinessName:   telnyx.String("Corrected Legal Name LLC"),
            MessageVolume:  telnyx.String("10000"),
            UseCaseSummary: telnyx.String("Updated description..."),
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Printf("Updated status: %s\n", request.Status)
}

Java

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

var request = client.tollFreeVerification().requests().update(
    "REQUEST_ID",
    TollFreeVerificationRequestUpdateParams.builder()
        .businessName("Corrected Legal Name LLC")
        .messageVolume("10000")
        .useCaseSummary("Updated description...")
        .build()
);
System.out.println("Updated status: " + request.status());

.NET

using Telnyx;

var client = new TelnyxClient(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var request = await client.TollFreeVerification.Requests.UpdateAsync(
    "REQUEST_ID",
    new TollFreeVerificationRequestUpdateParams
    {
        BusinessName = "Corrected Legal Name LLC",
        MessageVolume = "10000",
        UseCaseSummary = "Updated description...",
    }
);
Console.WriteLine($"Updated status: {request.Status}");

PHP

$telnyx = new \Telnyx\TelnyxClient(getenv('TELNYX_API_KEY'));

$request = $telnyx->tollFreeVerification->requests->update('REQUEST_ID', [
    'business_name' => 'Corrected Legal Name LLC',
    'message_volume' => '10000',
    'use_case_summary' => 'Updated description...',
]);
echo "Updated status: " . $request->status . "\n";

After updating, the verification automatically enters the review queue again. No separate “submit” action is needed — the PATCH triggers re-review. Set up webhooks to get notified when the review completes:

Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/toll-free", methods=["POST"])
def handle_toll_free_webhook():
    event = request.json
    event_type = event.get("data", {}).get("event_type", "")

    if event_type == "toll_free_verification.status_update":
        payload = event["data"]["payload"]
        status = payload["status"]
        request_id = payload["id"]

        if status == "verified":
            print(f"✅ Verification {request_id} approved!")
            # Enable full messaging for this number
        elif status == "rejected":
            reason = payload.get("rejectionReason", "No reason provided")
            print(f"❌ Verification {request_id} rejected: {reason}")
            # Alert team, prepare resubmission

    return jsonify({"status": "ok"}), 200

Resubmission tips

Do	Don’t
Fix only the cited rejection reason	Change everything at once
Use exact legal business name	Use informal names or abbreviations
Provide realistic sample messages	Use generic placeholder text
Include opt-out in every sample	Assume opt-out is implied
Wait for the full review cycle	Submit multiple times in rapid succession

Delivery issues after verification

Even after successful verification, you may experience delivery problems.

Throughput limitations

Verification status	Throughput	Notes
Unverified	~0.25 MPS	Heavy carrier filtering, low reliability
Pending review	~1 MPS	Some filtering may apply
Verified	Up to 20 MPS	Full throughput, minimal filtering

Sending above your throughput tier results in message queuing and eventual 40014 (Expired in queue) errors. If you need more than 20 MPS from toll-free numbers, consider using short codes or 10DLC with number pools.

Common delivery errors

Cause: Message content triggered carrier-level content filters, independent of verification status. Fix:

Review message content for spam trigger words (FREE, WINNER, ACT NOW)
Avoid URL shorteners (bit.ly, tinyurl) — use full URLs or Telnyx URL shortening
Don’t send identical messages to many recipients in rapid succession
Check if recipient has previously opted out
Review the error code reference for specific guidance

Cause: The recipient number is invalid, deactivated, or not SMS-capable. Fix:

Validate numbers before sending (use Number Lookup API)
Remove landlines and VoIP numbers that don’t support SMS
Check for typos in the recipient number

Cause: Sending faster than your verified throughput allows. Fix:

Implement client-side rate limiting (see Rate Limiting guide)
Spread traffic across multiple toll-free numbers if needed
Use a messaging profile with number pooling for high-volume use cases

Cause: Message sat in the queue too long, usually due to throughput congestion. Fix:

Reduce sending rate to stay within throughput limits
Check if a carrier outage is causing delivery backlog
For time-sensitive messages, set a shorter validity period

Cause: Some carriers may still filter your toll-free traffic even after verification, especially for:

New verifications (carrier trust builds over time)
Content that resembles spam patterns
High complaint rates from recipients

Fix:

Start with lower volumes and ramp up gradually over 1–2 weeks
Monitor delivery rates per carrier using MDRs
Ensure opt-out is working properly (high complaint rates trigger filtering)
Contact Telnyx support if specific carriers consistently filter your traffic

Checking verification status

Via API

curl

# Get status of a specific verification
curl -s https://api.telnyx.com/v2/tollFreeVerification/requests/{requestId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
print(f\"Status: {data['status']}\")
print(f\"Phone numbers: {', '.join(data.get('phoneNumbers', []))}\")
if data.get('rejectionReason'):
    print(f\"Rejection reason: {data['rejectionReason']}\")
"

# List all verifications
curl -s "https://api.telnyx.com/v2/tollFreeVerification/requests?page[size]=25" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
for req in data:
    numbers = ', '.join(req.get('phoneNumbers', []))
    print(f\"{req['id']} | {req['status']:12} | {numbers}\")
"

Python

import telnyx
import os

telnyx.api_key = os.environ["TELNYX_API_KEY"]

# List all verifications
verifications = telnyx.TollFreeVerificationRequest.list(page={"size": 25})
for v in verifications.data:
    numbers = ", ".join(v.phone_numbers or [])
    print(f"{v.id} | {v.status:12} | {numbers}")
    if v.status == "rejected":
        print(f"  Reason: {v.rejection_reason}")

Node

import Telnyx from "telnyx";

const telnyx = new Telnyx(process.env.TELNYX_API_KEY);

// List all verifications
const { data: verifications } = await telnyx.tollFreeVerification.requests.list({
  page: { size: 25 },
});
for (const v of verifications) {
  const numbers = (v.phoneNumbers || []).join(", ");
  console.log(`${v.id} | ${v.status.padEnd(12)} | ${numbers}`);
  if (v.status === "rejected") {
    console.log(`  Reason: ${v.rejectionReason}`);
  }
}

Via Portal

Log in to the Telnyx Portal
Navigate to Messaging → Toll-Free Verification
View status, rejection reasons, and submission details for each verification

Status reference

Status	Meaning	Action needed
`draft`	Created but not yet submitted	Complete required fields and submit
`pending`	Under carrier review	Wait (1–2 weeks typical)
`verified`	Approved ✅	None — full throughput unlocked
`rejected`	Carrier rejected ❌	Fix issues and resubmit

Diagnostic checklist

Use this checklist when troubleshooting verification issues:

Before submitting

After rejection

Read the rejection reason completely
Cross-reference with the rejection reasons above
Fix only the specific issue cited
Double-check all information against official business records
Resubmit via PATCH (don’t create a new request)
Set up webhooks to track the new review

After verification (delivery issues)

Verify toll-free number is on an active messaging profile
Check sending rate isn’t exceeding throughput tier
Review message content for spam trigger words
Confirm opt-out keywords are being processed
Check MDRs for carrier-specific delivery rates
Monitor error codes for patterns

Timeline expectations

Stage	Typical duration
Initial submission to review start	1–3 business days
Carrier review	5–10 business days
Total (first submission)	1–2 weeks
Resubmission review	5–10 business days
Multiple resubmissions	Each adds ~1 week

Expedited review is not available for toll-free verification. The review timeline is set by carriers, not Telnyx. Ensure your first submission is complete and accurate to avoid resubmission delays.

Toll-free vs. 10DLC: when to use which

Factor	Toll-Free	10DLC
Setup time	1–2 weeks	Days (brand + campaign registration)
Throughput	Up to 20 MPS	Varies by vetting score (up to 240 MPS with enhanced)
Cost	Per-message only	Per-message + campaign fees ($10/mo)
Number appearance	800/888/877/etc.	Local area code
Registration	Toll-free verification	TCR brand + campaign
MMS	✅ Supported	✅ Supported
Best for	Customer service, national reach	Local presence, high volume A2P

Many businesses use both: toll-free for customer service and support lines, 10DLC for marketing and transactional messages with local presence.

Next steps

Main verification guide with BRN fields and API reference. Understand delivery error codes and resolution steps. Similar troubleshooting guide for 10DLC registration issues. Implement client-side rate limiting to avoid throughput errors.

Quickstart

Source: https://developers.telnyx.com/docs/messaging/10dlc/quickstart.md

10DLC (10-Digit Long Code) is the industry standard for application-to-person (A2P) messaging on US long code numbers. Registering your brand and campaigns provides higher throughput, better deliverability, and reduced carrier filtering.

Registration overview

Step	What happens	Timeline
1. Create Brand	Register your business identity with The Campaign Registry (TCR)	Instant
2. Vet Brand	Third-party vetting determines your trust score (0-100)	1-7 business days
3. Create Campaign	Register your messaging use case	Instant (pending carrier approval)
4. Assign Numbers	Link phone numbers to your campaign	Instant

Vetting is critical. Your brand’s vetting score directly determines your throughput limits — especially on AT&T and T-Mobile. See 10DLC Rate Limits for details.

Step 1: Create a brand

A brand represents the business entity sending messages.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/brand \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "entityType": "PRIVATE_PROFIT",
    "displayName": "Acme Corp",
    "companyName": "Acme Corporation",
    "ein": "12-3456789",
    "phone": "+15551234567",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US",
    "email": "admin@acmecorp.com",
    "website": "https://acmecorp.com",
    "vertical": "TECHNOLOGY"
  }'

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

brand_data = {
    "entityType": "PRIVATE_PROFIT",
    "displayName": "Acme Corp",
    "companyName": "Acme Corporation",
    "ein": "12-3456789",
    "phone": "+15551234567",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US",
    "email": "admin@acmecorp.com",
    "website": "https://acmecorp.com",
    "vertical": "TECHNOLOGY",
}

response = requests.post(
    "https://api.telnyx.com/v2/10dlc/brand",
    headers=headers,
    json=brand_data,
)
brand = response.json()
print(f"Brand created: {brand['data']['brandId']}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
  'Content-Type': 'application/json',
};

const brandData = {
  entityType: 'PRIVATE_PROFIT',
  displayName: 'Acme Corp',
  companyName: 'Acme Corporation',
  ein: '12-3456789',
  phone: '+15551234567',
  street: '123 Main St',
  city: 'New York',
  state: 'NY',
  postalCode: '10001',
  country: 'US',
  email: 'admin@acmecorp.com',
  website: 'https://acmecorp.com',
  vertical: 'TECHNOLOGY',
};

const response = await axios.post(
  'https://api.telnyx.com/v2/10dlc/brand',
  brandData,
  { headers }
);
console.log(`Brand created: ${response.data.data.brandId}`);

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.telnyx.com/v2/10dlc/brand")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = {
  entityType: "PRIVATE_PROFIT",
  displayName: "Acme Corp",
  companyName: "Acme Corporation",
  ein: "12-3456789",
  phone: "+15551234567",
  street: "123 Main St",
  city: "New York",
  state: "NY",
  postalCode: "10001",
  country: "US",
  email: "admin@acmecorp.com",
  website: "https://acmecorp.com",
  vertical: "TECHNOLOGY"
}.to_json

response = http.request(request)
brand = JSON.parse(response.body)
puts "Brand created: #{brand['data']['brandId']}"

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func main() {
  brandData := map[string]string{
    "entityType":  "PRIVATE_PROFIT",
    "displayName": "Acme Corp",
    "companyName":  "Acme Corporation",
    "ein":          "12-3456789",
    "phone":        "+15551234567",
    "street":       "123 Main St",
    "city":         "New York",
    "state":        "NY",
    "postalCode":   "10001",
    "country":      "US",
    "email":        "admin@acmecorp.com",
    "website":      "https://acmecorp.com",
    "vertical":     "TECHNOLOGY",
  }

  body, _ := json.Marshal(brandData)
  req, _ := http.NewRequest("POST", "https://api.telnyx.com/v2/10dlc/brand", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  data := result["data"].(map[string]interface{})
  fmt.Printf("Brand created: %s\n", data["brandId"])
}

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');

$brandData = [
    'entityType' => 'PRIVATE_PROFIT',
    'displayName' => 'Acme Corp',
    'companyName' => 'Acme Corporation',
    'ein' => '12-3456789',
    'phone' => '+15551234567',
    'street' => '123 Main St',
    'city' => 'New York',
    'state' => 'NY',
    'postalCode' => '10001',
    'country' => 'US',
    'email' => 'admin@acmecorp.com',
    'website' => 'https://acmecorp.com',
    'vertical' => 'TECHNOLOGY',
];

$ch = curl_init('https://api.telnyx.com/v2/10dlc/brand');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($brandData),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Brand created: {$response['data']['brandId']}\n";

Required fields:

Field	Description	Example
`entityType`	Business type	`PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`
`displayName`	Brand display name	`Acme Corp`
`companyName`	Legal company name	`Acme Corporation`
`ein`	EIN/Tax ID	`12-3456789`
`phone`	Business phone	`+15551234567`
`street`, `city`, `state`, `postalCode`, `country`	Business address	—
`email`	Contact email	`admin@acmecorp.com`
`vertical`	Industry vertical	`TECHNOLOGY`, `HEALTHCARE`, `RETAIL`, etc.
Go to Brands in Mission Control Portal.
Click Create Brand and enter your business information including legal name, EIN, address, and industry vertical.
Click Save. Your brand is now registered with The Campaign Registry.

Step 2: Vet your brand

Brand vetting determines your trust score (0-100), which directly affects your messaging throughput. Higher scores unlock more messages per minute.

curl

# Request vetting for a brand
curl -X POST https://api.telnyx.com/v2/10dlc/brand/{brandId}/vetting \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "vettingProvider": "AEGIS",
    "vettingClass": "STANDARD"
  }'

Check vetting status:

curl -s https://api.telnyx.com/v2/10dlc/brand/{brandId} \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data.vettingScore'

Click on the brand you want to vet on the Brands page. Under the Vetting Request section, select Aegis Mobile as the provider and Standard as the vetting class. Click Apply for Vetting. Results typically arrive within 1-7 business days. Timeline: Standard vetting takes 1-7 business days. Enhanced vetting (for higher scores) may take longer. You can create campaigns before vetting completes, but throughput will be limited until a score is assigned.

Step 3: Create a campaign

A campaign defines your messaging use case and is required for each distinct type of messaging you do.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/campaignBuilder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "brandId": "your_brand_id",
    "usecase": "MIXED",
    "description": "Order confirmations and delivery updates",
    "sample1": "Your order #12345 has been confirmed. Track at https://acme.com/track/12345",
    "sample2": "Your package is out for delivery and will arrive by 5 PM today.",
    "messageFlow": "Customers opt in at checkout by checking a box to receive order updates via SMS.",
    "helpMessage": "Reply HELP for support. Contact us at support@acmecorp.com or call +15551234567.",
    "optinKeywords": "START, YES",
    "optoutKeywords": "STOP, UNSUBSCRIBE",
    "helpKeywords": "HELP, INFO",
    "embeddedLink": true,
    "numberPool": false,
    "ageGated": false
  }'

Python

campaign_data = {
    "brandId": "your_brand_id",
    "usecase": "MIXED",
    "description": "Order confirmations and delivery updates",
    "sample1": "Your order #12345 has been confirmed.",
    "sample2": "Your package is out for delivery.",
    "messageFlow": "Customers opt in at checkout.",
    "helpMessage": "Reply HELP for support.",
    "optinKeywords": "START, YES",
    "optoutKeywords": "STOP, UNSUBSCRIBE",
    "helpKeywords": "HELP, INFO",
    "embeddedLink": True,
    "numberPool": False,
    "ageGated": False,
}

response = requests.post(
    "https://api.telnyx.com/v2/10dlc/campaignBuilder",
    headers=headers,
    json=campaign_data,
)
campaign = response.json()
print(f"Campaign created: {campaign['data']['campaignId']}")

Node

const campaignData = {
  brandId: 'your_brand_id',
  usecase: 'MIXED',
  description: 'Order confirmations and delivery updates',
  sample1: 'Your order #12345 has been confirmed.',
  sample2: 'Your package is out for delivery.',
  messageFlow: 'Customers opt in at checkout.',
  helpMessage: 'Reply HELP for support.',
  optinKeywords: 'START, YES',
  optoutKeywords: 'STOP, UNSUBSCRIBE',
  helpKeywords: 'HELP, INFO',
  embeddedLink: true,
  numberPool: false,
  ageGated: false,
};

const response = await axios.post(
  'https://api.telnyx.com/v2/10dlc/campaignBuilder',
  campaignData,
  { headers }
);
console.log(`Campaign created: ${response.data.data.campaignId}`);

Common use case types:

Use Case	Description
`MIXED`	Multiple message types (most common)
`MARKETING`	Promotional messages
`CUSTOMER_CARE`	Support and service messages
`DELIVERY_NOTIFICATION`	Order/delivery updates
`ACCOUNT_NOTIFICATION`	Account alerts
`2FA`	Two-factor authentication
`SECURITY_ALERT`	Security notifications
`POLLING_VOTING`	Surveys and polls
`CHARITY`	Nonprofit messaging
`POLITICAL`	Political campaigns
Go to Campaigns and click Create New Campaign.
Choose the use case that best matches your messaging purpose and click Next.
Review the carrier terms and your brand score. Click Next.
Add industry vertical, sample messages, and campaign attributes. Accept the terms and conditions.

Sample messages matter. Carriers review your sample messages during approval. Make them realistic and representative of your actual messaging. Include opt-out language (e.g., “Reply STOP to unsubscribe”).

Step 4: Assign phone numbers

Link your phone numbers to the campaign so they can send messages under that campaign’s registration.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/phoneNumberCampaign \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+15551234567",
    "campaignId": "your_campaign_id"
  }'

Python

response = requests.post(
    "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign",
    headers=headers,
    json={
        "phoneNumber": "+15551234567",
        "campaignId": "your_campaign_id",
    },
)
print(f"Number assigned: {response.json()['data']['phoneNumber']}")

Node

const response = await axios.post(
  'https://api.telnyx.com/v2/10dlc/phoneNumberCampaign',
  {
    phoneNumber: '+15551234567',
    campaignId: 'your_campaign_id',
  },
  { headers }
);
console.log(`Number assigned: ${response.data.data.phoneNumber}`);

Go to Campaigns and click on your campaign. Navigate to the Assign Numbers panel. Select the messaging profile, then enter the phone number(s) to assign. Phone numbers must already be assigned to a messaging profile before they can be assigned to a campaign. See the Send Your First Message guide to set this up.

Troubleshooting

Common causes:

EIN mismatch: The EIN must match the legal business name exactly as registered with the IRS
Invalid address: Use the physical business address, not a P.O. box
Missing website: A working website is strongly recommended for higher vetting scores

Fix: Correct the information and resubmit. Brand registration is free to retry. Vetting scores depend on:

Business age and size
Online presence and reputation
EIN verification
Industry vertical

Options:

Request Enhanced Vetting for a more thorough review (may improve score)
Ensure your website is live, professional, and matches your brand information
Check that your EIN and business name match IRS records exactly

See 10DLC Rate Limits for how scores map to throughput. Carriers may reject campaigns for:

Vague or misleading sample messages
Missing opt-out language in samples
Use case doesn’t match message content
Prohibited content (cannabis, gambling in some states, etc.)

Fix: Review and update your sample messages, ensure opt-out language is included, and verify your use case is accurate. Even with 10DLC registration, messages can be filtered if:

Content doesn’t match the registered campaign use case
Messages look like spam (identical content to many recipients)
Links are flagged by carrier content filters
Volume exceeds your campaign’s throughput allocation

Fix: Ensure message content matches your campaign description. Personalize messages. Use link shorteners carefully. Monitor Message Detail Records for delivery issues.

Next steps

Understand carrier-specific throughput based on your vetting score. Receive webhooks for brand vetting, campaign approval, and more. Special 10DLC registration for sole proprietors without an EIN. Start sending messages once your 10DLC setup is complete.

Sole Proprietor

Source: https://developers.telnyx.com/docs/messaging/10dlc/sole-proprietor.md

Sole Proprietor registration enables individuals and small businesses without a federal Tax ID (EIN) to register for 10DLC messaging. This guide covers the API workflow for creating Sole Proprietor brands, completing OTP verification, and managing campaigns programmatically.

Overview

Sole Proprietor brands have specific constraints compared to standard business brands:

Constraint	Limit
Campaigns per brand	1
Phone numbers per campaign	1
Mobile phone reuse	Max 3 SP brands per mobile number
Throughput	Low-volume (varies by carrier)

Sole Proprietor registration requires identity verification via SMS OTP before campaigns can be created.

Prerequisites

Telnyx account with API access
At least one US 10DLC phone number
Valid US/CA mobile phone number for OTP verification
Personal information: name, address, date of birth

Registration Flow

Step 1: Create a Sole Proprietor Brand

Create a brand with entityType set to SOLE_PROPRIETOR: Valid vertical values include: PROFESSIONAL, REAL_ESTATE, HEALTHCARE, RETAIL, ENTERTAINMENT, EDUCATION, NONPROFIT, GOVERNMENT, and others. See the Brand API Reference for the full list.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/brand \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "entityType": "SOLE_PROPRIETOR",
    "firstName": "Jane",
    "lastName": "Smith",
    "displayName": "Jane Smith Consulting",
    "email": "jane@example.com",
    "phone": "+12025551234",
    "mobilePhone": "+12025559876",
    "street": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "postalCode": "78701",
    "country": "US",
    "vertical": "PROFESSIONAL"
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const brand = await client.messaging10dlc.brand.create({
  entityType: 'SOLE_PROPRIETOR',
  firstName: 'Jane',
  lastName: 'Smith',
  displayName: 'Jane Smith Consulting',
  email: 'jane@example.com',
  phone: '+12025551234',
  mobilePhone: '+12025559876',
  street: '123 Main St',
  city: 'Austin',
  state: 'TX',
  postalCode: '78701',
  country: 'US',
  vertical: 'PROFESSIONAL',
});

console.log(brand.brandId);
console.log(brand.identityStatus);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

brand = client.messaging_10dlc.brand.create(
    entity_type="SOLE_PROPRIETOR",
    first_name="Jane",
    last_name="Smith",
    display_name="Jane Smith Consulting",
    email="jane@example.com",
    phone="+12025551234",
    mobile_phone="+12025559876",
    street="123 Main St",
    city="Austin",
    state="TX",
    postal_code="78701",
    country="US",
    vertical="PROFESSIONAL",
)

print(brand.brand_id)
print(brand.identity_status)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

brand = client.messaging_10dlc.brand.create(
  entity_type: :SOLE_PROPRIETOR,
  first_name: "Jane",
  last_name: "Smith",
  display_name: "Jane Smith Consulting",
  email: "jane@example.com",
  phone: "+12025551234",
  mobile_phone: "+12025559876",
  street: "123 Main St",
  city: "Austin",
  state: "TX",
  postal_code: "78701",
  country: "US",
  vertical: :PROFESSIONAL
)

puts(brand)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  brand, err := client.Messaging10dlc.Brand.New(context.TODO(), telnyx.Messaging10dlcBrandNewParams{
    EntityType:  telnyx.EntityTypeSoleProprietor,
    FirstName:   "Jane",
    LastName:    "Smith",
    DisplayName: "Jane Smith Consulting",
    Email:       "jane@example.com",
    Phone:       "+12025551234",
    MobilePhone: "+12025559876",
    Street:      "123 Main St",
    City:        "Austin",
    State:       "TX",
    PostalCode:  "78701",
    Country:     "US",
    Vertical:    telnyx.VerticalProfessional,
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Brand ID: %s\n", brand.BrandID)
  fmt.Printf("Identity Status: %s\n", brand.IdentityStatus)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messaging10dlc.brand.BrandCreateParams;
import com.telnyx.sdk.models.messaging10dlc.brand.EntityType;
import com.telnyx.sdk.models.messaging10dlc.brand.TelnyxBrand;
import com.telnyx.sdk.models.messaging10dlc.brand.Vertical;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        BrandCreateParams params = BrandCreateParams.builder()
            .entityType(EntityType.SOLE_PROPRIETOR)
            .firstName("Jane")
            .lastName("Smith")
            .displayName("Jane Smith Consulting")
            .email("jane@example.com")
            .phone("+12025551234")
            .mobilePhone("+12025559876")
            .street("123 Main St")
            .city("Austin")
            .state("TX")
            .postalCode("78701")
            .country("US")
            .vertical(Vertical.PROFESSIONAL)
            .build();

        TelnyxBrand brand = client.messaging10dlc().brand().create(params);
        System.out.println("Brand ID: " + brand.brandId());
        System.out.println("Identity Status: " + brand.identityStatus());
    }
}

Response

{
  "brandId": "f5586561-8ff0-4291-a0ac-84fe544797bd",
  "entityType": "SOLE_PROPRIETOR",
  "displayName": "Jane Smith Consulting",
  "firstName": "Jane",
  "lastName": "Smith",
  "identityStatus": "PENDING",
  "mobilePhone": "+12025559876",
  "createdAt": "2026-02-03T12:00:00Z"
}

The brand will remain in PENDING identity status until OTP verification is completed. You cannot create campaigns until the brand is VERIFIED.

Step 2: Trigger OTP Verification

Send an OTP PIN to the mobile phone associated with the brand:

curl

curl -X POST https://api.telnyx.com/v2/10dlc/brand/{brand_id}/smsOtp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "pinSms": "Your Telnyx verification code is @OTP_PIN@. This code expires in 24 hours.",
    "successSms": "Your Telnyx 10DLC brand has been verified successfully."
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messaging10dlc.brand.triggerSMSOtp(
  'f5586561-8ff0-4291-a0ac-84fe544797bd',
  {
    pinSms: 'Your Telnyx verification code is @OTP_PIN@. This code expires in 24 hours.',
    successSms: 'Your Telnyx 10DLC brand has been verified successfully.',
  }
);

console.log(response.referenceId);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messaging_10dlc.brand.trigger_sms_otp(
    brand_id="f5586561-8ff0-4291-a0ac-84fe544797bd",
    pin_sms="Your Telnyx verification code is @OTP_PIN@. This code expires in 24 hours.",
    success_sms="Your Telnyx 10DLC brand has been verified successfully.",
)

print(response.reference_id)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messaging_10dlc.brand.trigger_sms_otp(
  "f5586561-8ff0-4291-a0ac-84fe544797bd",
  pin_sms: "Your Telnyx verification code is @OTP_PIN@. This code expires in 24 hours.",
  success_sms: "Your Telnyx 10DLC brand has been verified successfully."
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messaging10dlc.Brand.TriggerSMSOtp(
    context.TODO(),
    "f5586561-8ff0-4291-a0ac-84fe544797bd",
    telnyx.Messaging10dlcBrandTriggerSMSOtpParams{
      PinSMS:     "Your Telnyx verification code is @OTP_PIN@. This code expires in 24 hours.",
      SuccessSMS: "Your Telnyx 10DLC brand has been verified successfully.",
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Reference ID: %s\n", response.ReferenceID)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messaging10dlc.brand.BrandTriggerSmsOtpParams;
import com.telnyx.sdk.models.messaging10dlc.brand.BrandTriggerSmsOtpResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        BrandTriggerSmsOtpParams params = BrandTriggerSmsOtpParams.builder()
            .brandId("f5586561-8ff0-4291-a0ac-84fe544797bd")
            .pinSms("Your Telnyx verification code is @OTP_PIN@. This code expires in 24 hours.")
            .successSms("Your Telnyx 10DLC brand has been verified successfully.")
            .build();

        BrandTriggerSmsOtpResponse response = client.messaging10dlc().brand().triggerSmsOtp(params);
        System.out.println("Reference ID: " + response.referenceId());
    }
}

Request Parameters

Parameter	Type	Required	Description
`pinSms`	string	Yes	SMS message containing `@OTP_PIN@` placeholder (max 500 chars)
`successSms`	string	Yes	Confirmation SMS sent after successful verification (max 500 chars)

Response

{
  "brandId": "f5586561-8ff0-4291-a0ac-84fe544797bd",
  "referenceId": "OTP8A3B2C"
}

The @OTP_PIN@ placeholder in pinSms will be replaced with the actual 6-digit PIN when the SMS is sent.

Step 3: Check OTP Status

Poll the OTP status to confirm delivery:

curl

curl -X GET https://api.telnyx.com/v2/10dlc/brand/{brand_id}/smsOtp \
  -H "Authorization: Bearer YOUR_API_KEY"

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const status = await client.messaging10dlc.brand.retrieveSMSOtpStatus(
  'f5586561-8ff0-4291-a0ac-84fe544797bd'
);

console.log(status.deliveryStatus);
console.log(status.verifyDate);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

status = client.messaging_10dlc.brand.retrieve_sms_otp_status(
    "f5586561-8ff0-4291-a0ac-84fe544797bd",
)

print(status.delivery_status)
print(status.verify_date)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

status = client.messaging_10dlc.brand.retrieve_sms_otp_status(
  "f5586561-8ff0-4291-a0ac-84fe544797bd"
)

puts(status)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  status, err := client.Messaging10dlc.Brand.RetrieveSMSOtpStatus(
    context.TODO(),
    "f5586561-8ff0-4291-a0ac-84fe544797bd",
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Delivery Status: %s\n", status.DeliveryStatus)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messaging10dlc.brand.BrandSmsOtpStatus;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        BrandSmsOtpStatus status = client.messaging10dlc()
            .brand()
            .retrieveSmsOtpStatus("f5586561-8ff0-4291-a0ac-84fe544797bd");

        System.out.println("Delivery Status: " + status.deliveryStatus());
    }
}

Response

{
  "brandId": "f5586561-8ff0-4291-a0ac-84fe544797bd",
  "referenceId": "OTP8A3B2C",
  "mobilePhone": "+12025559876",
  "requestDate": "2026-02-03T12:05:00Z",
  "verifyDate": null,
  "deliveryStatus": "DELIVERED_HANDSET",
  "deliveryStatusDate": "2026-02-03T12:05:02Z",
  "deliveryStatusDetails": "Delivered to handset"
}

Delivery Status Values

Status	Description
`PENDING`	OTP request submitted, awaiting delivery
`DELIVERED_HANDSET`	SMS delivered to the mobile device
`DELIVERY_FAILED`	SMS delivery failed
`VERIFIED`	OTP PIN successfully verified
`EXPIRED`	OTP PIN expired (24-hour window)

Step 4: Verify OTP PIN

After the user receives and provides the PIN, verify it:

curl

curl -X PUT https://api.telnyx.com/v2/10dlc/brand/{brand_id}/smsOtp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "otpPin": "123456"
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

await client.messaging10dlc.brand.verifySMSOtp(
  'f5586561-8ff0-4291-a0ac-84fe544797bd',
  { otpPin: '123456' }
);

console.log('Brand verified successfully');

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

client.messaging_10dlc.brand.verify_sms_otp(
    brand_id="f5586561-8ff0-4291-a0ac-84fe544797bd",
    otp_pin="123456",
)

print("Brand verified successfully")

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

client.messaging_10dlc.brand.verify_sms_otp(
  "f5586561-8ff0-4291-a0ac-84fe544797bd",
  otp_pin: "123456"
)

puts("Brand verified successfully")

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  err := client.Messaging10dlc.Brand.VerifySMSOtp(
    context.TODO(),
    "f5586561-8ff0-4291-a0ac-84fe544797bd",
    telnyx.Messaging10dlcBrandVerifySMSOtpParams{
      OtpPin: "123456",
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Println("Brand verified successfully")
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messaging10dlc.brand.BrandVerifySmsOtpParams;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        BrandVerifySmsOtpParams params = BrandVerifySmsOtpParams.builder()
            .brandId("f5586561-8ff0-4291-a0ac-84fe544797bd")
            .otpPin("123456")
            .build();

        client.messaging10dlc().brand().verifySmsOtp(params);
        System.out.println("Brand verified successfully");
    }
}

Upon successful verification:

The brand identityStatus changes to VERIFIED
The successSms message is sent to the mobile phone
The brand registration fee is charged
You can now create campaigns

Step 5: Create a Sole Proprietor Campaign

With a verified brand, create a campaign using the SOLE_PROPRIETOR usecase: Sample messages (sample1, sample2) are required for campaign approval. Include realistic examples of messages you’ll send.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/campaignBuilder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "brandId": "f5586561-8ff0-4291-a0ac-84fe544797bd",
    "usecase": "SOLE_PROPRIETOR",
    "description": "Customer appointment reminders and booking confirmations for consulting services.",
    "messageFlow": "Customers opt-in via web form when booking appointments. They receive confirmation and reminder messages.",
    "helpMessage": "Reply HELP for assistance. Contact support@example.com",
    "optoutMessage": "Reply STOP to unsubscribe from messages.",
    "sample1": "Hi Jane, this is a reminder of your appointment tomorrow at 2pm.",
    "sample2": "Your booking for March 15th has been confirmed. Reply STOP to opt out.",
    "termsAndConditions": true
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const campaign = await client.messaging10dlc.campaignBuilder.submit({
  brandId: 'f5586561-8ff0-4291-a0ac-84fe544797bd',
  usecase: 'SOLE_PROPRIETOR',
  description: 'Customer appointment reminders and booking confirmations for consulting services.',
  messageFlow: 'Customers opt-in via web form when booking appointments. They receive confirmation and reminder messages.',
  helpMessage: 'Reply HELP for assistance. Contact support@example.com',
  optoutMessage: 'Reply STOP to unsubscribe from messages.',
  sample1: 'Hi Jane, this is a reminder of your appointment tomorrow at 2pm.',
  sample2: 'Your booking for March 15th has been confirmed. Reply STOP to opt out.',
  termsAndConditions: true,
});

console.log(campaign.campaignId);
console.log(campaign.status);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

campaign = client.messaging_10dlc.campaign_builder.submit(
    brand_id="f5586561-8ff0-4291-a0ac-84fe544797bd",
    usecase="SOLE_PROPRIETOR",
    description="Customer appointment reminders and booking confirmations for consulting services.",
    message_flow="Customers opt-in via web form when booking appointments. They receive confirmation and reminder messages.",
    help_message="Reply HELP for assistance. Contact support@example.com",
    optout_message="Reply STOP to unsubscribe from messages.",
    sample1="Hi Jane, this is a reminder of your appointment tomorrow at 2pm.",
    sample2="Your booking for March 15th has been confirmed. Reply STOP to opt out.",
    terms_and_conditions=True,
)

print(campaign.campaign_id)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

campaign = client.messaging_10dlc.campaign_builder.submit(
  brand_id: "f5586561-8ff0-4291-a0ac-84fe544797bd",
  usecase: "SOLE_PROPRIETOR",
  description: "Customer appointment reminders and booking confirmations for consulting services.",
  message_flow: "Customers opt-in via web form when booking appointments. They receive confirmation and reminder messages.",
  help_message: "Reply HELP for assistance. Contact support@example.com",
  optout_message: "Reply STOP to unsubscribe from messages.",
  sample1: "Hi Jane, this is a reminder of your appointment tomorrow at 2pm.",
  sample2: "Your booking for March 15th has been confirmed. Reply STOP to opt out.",
  terms_and_conditions: true
)

puts(campaign)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  campaign, err := client.Messaging10dlc.CampaignBuilder.Submit(context.TODO(), telnyx.Messaging10dlcCampaignBuilderSubmitParams{
    BrandID:            "f5586561-8ff0-4291-a0ac-84fe544797bd",
    Usecase:            "SOLE_PROPRIETOR",
    Description:        "Customer appointment reminders and booking confirmations for consulting services.",
    MessageFlow:        "Customers opt-in via web form when booking appointments. They receive confirmation and reminder messages.",
    HelpMessage:        "Reply HELP for assistance. Contact support@example.com",
    OptoutMessage:      "Reply STOP to unsubscribe from messages.",
    Sample1:            "Hi Jane, this is a reminder of your appointment tomorrow at 2pm.",
    Sample2:            "Your booking for March 15th has been confirmed. Reply STOP to opt out.",
    TermsAndConditions: true,
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Campaign ID: %s\n", campaign.CampaignID)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messaging10dlc.campaign.TelnyxCampaignCsp;
import com.telnyx.sdk.models.messaging10dlc.campaignbuilder.CampaignBuilderSubmitParams;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        CampaignBuilderSubmitParams params = CampaignBuilderSubmitParams.builder()
            .brandId("f5586561-8ff0-4291-a0ac-84fe544797bd")
            .usecase("SOLE_PROPRIETOR")
            .description("Customer appointment reminders and booking confirmations for consulting services.")
            .messageFlow("Customers opt-in via web form when booking appointments. They receive confirmation and reminder messages.")
            .helpMessage("Reply HELP for assistance. Contact support@example.com")
            .optoutMessage("Reply STOP to unsubscribe from messages.")
            .sample1("Hi Jane, this is a reminder of your appointment tomorrow at 2pm.")
            .sample2("Your booking for March 15th has been confirmed. Reply STOP to opt out.")
            .termsAndConditions(true)
            .build();

        TelnyxCampaignCsp campaign = client.messaging10dlc().campaignBuilder().submit(params);
        System.out.println("Campaign ID: " + campaign.campaignId());
    }
}

Response

{
  "campaignId": "c5e5e598-95b3-4076-bfe2-c7d2c58ec57f",
  "brandId": "f5586561-8ff0-4291-a0ac-84fe544797bd",
  "usecase": "SOLE_PROPRIETOR",
  "status": "ACTIVE",
  "description": "Customer appointment reminders and booking confirmations for consulting services.",
  "createdAt": "2026-02-03T12:30:00Z"
}

Sole Proprietor campaigns are typically auto-approved and become ACTIVE immediately. Standard campaigns may require carrier review.

Step 6: Assign a Phone Number

Assign your 10DLC number to the campaign:

curl

curl -X POST https://api.telnyx.com/v2/10dlc/phone_number_campaigns \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+12025551234",
    "campaignId": "campaign_id_here"
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const assignment = await client.messaging10dlc.phoneNumberCampaigns.create({
  phoneNumber: '+12025551234',
  campaignId: 'campaign_id_here',
});

console.log(assignment.campaignId);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

assignment = client.messaging_10dlc.phone_number_campaigns.create(
    phone_number="+12025551234",
    campaign_id="campaign_id_here",
)

print(assignment.campaign_id)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

assignment = client.messaging_10dlc.phone_number_campaigns.create(
  phone_number: "+12025551234",
  campaign_id: "campaign_id_here"
)

puts(assignment)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  assignment, err := client.Messaging10dlc.PhoneNumberCampaigns.New(context.TODO(), telnyx.Messaging10dlcPhoneNumberCampaignNewParams{
    PhoneNumberCampaignCreate: telnyx.PhoneNumberCampaignCreateParam{
      PhoneNumber: "+12025551234",
      CampaignID:  "campaign_id_here",
    },
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("Assignment: %+v\n", assignment)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messaging10dlc.phonenumbercampaigns.PhoneNumberCampaign;
import com.telnyx.sdk.models.messaging10dlc.phonenumbercampaigns.PhoneNumberCampaignCreate;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        PhoneNumberCampaignCreate params = PhoneNumberCampaignCreate.builder()
            .phoneNumber("+12025551234")
            .campaignId("campaign_id_here")
            .build();

        PhoneNumberCampaign assignment = client.messaging10dlc().phoneNumberCampaigns().create(params);
        System.out.println("Campaign ID: " + assignment.campaignId());
    }
}

Sole Proprietor campaigns can only have one phone number assigned. Attempting to assign additional numbers will return an error.

Error Handling

Common Errors

Error	Cause	Solution
`Sole Proprietor brands can only have one active campaign`	Attempting to create a second campaign	Delete or deactivate existing campaign first
`Sole Proprietor campaigns can only have one phone number assigned`	Attempting to assign multiple numbers	Use only one number per SP campaign
`Cannot associate campaign with brand in pending or failed status`	Brand not verified	Complete OTP verification first
`OTP PIN expired`	24-hour verification window exceeded	Trigger a new OTP with `POST /10dlc/brand/{id}/smsOtp`

Retrying OTP

If the OTP expires or the user needs a new PIN, simply call the trigger endpoint again:

curl -X POST https://api.telnyx.com/v2/10dlc/brand/{brand_id}/smsOtp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "pinSms": "Your new Telnyx verification code is @OTP_PIN@. This code expires in 24 hours.",
    "successSms": "Your Telnyx 10DLC brand has been verified successfully."
  }'

Fees

Item	Amount	Frequency
Brand Registration	$4.00	One-time (charged after verification)
Campaign Vetting	$15.00	Per submission
Monthly Maintenance	$2.00	Monthly

Webhooks

Subscribe to brand and campaign status updates via webhooks. See 10DLC Event Notifications for details on:

10dlc.brand.update — Brand status and identity verification changes
10dlc.campaign.update — Campaign approval/rejection
10dlc.phone_number.update — Phone number assignment status

Next Steps

Understand throughput limits for Sole Proprietor campaigns Set up webhooks for status updates Full API documentation for brand management Portal walkthrough for non-API users

Brand Registration

Source: https://developers.telnyx.com/docs/messaging/10dlc/brand-registration.md

A brand is your registered business identity in the 10DLC ecosystem. Before you can create messaging campaigns or send A2P messages on US long codes, you must register your brand with The Campaign Registry (TCR) through the Telnyx API. Your brand’s vetting score directly determines your messaging throughput limits.

Prerequisites

A Telnyx account with API access
Your API key
Business information: legal name, EIN/Tax ID, address, phone, email, website

For Sole Proprietor registration (individuals without an EIN), see the Sole Proprietor guide. This guide covers standard business brand registration.

Brand entity types

TCR supports several entity types. Choose the one that matches your business structure:

Entity Type	API Value	Description	Vetting Required
Private for-profit	`PRIVATE_PROFIT`	Private companies (LLC, Inc, etc.)	Yes
Public for-profit	`PUBLIC_PROFIT`	Publicly traded companies	Yes
Non-profit	`NON_PROFIT`	501(c)(3) or equivalent	Yes
Government	`GOVERNMENT`	Federal, state, or local government	Yes
Sole Proprietor	`SOLE_PROPRIETOR`	Individuals without EIN	OTP only

Sole Proprietor brands have significant limitations: 1 campaign, 1 phone number, low throughput. Use standard registration if your business has an EIN.

Registration flow

Step 1: Create a brand

Required fields

Field	Type	Description
`entityType`	string	Business entity type (see table above)
`displayName`	string	Brand display name (shown to carriers)
`companyName`	string	Legal company name (must match EIN records)
`ein`	string	Federal Tax ID / EIN (format: `XX-XXXXXXX`)
`phone`	string	Business phone in E.164 format
`street`	string	Business street address
`city`	string	City
`state`	string	State (2-letter abbreviation)
`postalCode`	string	ZIP code
`country`	string	Country code (`US` or `CA`)
`email`	string	Business contact email
`website`	string	Business website URL
`vertical`	string	Industry vertical (see verticals list)

Optional fields

Field	Type	Description
`altBusinessId`	string	Alternative business ID (DUNS, GIIN, LEI)
`altBusinessIdType`	string	Type of alternative ID: `DUNS`, `GIIN`, or `LEI`
`stockSymbol`	string	Stock ticker (required for `PUBLIC_PROFIT`)
`stockExchange`	string	Exchange: `NYSE`, `NASDAQ`, `AMEX`, etc.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/brand \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "entityType": "PRIVATE_PROFIT",
    "displayName": "Acme Corp",
    "companyName": "Acme Corporation",
    "ein": "12-3456789",
    "phone": "+15551234567",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US",
    "email": "admin@acmecorp.com",
    "website": "https://acmecorp.com",
    "vertical": "TECHNOLOGY"
  }'

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

brand_data = {
    "entityType": "PRIVATE_PROFIT",
    "displayName": "Acme Corp",
    "companyName": "Acme Corporation",
    "ein": "12-3456789",
    "phone": "+15551234567",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US",
    "email": "admin@acmecorp.com",
    "website": "https://acmecorp.com",
    "vertical": "TECHNOLOGY",
}

response = requests.post(
    "https://api.telnyx.com/v2/10dlc/brand",
    headers=headers,
    json=brand_data,
)
brand = response.json()
brand_id = brand["data"]["brandId"]
print(f"Brand created: {brand_id}")
print(f"Status: {brand['data']['identityStatus']}")

Node

const axios = require('axios');

const API_KEY = process.env.TELNYX_API_KEY;
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

const brandData = {
  entityType: 'PRIVATE_PROFIT',
  displayName: 'Acme Corp',
  companyName: 'Acme Corporation',
  ein: '12-3456789',
  phone: '+15551234567',
  street: '123 Main St',
  city: 'New York',
  state: 'NY',
  postalCode: '10001',
  country: 'US',
  email: 'admin@acmecorp.com',
  website: 'https://acmecorp.com',
  vertical: 'TECHNOLOGY',
};

const { data: brand } = await axios.post(
  'https://api.telnyx.com/v2/10dlc/brand',
  brandData,
  { headers }
);
console.log(`Brand created: ${brand.data.brandId}`);
console.log(`Status: ${brand.data.identityStatus}`);

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.telnyx.com/v2/10dlc/brand")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = {
  entityType: "PRIVATE_PROFIT",
  displayName: "Acme Corp",
  companyName: "Acme Corporation",
  ein: "12-3456789",
  phone: "+15551234567",
  street: "123 Main St",
  city: "New York",
  state: "NY",
  postalCode: "10001",
  country: "US",
  email: "admin@acmecorp.com",
  website: "https://acmecorp.com",
  vertical: "TECHNOLOGY"
}.to_json

response = http.request(request)
brand = JSON.parse(response.body)
puts "Brand created: #{brand['data']['brandId']}"
puts "Status: #{brand['data']['identityStatus']}"

Java

import java.net.http.*;
import java.net.URI;

String apiKey = System.getenv("TELNYX_API_KEY");
String body = """
  {
    "entityType": "PRIVATE_PROFIT",
    "displayName": "Acme Corp",
    "companyName": "Acme Corporation",
    "ein": "12-3456789",
    "phone": "+15551234567",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US",
    "email": "admin@acmecorp.com",
    "website": "https://acmecorp.com",
    "vertical": "TECHNOLOGY"
  }
  """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.telnyx.com/v2/10dlc/brand"))
    .header("Authorization", "Bearer " + apiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Brand response: " + response.body());

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var apiKey = Environment.GetEnvironmentVariable("TELNYX_API_KEY");
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

var brandData = new
{
    entityType = "PRIVATE_PROFIT",
    displayName = "Acme Corp",
    companyName = "Acme Corporation",
    ein = "12-3456789",
    phone = "+15551234567",
    street = "123 Main St",
    city = "New York",
    state = "NY",
    postalCode = "10001",
    country = "US",
    email = "admin@acmecorp.com",
    website = "https://acmecorp.com",
    vertical = "TECHNOLOGY"
};

var content = new StringContent(
    JsonSerializer.Serialize(brandData),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://api.telnyx.com/v2/10dlc/brand", content
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Brand response: {result}");

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');

$brandData = [
    'entityType'  => 'PRIVATE_PROFIT',
    'displayName' => 'Acme Corp',
    'companyName'  => 'Acme Corporation',
    'ein'          => '12-3456789',
    'phone'        => '+15551234567',
    'street'       => '123 Main St',
    'city'         => 'New York',
    'state'        => 'NY',
    'postalCode'   => '10001',
    'country'      => 'US',
    'email'        => 'admin@acmecorp.com',
    'website'      => 'https://acmecorp.com',
    'vertical'     => 'TECHNOLOGY',
];

$ch = curl_init('https://api.telnyx.com/v2/10dlc/brand');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer {$apiKey}",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($brandData),
]);

$response = curl_exec($ch);
curl_close($ch);

$brand = json_decode($response, true);
echo "Brand created: " . $brand['data']['brandId'] . "\n";
echo "Status: " . $brand['data']['identityStatus'] . "\n";

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  brandData := map[string]string{
    "entityType":  "PRIVATE_PROFIT",
    "displayName": "Acme Corp",
    "companyName":  "Acme Corporation",
    "ein":          "12-3456789",
    "phone":        "+15551234567",
    "street":       "123 Main St",
    "city":         "New York",
    "state":        "NY",
    "postalCode":   "10001",
    "country":      "US",
    "email":        "admin@acmecorp.com",
    "website":      "https://acmecorp.com",
    "vertical":     "TECHNOLOGY",
  }

  body, _ := json.Marshal(brandData)
  req, _ := http.NewRequest("POST", "https://api.telnyx.com/v2/10dlc/brand", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
  }
  defer resp.Body.Close()

  result, _ := io.ReadAll(resp.Body)
  fmt.Printf("Brand response: %s\n", result)
}

Brand creation response

{
  "data": {
    "brandId": "BXXXXXX",
    "entityType": "PRIVATE_PROFIT",
    "displayName": "Acme Corp",
    "companyName": "Acme Corporation",
    "ein": "12-3456789",
    "identityStatus": "VERIFIED",
    "cspId": "TELNYX",
    "brandRelationship": "BASIC_ACCOUNT",
    "vertical": "TECHNOLOGY",
    "phone": "+15551234567",
    "email": "admin@acmecorp.com",
    "website": "https://acmecorp.com",
    "country": "US",
    "state": "NY",
    "city": "New York",
    "street": "123 Main St",
    "postalCode": "10001"
  }
}

Step 2: Retrieve brand details

After creation, check your brand status and details:

curl

curl -X GET https://api.telnyx.com/v2/10dlc/brand/BXXXXXX \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.get(
    f"https://api.telnyx.com/v2/10dlc/brand/{brand_id}",
    headers=headers,
)
brand_details = response.json()
print(f"Identity status: {brand_details['data']['identityStatus']}")

Node

const { data: details } = await axios.get(
  `https://api.telnyx.com/v2/10dlc/brand/${brandId}`,
  { headers }
);
console.log(`Identity status: ${details.data.identityStatus}`);

Ruby

uri = URI("https://api.telnyx.com/v2/10dlc/brand/#{brand_id}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"

response = http.request(request)
details = JSON.parse(response.body)
puts "Identity status: #{details['data']['identityStatus']}"

Brand statuses

Status	Meaning
`SELF_DECLARED`	Brand created, not yet verified
`VERIFIED`	Identity verified by TCR
`VETTED_VERIFIED`	Third-party vetting completed
`UNVERIFIED`	Verification failed — see troubleshooting

Step 3: Submit for external vetting

Vetting is performed by a third-party partner (e.g., Campaign Verify) and produces a trust score from 0 to 100 that directly impacts your messaging throughput.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/brand/BXXXXXX/externalVetting \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "evpId": "AEGIS",
    "vettingClass": "STANDARD"
  }'

Python

vetting_response = requests.post(
    f"https://api.telnyx.com/v2/10dlc/brand/{brand_id}/externalVetting",
    headers=headers,
    json={
        "evpId": "AEGIS",
        "vettingClass": "STANDARD",
    },
)
print(f"Vetting submitted: {vetting_response.json()}")

Node

const { data: vetting } = await axios.post(
  `https://api.telnyx.com/v2/10dlc/brand/${brandId}/externalVetting`,
  { evpId: 'AEGIS', vettingClass: 'STANDARD' },
  { headers }
);
console.log('Vetting submitted:', vetting);

Ruby

uri = URI("https://api.telnyx.com/v2/10dlc/brand/#{brand_id}/externalVetting")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = { evpId: "AEGIS", vettingClass: "STANDARD" }.to_json

response = http.request(request)
puts "Vetting submitted: #{response.body}"

Idempotency: Submitting the same evpId + vettingClass for a brand that already has a successful vetting (within the last 180 days) or one currently being processed returns 400 with error code 10012 (“Duplicate resource”). Failed vettings are excluded from this check, so you can retry immediately after a real failure. To retrieve existing vettings, use GET /v2/10dlc/brand/{brandId}/externalVetting.

Vetting classes

Class	Cost	Use Case
`STANDARD`	~$4	Default for most brands
`ENHANCED`	~$40	Higher trust scores, faster approval

Vetting score impact on throughput

Your vetting score directly controls your carrier-specific throughput. See the 10DLC Rate Limits guide for detailed carrier tables.

Score Range	T-Mobile Throughput	AT&T Throughput	Category
0–24	2,000/day	1 MPS	Low
25–49	10,000/day	4 MPS	Medium-Low
50–74	50,000/day	10 MPS	Medium
75–89	100,000/day	25 MPS	High
90–100	200,000+/day	75 MPS	Highest

Without vetting, brands default to the lowest throughput tier. Always submit for vetting before creating campaigns.

Step 4: Check vetting results

Vetting typically takes 1–7 business days. You can poll or use webhooks to check the result.

curl

# List external vettings for a brand
curl -X GET https://api.telnyx.com/v2/10dlc/brand/BXXXXXX/externalVetting \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.get(
    f"https://api.telnyx.com/v2/10dlc/brand/{brand_id}/externalVetting",
    headers=headers,
)
vettings = response.json()
for v in vettings.get("data", []):
    print(f"Score: {v.get('vettingScore')} | Status: {v.get('vettingStatus')}")

Node

const { data: vettings } = await axios.get(
  `https://api.telnyx.com/v2/10dlc/brand/${brandId}/externalVetting`,
  { headers }
);
vettings.data.forEach(v => {
  console.log(`Score: ${v.vettingScore} | Status: ${v.vettingStatus}`);
});

Step 5: Update a brand

If your brand details change (address, phone, etc.), update them via the API:

curl

curl -X PUT https://api.telnyx.com/v2/10dlc/brand/BXXXXXX \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "phone": "+15559876543",
    "email": "newemail@acmecorp.com",
    "website": "https://www.acmecorp.com"
  }'

Python

response = requests.put(
    f"https://api.telnyx.com/v2/10dlc/brand/{brand_id}",
    headers=headers,
    json={
        "phone": "+15559876543",
        "email": "newemail@acmecorp.com",
        "website": "https://www.acmecorp.com",
    },
)
print(f"Brand updated: {response.json()['data']['brandId']}")

Node

const { data: updated } = await axios.put(
  `https://api.telnyx.com/v2/10dlc/brand/${brandId}`,
  {
    phone: '+15559876543',
    email: 'newemail@acmecorp.com',
    website: 'https://www.acmecorp.com',
  },
  { headers }
);
console.log(`Brand updated: ${updated.data.brandId}`);

Updating certain fields (company name, EIN) may trigger re-verification. Contact support if you need to change core identity fields.

List all brands

Retrieve all registered brands on your account:

curl

curl -X GET "https://api.telnyx.com/v2/10dlc/brand?page[size]=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.get(
    "https://api.telnyx.com/v2/10dlc/brand",
    headers=headers,
    params={"page[size]": 25},
)
brands = response.json()
for b in brands.get("data", []):
    print(f"{b['brandId']}: {b['displayName']} ({b['identityStatus']})")

Node

const { data: brands } = await axios.get(
  'https://api.telnyx.com/v2/10dlc/brand',
  { headers, params: { 'page[size]': 25 } }
);
brands.data.forEach(b => {
  console.log(`${b.brandId}: ${b.displayName} (${b.identityStatus})`);
});

Common rejection reasons and fixes

Cause: The companyName field doesn’t match what the IRS has on file for that EIN. Fix: Use your exact legal name as registered with the IRS. Check your EIN confirmation letter (CP 575) or search the IRS tax-exempt organization database for non-profits. Cause: EIN must be in XX-XXXXXXX format (9 digits with a hyphen after the first 2). Fix: Double-check your EIN. It should look like 12-3456789. Don’t include spaces or extra characters. Cause: The vetting partner couldn’t access your website, or the website content doesn’t match the registered business. Fix: Ensure your website is live, publicly accessible (no authentication required), and has content that clearly identifies your business. The domain should ideally match your business email domain. Cause: The business phone number provided is not a valid, reachable US/CA number. Fix: Provide a working business phone number in E.164 format (e.g., +15551234567). The number should be answerable during business hours. Cause: The provided address doesn’t match USPS records or can’t be verified. Fix: Use your exact business address as registered. Verify it through USPS address lookup. Cause: A brand with this EIN is already registered (possibly by another CSP or a previous registration). Fix: You can only have one brand per EIN. If you previously registered through another provider, you may need to import or transfer the brand. Contact Telnyx support for assistance.

Appeal process

If your brand is rejected or receives a low vetting score, you can appeal: Check the brand’s identityStatus and any associated error messages via the API or Mission Control Portal. Update your brand information to address the specific rejection reason using the update brand API. After updating your brand, submit a new external vetting request. Each vetting submission incurs a fee. For complex cases (EIN transfers, duplicate brands, identity disputes), contact Telnyx support with your brandId and details. Re-vetting after fixing issues often results in a higher score. The most common improvement is ensuring your website, company name, and EIN all align.

Industry verticals

When creating a brand, specify your industry using one of these vertical values:

Vertical	API Value
Professional Services	`PROFESSIONAL`
Real Estate	`REAL_ESTATE`
Healthcare	`HEALTHCARE`
Human Resources	`HUMAN_RESOURCES`
Energy	`ENERGY`
Entertainment	`ENTERTAINMENT`
Retail	`RETAIL`
Transportation	`TRANSPORTATION`
Agriculture	`AGRICULTURE`
Insurance	`INSURANCE`
Postal	`POSTAL`
Education	`EDUCATION`
Hospitality	`HOSPITALITY`
Financial	`FINANCIAL`
Political	`POLITICAL`
Gambling	`GAMBLING`
Legal	`LEGAL`
Construction	`CONSTRUCTION`
NGO	`NGO`
Manufacturing	`MANUFACTURING`
Government	`GOVERNMENT`
Technology	`TECHNOLOGY`
Communication	`COMMUNICATION`

Webhook notifications

Telnyx sends webhooks for brand lifecycle events. Configure your webhook URL on your messaging profile or via the API.

Event	Description
`brand.created`	Brand successfully registered with TCR
`brand.updated`	Brand details updated
`brand.vetted`	External vetting completed (includes score)
`brand.deleted`	Brand deleted

See 10DLC Event Notifications for payload examples and webhook handling.

Next steps

Register your messaging use case after your brand is vetted. Understand how your vetting score impacts throughput. Registration guide for individuals without an EIN. Track brand and campaign lifecycle via webhooks.

Campaign Registration

Source: https://developers.telnyx.com/docs/messaging/10dlc/campaign-registration.md

A 10DLC campaign defines your messaging use case — what you’re sending, who you’re sending to, and how recipients opted in. Every campaign must be registered with The Campaign Registry (TCR) and approved by mobile carriers before you can send messages at scale. This guide walks you through creating campaigns via API and Portal, choosing the right use case, writing sample messages that pass carrier review, and handling rejections. Prerequisites: You need an approved brand before creating campaigns. Your brand’s vetting score affects campaign throughput — see 10DLC Rate Limits.

Campaign use case types

Choose the use case that best describes your messaging. Carriers review this against your sample messages, so accuracy matters.

Standard use cases

Use Case	Description	Example
`CUSTOMER_CARE`	Support and service messages	”Your ticket #4521 has been updated. View details at…”
`DELIVERY_NOTIFICATION`	Order and shipping updates	”Your package shipped! Tracking: 1Z999…”
`ACCOUNT_NOTIFICATION`	Account alerts and changes	”Your password was changed. If this wasn’t you, call…”
`MARKETING`	Promotional content	”Summer sale! 30% off all items this weekend…”
`2FA`	Two-factor authentication codes	”Your verification code is 847291. Expires in 10 min.”
`SECURITY_ALERT`	Security-related notifications	”New login detected from Chrome on Windows…”
`POLLING_VOTING`	Surveys and polls	”How was your experience? Reply 1-5.”
`CHARITY`	Nonprofit fundraising and awareness	”Thanks for supporting Habitat! Text DONATE for…”
`POLITICAL`	Political campaigns and advocacy	”Reminder: Vote on Nov 5th. Find your polling place…”
`MIXED`	Multiple message types (most common)	Combination of the above

Special use cases

Use Case	Description	Requirements
`LOW_VOLUME`	Under 6,000 messages/month	Simplified registration
`SOLE_PROPRIETOR`	Individual/small business without EIN	See Sole Proprietor guide
`EMERGENCY`	Life-threatening alerts	Must demonstrate emergency nature
`AGENTS_FRANCHISES`	ISVs sending on behalf of clients	Additional compliance requirements
`SWEEPSTAKES`	Contests and giveaways	Must include rules and terms

Choose carefully. Changing a campaign’s use case after registration requires creating a new campaign. Carriers reject campaigns where sample messages don’t match the declared use case.

Create a campaign

Required fields

Field	Type	Description
`brandId`	string	Your registered brand ID
`usecase`	string	Use case type (see table above)
`description`	string	What your campaign does (2-4 sentences)
`sample1`	string	First sample message
`sample2`	string	Second sample message
`messageFlow`	string	How users opt in to receive messages
`helpMessage`	string	Response to HELP keyword
`optinKeywords`	string	Comma-separated opt-in keywords
`optoutKeywords`	string	Comma-separated opt-out keywords
`helpKeywords`	string	Comma-separated help keywords

Optional fields

Field	Type	Default	Description
`embeddedLink`	boolean	`false`	Messages contain URLs
`embeddedPhone`	boolean	`false`	Messages contain phone numbers
`numberPool`	boolean	`false`	Using number pool for sending
`ageGated`	boolean	`false`	Content requires age verification
`directLending`	boolean	`false`	Related to direct lending
`subscriberOptin`	boolean	`true`	Subscribers have opted in
`subscriberOptout`	boolean	`true`	Subscribers can opt out
`subscriberHelp`	boolean	`true`	Help keyword is supported
`sample3`	string	—	Third sample message (recommended)
`sample4`	string	—	Fourth sample message
`sample5`	string	—	Fifth sample message

curl

curl -X POST https://api.telnyx.com/v2/10dlc/campaignBuilder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "brandId": "BRAND_ID",
    "usecase": "DELIVERY_NOTIFICATION",
    "description": "Order confirmation and delivery status updates for e-commerce customers who purchase through our website.",
    "sample1": "Hi {{name}}, your order #{{orderId}} has been confirmed! Estimated delivery: {{date}}. Track at https://acme.com/track/{{orderId}} Reply STOP to opt out.",
    "sample2": "Great news! Your package is out for delivery and should arrive by 5 PM today. Driver: {{driverName}}. Reply STOP to unsubscribe.",
    "sample3": "Your order #{{orderId}} has been delivered to your front door. Rate your experience: https://acme.com/review/{{orderId}}",
    "messageFlow": "Customers opt in at checkout by checking a consent box that reads: I agree to receive order updates via SMS. Frequency varies. Msg & data rates may apply.",
    "helpMessage": "Acme Corp order updates. For help, visit https://acme.com/support or call +15551234567. Reply STOP to cancel.",
    "optinKeywords": "START, YES, SUBSCRIBE",
    "optoutKeywords": "STOP, UNSUBSCRIBE, CANCEL, QUIT",
    "helpKeywords": "HELP, INFO",
    "embeddedLink": true,
    "numberPool": false,
    "ageGated": false
  }'

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

campaign_data = {
    "brandId": "BRAND_ID",
    "usecase": "DELIVERY_NOTIFICATION",
    "description": (
        "Order confirmation and delivery status updates for "
        "e-commerce customers who purchase through our website."
    ),
    "sample1": (
        "Hi {{name}}, your order #{{orderId}} has been confirmed! "
        "Estimated delivery: {{date}}. Track at "
        "https://acme.com/track/{{orderId}} Reply STOP to opt out."
    ),
    "sample2": (
        "Great news! Your package is out for delivery and should "
        "arrive by 5 PM today. Reply STOP to unsubscribe."
    ),
    "sample3": (
        "Your order #{{orderId}} has been delivered to your front "
        "door. Rate your experience: https://acme.com/review/{{orderId}}"
    ),
    "messageFlow": (
        "Customers opt in at checkout by checking a consent box."
    ),
    "helpMessage": (
        "Acme Corp order updates. For help, visit "
        "https://acme.com/support or call +15551234567. "
        "Reply STOP to cancel."
    ),
    "optinKeywords": "START, YES, SUBSCRIBE",
    "optoutKeywords": "STOP, UNSUBSCRIBE, CANCEL, QUIT",
    "helpKeywords": "HELP, INFO",
    "embeddedLink": True,
    "numberPool": False,
    "ageGated": False,
}

response = requests.post(
    "https://api.telnyx.com/v2/10dlc/campaignBuilder",
    headers=headers,
    json=campaign_data,
)
campaign = response.json()
print(f"Campaign ID: {campaign['data']['campaignId']}")
print(f"Status: {campaign['data']['status']}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
  'Content-Type': 'application/json',
};

const campaignData = {
  brandId: 'BRAND_ID',
  usecase: 'DELIVERY_NOTIFICATION',
  description:
    'Order confirmation and delivery status updates for e-commerce customers.',
  sample1:
    'Hi {{name}}, your order #{{orderId}} has been confirmed! Track at https://acme.com/track/{{orderId}} Reply STOP to opt out.',
  sample2:
    'Great news! Your package is out for delivery and should arrive by 5 PM today. Reply STOP to unsubscribe.',
  sample3:
    'Your order #{{orderId}} has been delivered. Rate your experience: https://acme.com/review/{{orderId}}',
  messageFlow: 'Customers opt in at checkout by checking a consent box.',
  helpMessage:
    'Acme Corp order updates. For help, visit https://acme.com/support. Reply STOP to cancel.',
  optinKeywords: 'START, YES, SUBSCRIBE',
  optoutKeywords: 'STOP, UNSUBSCRIBE, CANCEL, QUIT',
  helpKeywords: 'HELP, INFO',
  embeddedLink: true,
  numberPool: false,
  ageGated: false,
};

const response = await axios.post(
  'https://api.telnyx.com/v2/10dlc/campaignBuilder',
  campaignData,
  { headers }
);

console.log(`Campaign ID: ${response.data.data.campaignId}`);
console.log(`Status: ${response.data.data.status}`);

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.telnyx.com/v2/10dlc/campaignBuilder")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = {
  brandId: "BRAND_ID",
  usecase: "DELIVERY_NOTIFICATION",
  description: "Order confirmation and delivery status updates.",
  sample1: "Hi {{name}}, your order #{{orderId}} confirmed! Reply STOP to opt out.",
  sample2: "Your package is out for delivery. Reply STOP to unsubscribe.",
  messageFlow: "Customers opt in at checkout.",
  helpMessage: "For help visit https://acme.com/support. Reply STOP to cancel.",
  optinKeywords: "START, YES, SUBSCRIBE",
  optoutKeywords: "STOP, UNSUBSCRIBE, CANCEL, QUIT",
  helpKeywords: "HELP, INFO",
  embeddedLink: true,
  numberPool: false,
  ageGated: false
}.to_json

response = http.request(request)
campaign = JSON.parse(response.body)
puts "Campaign ID: #{campaign['data']['campaignId']}"

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func main() {
  campaignData := map[string]interface{}{
    "brandId":        "BRAND_ID",
    "usecase":        "DELIVERY_NOTIFICATION",
    "description":    "Order confirmation and delivery status updates.",
    "sample1":        "Hi {{name}}, your order #{{orderId}} confirmed! Reply STOP to opt out.",
    "sample2":        "Your package is out for delivery. Reply STOP to unsubscribe.",
    "messageFlow":    "Customers opt in at checkout.",
    "helpMessage":    "For help visit https://acme.com/support. Reply STOP to cancel.",
    "optinKeywords":  "START, YES, SUBSCRIBE",
    "optoutKeywords": "STOP, UNSUBSCRIBE, CANCEL, QUIT",
    "helpKeywords":   "HELP, INFO",
    "embeddedLink":   true,
    "numberPool":     false,
    "ageGated":       false,
  }

  body, _ := json.Marshal(campaignData)
  req, _ := http.NewRequest("POST", "https://api.telnyx.com/v2/10dlc/campaignBuilder", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  data := result["data"].(map[string]interface{})
  fmt.Printf("Campaign ID: %s\n", data["campaignId"])
}

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');

$campaignData = [
    'brandId' => 'BRAND_ID',
    'usecase' => 'DELIVERY_NOTIFICATION',
    'description' => 'Order confirmation and delivery status updates.',
    'sample1' => 'Hi {{name}}, your order #{{orderId}} confirmed! Reply STOP to opt out.',
    'sample2' => 'Your package is out for delivery. Reply STOP to unsubscribe.',
    'messageFlow' => 'Customers opt in at checkout.',
    'helpMessage' => 'For help visit https://acme.com/support. Reply STOP to cancel.',
    'optinKeywords' => 'START, YES, SUBSCRIBE',
    'optoutKeywords' => 'STOP, UNSUBSCRIBE, CANCEL, QUIT',
    'helpKeywords' => 'HELP, INFO',
    'embeddedLink' => true,
    'numberPool' => false,
    'ageGated' => false,
];

$ch = curl_init('https://api.telnyx.com/v2/10dlc/campaignBuilder');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($campaignData),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Campaign ID: {$response['data']['campaignId']}\n";
echo "Status: {$response['data']['status']}\n";

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var apiKey = Environment.GetEnvironmentVariable("TELNYX_API_KEY");
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

var campaignData = new
{
    brandId = "BRAND_ID",
    usecase = "DELIVERY_NOTIFICATION",
    description = "Order confirmation and delivery status updates.",
    sample1 = "Hi {{name}}, your order #{{orderId}} confirmed! Reply STOP to opt out.",
    sample2 = "Your package is out for delivery. Reply STOP to unsubscribe.",
    messageFlow = "Customers opt in at checkout.",
    helpMessage = "For help visit https://acme.com/support. Reply STOP to cancel.",
    optinKeywords = "START, YES, SUBSCRIBE",
    optoutKeywords = "STOP, UNSUBSCRIBE, CANCEL, QUIT",
    helpKeywords = "HELP, INFO",
    embeddedLink = true,
    numberPool = false,
    ageGated = false,
};

var json = JsonSerializer.Serialize(campaignData);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(
    "https://api.telnyx.com/v2/10dlc/campaignBuilder", content);
var result = await response.Content.ReadAsStringAsync();

using var doc = JsonDocument.Parse(result);
var data = doc.RootElement.GetProperty("data");
Console.WriteLine($"Campaign ID: {data.GetProperty("campaignId")}");

Go to Campaigns in Mission Control and click Create New Campaign. Choose the brand this campaign belongs to. If you haven’t created one yet, see the Quickstart. Select the use case that best describes your messaging purpose. See the use case table above for guidance. Review the carrier terms and your brand’s vetting score. Click Next to continue. Fill in your campaign description, sample messages, message flow (opt-in process), and keyword responses (HELP, STOP). Set campaign attributes like embedded links and age gating. Accept the terms and conditions and click Submit. Your campaign enters carrier review.

Writing sample messages that pass review

Carriers manually review your sample messages. Poorly written samples are the #1 reason campaigns get rejected. Every sample should include opt-out instructions:

“Your order #12345 has shipped! Track at https://acme.com/track/12345. Reply STOP to unsubscribe.”

Use real-looking content with your actual brand name:

“Hi Sarah, your Acme Corp appointment is confirmed for Tuesday at 2 PM. Reply YES to confirm or HELP for assistance.”

If your use case is DELIVERY_NOTIFICATION, all samples should be about deliveries:

✅ “Your package has shipped via FedEx. Tracking: 1Z999AA10123456784” ❌ “Check out our summer sale! 30% off everything!” (This is marketing, not delivery)

Carriers reject vague samples:

❌ “This is a test message” ❌ “Hello, this is a message from our company”

Carriers prohibit or restrict:

Cannabis / CBD messaging
Gambling content (varies by state)
Firearms sales
Payday lending
Content targeting minors without age gate

The messageFlow field should explain exactly how users consent:

“Users sign up on our website at https://acme.com/signup where they enter their phone number and check a box that reads: ‘I agree to receive order updates via SMS from Acme Corp. Msg frequency varies. Msg & data rates may apply. Reply STOP to cancel.’”

MNO provisioning timeline

After TCR approves your campaign, each carrier (MNO) provisions it on their network independently. This affects when you can send messages on each carrier.

Carrier	Typical Timeline	Notes
T-Mobile	Instant to 24 hours	Usually the fastest
AT&T	1-3 business days	May require additional review for some use cases
Verizon	1-3 business days	—
US Cellular	3-5 business days	Smaller carrier, longer provisioning

You can check provisioning status per carrier via the API:

curl -s https://api.telnyx.com/v2/10dlc/campaignBuilder/{campaignId} \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data.mnoMetadata'

Check campaign status

curl

# Get campaign details
curl -s https://api.telnyx.com/v2/10dlc/campaignBuilder/{campaignId} \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '{
    status: .data.status,
    usecase: .data.usecase,
    brandId: .data.brandId,
    createDate: .data.createDate
  }'

Python

response = requests.get(
    f"https://api.telnyx.com/v2/10dlc/campaignBuilder/{campaign_id}",
    headers=headers,
)
campaign = response.json()["data"]
print(f"Status: {campaign['status']}")
print(f"Use case: {campaign['usecase']}")

Node

const response = await axios.get(
  `https://api.telnyx.com/v2/10dlc/campaignBuilder/${campaignId}`,
  { headers }
);

console.log(`Status: ${response.data.data.status}`);
console.log(`Use case: ${response.data.data.usecase}`);

Campaign statuses

Status	Meaning
`ACTIVE`	Approved and ready to send
`EXPIRED`	Campaign expired (renew required)
`SUSPENDED`	Suspended by carrier — contact support

List all campaigns

curl

curl -s https://api.telnyx.com/v2/10dlc/campaignBuilder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G -d "page[size]=20"

Python

response = requests.get(
    "https://api.telnyx.com/v2/10dlc/campaignBuilder",
    headers=headers,
    params={"page[size]": 20},
)
campaigns = response.json()["data"]
for c in campaigns:
    print(f"{c['campaignId']} | {c['usecase']} | {c['status']}")

Node

const response = await axios.get(
  'https://api.telnyx.com/v2/10dlc/campaignBuilder',
  {
    headers,
    params: { 'page[size]': 20 },
  }
);

response.data.data.forEach((c) => {
  console.log(`${c.campaignId} | ${c.usecase} | ${c.status}`);
});

Handle campaign rejections

Campaigns can be rejected during carrier review. Common reasons and how to fix them:

Rejection Reason	Fix
Samples don’t match use case	Rewrite samples to match your declared use case exactly
Missing opt-out language	Add “Reply STOP to unsubscribe” to every sample
Vague message flow	Describe the exact opt-in mechanism (website form, checkout checkbox, etc.)
Prohibited content	Remove restricted content (cannabis, gambling, etc.)
Brand not vetted	Complete brand vetting before resubmitting

Resubmitting a rejected campaign

You cannot edit a rejected campaign. Instead, create a new campaign with corrected information:

Review the rejection reason (check Event Notifications webhooks)
Fix the identified issues in your samples and description
Create a new campaign via the API or Portal
Reassign your phone numbers to the new campaign

Each campaign submission incurs a TCR registration fee. Review your samples carefully before submitting to avoid repeated rejections and fees.

Campaign compliance best practices

Only send messages that match your registered campaign use case. Sending marketing from a CUSTOMER_CARE campaign risks suspension. Process STOP requests within seconds. Carriers monitor compliance. See Advanced Opt-In/Out for implementation. Maintain proof of consent (opt-in records with timestamp, source, and phone number). Carriers may request this during audits. Don’t exceed your campaign’s allocated throughput. Check 10DLC Rate Limits for your brand score tier. Set up webhooks for 10DLC events to catch approval, rejection, and suspension events in real time.

Competitor comparison

Feature	Telnyx	Twilio	Vonage
Campaign creation	API + Portal	API + Console	API + Dashboard
Use case types	15+ standard types	Similar TCR types	Similar TCR types
Sample messages	2 required, up to 5	2 required	2 required
MNO status visibility	Per-carrier status via API	Per-carrier status	Limited visibility
Rejection handling	Create new campaign	Create new campaign	Create new campaign

Next steps

Link phone numbers to your campaign to start sending. Understand throughput based on your brand’s vetting score. Receive real-time webhooks for campaign status changes. Start sending once your campaign is approved.

Use Case Examples

Source: https://developers.telnyx.com/docs/messaging/10dlc/campaign-use-cases.md

Writing good sample messages is the #1 factor in getting your 10DLC campaign approved. Carriers reject campaigns when sample messages don’t match the declared use case, lack opt-out language, or look like spam. This guide provides ready-to-use sample messages, compliant opt-in language, and content patterns for every campaign use case type. How carriers review sample messages:

Must match the declared use case type
Must include opt-out language (STOP to opt out)
Must represent actual messages you’ll send
Vague or generic samples get rejected

Standard use cases

2FA / Two-Factor Authentication

The simplest use case — short, transactional, no marketing content. Sample 1:

Your Acme verification code is 847291. This code expires in 10 minutes. If you didn't request this, ignore this message.

Sample 2:

Your login code for Acme is 523016. Don't share this code with anyone. Reply STOP to opt out.

Sample 3:

Acme security code: 194738. Enter this code to complete your password reset. This code expires in 5 minutes.

By entering your phone number, you agree to receive one-time verification
codes from [Brand] via SMS. Message frequency varies. Message and data rates
may apply. Reply STOP to opt out.

Keep messages under 160 characters
Include the code prominently
Add an expiry time
Don’t include marketing content or links
Brand name should appear in the message

API example — registering a 2FA campaign:

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"

campaign = telnyx.TenDLCCampaign.create(
    brand_id="B000001",
    usecase="2FA",
    description="One-time verification codes for user login and password reset",
    sample1="Your Acme verification code is 847291. This code expires in 10 minutes.",
    sample2="Your login code for Acme is 523016. Don't share this code with anyone. Reply STOP to opt out.",
    sample3="Acme security code: 194738. Enter this code to complete your password reset.",
    message_flow="Users enter their phone number during login or password reset. A one-time code is sent via SMS. Users enter the code to authenticate.",
    help_message="Reply HELP for support or contact support@acme.com",
    optin_message="By entering your phone number, you agree to receive verification codes from Acme via SMS. Reply STOP to opt out.",
)
print(campaign.campaign_id)

Node.js

const telnyx = require('telnyx')('YOUR_API_KEY');

const campaign = await telnyx.tenDlcCampaigns.create({
  brand_id: 'B000001',
  usecase: '2FA',
  description: 'One-time verification codes for user login and password reset',
  sample1: 'Your Acme verification code is 847291. This code expires in 10 minutes.',
  sample2: "Your login code for Acme is 523016. Don't share this code with anyone. Reply STOP to opt out.",
  sample3: 'Acme security code: 194738. Enter this code to complete your password reset.',
  message_flow: 'Users enter their phone number during login or password reset. A one-time code is sent via SMS.',
  help_message: 'Reply HELP for support or contact support@acme.com',
  optin_message: 'By entering your phone number, you agree to receive verification codes from Acme via SMS. Reply STOP to opt out.',
});
console.log(campaign.data.campaign_id);

Ruby

require 'telnyx'

Telnyx.api_key = 'YOUR_API_KEY'

campaign = Telnyx::TenDlcCampaign.create(
  brand_id: 'B000001',
  usecase: '2FA',
  description: 'One-time verification codes for user login and password reset',
  sample1: 'Your Acme verification code is 847291. This code expires in 10 minutes.',
  sample2: "Your login code for Acme is 523016. Don't share this code with anyone. Reply STOP to opt out.",
  sample3: 'Acme security code: 194738. Enter this code to complete your password reset.',
  message_flow: 'Users enter their phone number during login or password reset.',
  help_message: 'Reply HELP for support or contact support@acme.com',
  optin_message: 'By entering your phone number, you agree to receive verification codes from Acme via SMS. Reply STOP to opt out.',
)
puts campaign.campaign_id

Java

import com.telnyx.sdk.ApiClient;
import com.telnyx.sdk.api.TenDlcApi;
import com.telnyx.sdk.model.CreateTenDlcCampaignRequest;

ApiClient client = new ApiClient();
client.setApiKey("YOUR_API_KEY");
TenDlcApi api = new TenDlcApi(client);

CreateTenDlcCampaignRequest request = new CreateTenDlcCampaignRequest()
    .brandId("B000001")
    .usecase("2FA")
    .description("One-time verification codes for user login and password reset")
    .sample1("Your Acme verification code is 847291. This code expires in 10 minutes.")
    .sample2("Your login code for Acme is 523016. Don't share this code with anyone. Reply STOP to opt out.")
    .sample3("Acme security code: 194738. Enter this code to complete your password reset.")
    .messageFlow("Users enter their phone number during login or password reset.")
    .helpMessage("Reply HELP for support or contact support@acme.com")
    .optinMessage("By entering your phone number, you agree to receive verification codes from Acme via SMS. Reply STOP to opt out.");

var campaign = api.createTenDlcCampaign(request);
System.out.println(campaign.getData().getCampaignId());

.NET

using Telnyx.net;

TelnyxConfiguration.SetApiKey("YOUR_API_KEY");

var service = new TenDlcCampaignService();
var campaign = service.Create(new TenDlcCampaignCreateOptions
{
    BrandId = "B000001",
    Usecase = "2FA",
    Description = "One-time verification codes for user login and password reset",
    Sample1 = "Your Acme verification code is 847291. This code expires in 10 minutes.",
    Sample2 = "Your login code for Acme is 523016. Don't share this code with anyone. Reply STOP to opt out.",
    Sample3 = "Acme security code: 194738. Enter this code to complete your password reset.",
    MessageFlow = "Users enter their phone number during login or password reset.",
    HelpMessage = "Reply HELP for support or contact support@acme.com",
    OptinMessage = "By entering your phone number, you agree to receive verification codes from Acme via SMS. Reply STOP to opt out.",
});
Console.WriteLine(campaign.CampaignId);

PHP

$telnyx = new \Telnyx\Telnyx('YOUR_API_KEY');

$campaign = \Telnyx\TenDlcCampaign::create([
    'brand_id' => 'B000001',
    'usecase' => '2FA',
    'description' => 'One-time verification codes for user login and password reset',
    'sample1' => 'Your Acme verification code is 847291. This code expires in 10 minutes.',
    'sample2' => "Your login code for Acme is 523016. Don't share this code with anyone. Reply STOP to opt out.",
    'sample3' => 'Acme security code: 194738. Enter this code to complete your password reset.',
    'message_flow' => 'Users enter their phone number during login or password reset.',
    'help_message' => 'Reply HELP for support or contact support@acme.com',
    'optin_message' => 'By entering your phone number, you agree to receive verification codes from Acme via SMS. Reply STOP to opt out.',
]);
echo $campaign->campaign_id;

package main

import (
    "fmt"
    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient("YOUR_API_KEY")

    campaign, err := client.TenDlc.Campaigns.Create(&telnyx.TenDlcCampaignParams{
        BrandID:     "B000001",
        Usecase:     "2FA",
        Description: "One-time verification codes for user login and password reset",
        Sample1:     "Your Acme verification code is 847291. This code expires in 10 minutes.",
        Sample2:     "Your login code for Acme is 523016. Don't share this code with anyone. Reply STOP to opt out.",
        Sample3:     "Acme security code: 194738. Enter this code to complete your password reset.",
        MessageFlow: "Users enter their phone number during login or password reset.",
        HelpMessage: "Reply HELP for support or contact support@acme.com",
        OptinMessage: "By entering your phone number, you agree to receive verification codes from Acme via SMS. Reply STOP to opt out.",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(campaign.CampaignID)
}

Customer Care

Support conversations, ticket updates, and service messages. Sample 1:

Hi [Name], your support ticket #4521 has been updated. Our team has responded — view details at support.acme.com/tickets/4521. Reply STOP to opt out.

Sample 2:

Acme Support: Your return request for order #8834 has been approved. A prepaid label has been sent to your email. Questions? Reply HELP.

Sample 3:

Your appointment with Acme Support is confirmed for March 15 at 2:00 PM EST. Reply YES to confirm or RESCHEDULE to change. Reply STOP to unsubscribe.

By providing your phone number, you consent to receive customer service
messages from [Brand] via SMS, including support ticket updates, appointment
reminders, and service notifications. Message frequency varies. Msg & data
rates may apply. Reply HELP for help, STOP to cancel.

Messages should be reactive (responding to customer actions)
Include ticket/order numbers for context
Don’t mix in promotional content
Keep a helpful, service-oriented tone
Include brand name in every message

Delivery Notifications

Order confirmations, shipping updates, and delivery status. Sample 1:

Acme: Your order #99281 has shipped! Tracking: 1Z999AA10123456784. Estimated delivery: March 18. Track at acme.com/track. Reply STOP to opt out.

Sample 2:

Your Acme delivery is out for delivery and will arrive today between 2-6 PM. A photo confirmation will be sent upon delivery. Reply STOP to unsubscribe.

Sample 3:

Acme: Your package was delivered at 3:42 PM and left at front door. View delivery photo at acme.com/orders/99281. Reply STOP to opt out.

By placing an order, you agree to receive shipping and delivery updates from
[Brand] via SMS. Message frequency varies based on order activity. Msg & data
rates may apply. Reply STOP to cancel, HELP for help.

Include order/tracking numbers
Messages should follow the order lifecycle
Include delivery estimates when available
Don’t add promotional upsells in delivery messages

Account Notifications

Password changes, billing alerts, account activity. Sample 1:

Acme: Your password was successfully changed on March 4, 2026. If you didn't make this change, contact support immediately at 1-800-555-0199. Reply STOP to opt out.

Sample 2:

Acme billing alert: Your payment of $49.99 was processed successfully. Your next billing date is April 4, 2026. View invoice at acme.com/billing. Reply STOP to unsubscribe.

Sample 3:

Acme: Your subscription plan was upgraded to Pro. Your new monthly rate is $79.99, effective immediately. Questions? Reply HELP. Reply STOP to opt out.

By creating an account, you consent to receive account-related notifications
from [Brand] via SMS, including billing alerts, password changes, and account
updates. Msg frequency varies. Msg & data rates apply. Reply STOP to cancel.

Focus on account changes the user initiated
Include specific details (amounts, dates)
Provide a way to verify or dispute changes
Never include marketing in account notifications

Marketing

Promotions, sales, product announcements, and brand content. Marketing campaigns receive the most scrutiny. Opt-in must be explicit and separate from terms of service. Sample 1:

Acme Summer Sale! 🎉 Get 30% off all items this weekend only. Use code SUMMER30 at checkout. Shop now: acme.com/sale. Reply STOP to opt out.

Sample 2:

New at Acme: Our spring collection just dropped! Be the first to shop 50+ new styles starting at $19.99. Browse: acme.com/new. Txt STOP to unsubscribe.

Sample 3:

Acme: Thanks for being a loyal customer! Here's an exclusive 20% off coupon just for you. Use code VIP20 by March 31. Shop: acme.com. Reply STOP to cancel.

By checking this box, you agree to receive recurring marketing messages from
[Brand] via SMS, including promotions, sales, and product updates. Consent is
not a condition of purchase. Message frequency varies (up to 8 msgs/month).
Msg & data rates may apply. Reply HELP for help, STOP to unsubscribe.
View our Privacy Policy at [link] and Terms at [link].

Opt-in MUST be separate from ToS (not buried in fine print)
Include message frequency estimate
State “consent is not a condition of purchase”
Link to privacy policy and terms
Every message must include opt-out language
Don’t use ALL CAPS excessively
Include brand name in every message

Security Alerts

Acme security alert: New login detected from Chrome on Windows in New York, NY at 3:42 PM EST. If this wasn't you, secure your account: acme.com/security. Reply STOP to opt out.

Sample 2:

Acme: Unusual activity detected on your account. A purchase of $299.99 was attempted. If this wasn't you, reply BLOCK or call 1-800-555-0199. Reply STOP to unsubscribe.

Sample 3:

Acme: Your account recovery email was changed. If you made this change, no action needed. If not, contact security immediately at 1-800-555-0199. Reply STOP to opt out.

By enabling security alerts, you agree to receive security notifications from
[Brand] via SMS, including login alerts, fraud detection, and account security
updates. Message frequency varies based on account activity. Msg & data rates
may apply. Reply STOP to cancel.

Include specific details (device, location, time)
Always provide a way to take action
Keep urgency appropriate — don’t create false panic
These are high-priority; carriers are lenient but still review

Polling & Voting

Surveys, feedback requests, and interactive polls. Sample 1:

Acme: How was your recent purchase? Rate your experience 1-5 (1=poor, 5=excellent). Your feedback helps us improve! Reply STOP to opt out.

Sample 2:

Acme customer survey: Would you recommend us to a friend? Reply YES or NO. As a thank you, get 10% off your next order. Reply STOP to unsubscribe.

Sample 3:

Acme: Quick poll — which new feature matters most to you? Reply A) Faster shipping B) More colors C) Lower prices. Reply STOP to opt out.

By opting in, you agree to receive occasional survey and feedback requests
from [Brand] via SMS. Message frequency: up to 2 msgs/month. Msg & data
rates may apply. Reply STOP to opt out, HELP for help.

Keep surveys short (1-2 questions per message)
Make responses simple (numbers, YES/NO, letters)
Don’t disguise marketing as surveys
Include clear opt-out in every message

Charity / Nonprofit

Fundraising, awareness campaigns, and donation acknowledgments. Sample 1:

Habitat for Hope: Thanks to donors like you, we built 12 homes this month! See the impact at habitatforhope.org/impact. Reply STOP to opt out.

Sample 2:

Habitat for Hope: Our spring fundraiser starts March 15! Your $25 donation provides building materials for a family in need. Donate: habitatforhope.org/give. Reply STOP to unsubscribe.

Sample 3:

Thank you for your $50 donation to Habitat for Hope! Your tax receipt has been emailed. Together we're building stronger communities. Reply STOP to opt out.

By texting JOIN to [number], you agree to receive updates from [Nonprofit]
via SMS, including impact updates, fundraising campaigns, and donation
receipts. Msg frequency varies (up to 4 msgs/month). Msg & data rates apply.
Reply STOP to cancel, HELP for help.

Clearly identify your nonprofit in every message
Show impact, not just ask for money
Include donation receipts/acknowledgments
Link to your organization’s website

Mixed (Most Common)

Multiple message types from a single campaign. This is the most frequently used use case. Sample 1 (transactional):

Acme: Your order #77412 has shipped and will arrive by March 18. Track at acme.com/track. Reply STOP to opt out.

Sample 2 (support):

Acme Support: Your ticket #2291 has been resolved. If you need further help, reply to this message or visit support.acme.com. Reply STOP to unsubscribe.

Sample 3 (promotional):

Acme: Spring sale starts tomorrow! Get early access with code SPRING25 for 25% off. Shop: acme.com/sale. Reply STOP to opt out.

By providing your phone number, you consent to receive messages from [Brand]
via SMS, including order updates, customer support notifications, and
promotional offers. Message frequency varies. Msg & data rates may apply.
Consent is not required for purchase. Reply HELP for help, STOP to cancel.
View our Privacy Policy at [link].

Each sample should demonstrate a DIFFERENT message type
Opt-in must mention ALL types of messages (transactional + marketing)
If you include marketing, follow marketing opt-in rules
Description should list all message categories
This is the safest choice if you’re unsure which use case to pick

Special use cases

Low Volume

For brands sending fewer than 6,000 messages per month. Simplified registration with reduced documentation. Same as whatever your primary use case is — low volume is about throughput, not content type. Use samples from the relevant standard use case above.

Best for small businesses with limited messaging needs
Lower throughput limits (75 messages/minute on T-Mobile)
Cannot be upgraded to standard — must create a new campaign
Still requires compliant opt-in and opt-out

Sole Proprietor

For individuals or small businesses without an EIN. See the full Sole Proprietor guide.

Emergency

For life-safety alerts. Requires demonstrating genuine emergency nature. Sample 1:

EMERGENCY ALERT: Severe weather warning for your area. Tornado watch until 8 PM. Seek shelter immediately. Details: alerts.example.com. Reply STOP to opt out.

Sample 2:

SafeAlert: Building evacuation in progress at 123 Main St. Exit via stairwell B. Do NOT use elevators. All clear will be sent when safe. Reply STOP to opt out.

Must be genuinely life-safety related
Carriers may grant higher throughput
Don’t abuse this category — misuse leads to suspension

Writing compliant sample messages

Do’s and don’ts

Include your brand name in every message
Add opt-out language (STOP to opt out)
Use specific, realistic content
Match samples to your declared use case
Show the actual format you’ll send
Include 3 distinct sample messages
Use generic placeholder text (“Hello, this is a test”)
Mix marketing into transactional use cases
Use ALL CAPS for entire messages
Include URL shorteners (bit.ly, tinyurl)
Copy samples from other brands
Submit identical or near-identical samples

Opt-out language requirements

Every campaign must support these keywords:

Keyword	Required Response
`STOP`	”You have been unsubscribed from [Brand] messages. No more messages will be sent. Reply START to resubscribe.”
`HELP`	”[Brand] support: For help, visit [url] or call [number]. Msg & data rates may apply. Msg frequency varies. Reply STOP to cancel.”
`START` / `UNSTOP`	”You have been resubscribed to [Brand] messages. Reply STOP to opt out, HELP for help.”

Telnyx handles STOP/START/HELP keyword processing automatically when Advanced Opt-Out is enabled on your messaging profile.

Message flow description

Your campaign’s message_flow field should clearly describe how users opt in. Carriers look for: How does the user first provide their phone number? (Website form, checkout, text-to-join keyword, etc.) How is consent captured? (Checkbox, keyword reply, verbal confirmation, etc.) What happens after opt-in? (Welcome message, double opt-in confirmation, etc.) What kinds of messages will the user receive? Example message flow:

Customers opt in by checking a consent checkbox during online checkout at
acme.com/checkout. After opting in, they receive a welcome message confirming
their subscription. They then receive order confirmations, shipping updates,
and delivery notifications related to their purchases. Customers can opt out
at any time by replying STOP.

Common rejection reasons

Rejection Reason	Fix
Sample messages don’t match use case	Rewrite samples to clearly demonstrate your declared use case
Missing opt-out language	Add “Reply STOP to opt out” to every sample
Vague or generic samples	Use specific, realistic content with your brand name
Inadequate opt-in description	Detail the exact opt-in flow (where, how, what users see)
URL shorteners used	Use full branded URLs (acme.com/track, not bit.ly/abc)
Samples too similar	Make each sample distinctly different
Marketing content in non-marketing use case	Remove promotional language or switch to MIXED use case

For detailed troubleshooting of campaign rejections, see the 10DLC Troubleshooting Guide.

ISV/Reseller Onboarding

Source: https://developers.telnyx.com/docs/messaging/10dlc/isv-reseller-onboarding.md

If you’re an ISV, reseller, or SaaS platform sending messages on behalf of your customers, you need a partner campaign architecture — not a standard 10DLC registration. This guide covers everything from initial setup through production messaging. Quick links: Architecture overview · Step-by-step setup · Managing customers at scale · Troubleshooting

Who needs this guide?

Scenario	You are…	Your architecture
SaaS platform	Building messaging into your product	Partner campaign (shared across customers)
Reseller / agency	Managing messaging for clients	One brand + campaign per client, or shared
ISV	Offering white-label messaging	Partner campaign with downstream CSPs

Direct customer? If you’re sending messages for your own business only, use the standard 10DLC quickstart instead.

Architecture overview

ISV/reseller 10DLC uses a shared campaign model where you register campaigns with your upstream CSP (Campaign Service Provider) and share them to Telnyx for number assignment and messaging.

Key concepts

The Campaign Service Provider where you register brands and campaigns with TCR. This could be Telnyx (if you register directly) or another CSP. The messaging provider that sends traffic. Telnyx acts as your downstream CSP — you share campaigns to Telnyx for number assignment. A campaign registered at one CSP and shared to another for traffic delivery. Required for ISV architectures. The TCR process of granting a downstream CSP access to send traffic for a campaign. Sharing must be accepted by the downstream CSP.

Native vs. partner campaigns

Feature	Native Campaign	Partner (Shared) Campaign
Registration	Directly on Telnyx	On upstream CSP, shared to Telnyx
Brand ownership	Your Telnyx account	Your upstream CSP account
Campaign management	Telnyx API	Upstream CSP + Telnyx Partner API
Number assignment	Standard	Via partner campaign endpoints
Use case	Direct customer	ISV, reseller, multi-tenant
Appeal process	Direct API	CSP nudge mechanism

Prerequisites

Before starting, ensure you have: Sign up and complete account verification. You need a Level 2 verified account. An account with a CSP where you’ll register brands and campaigns (this can be Telnyx or another provider like Campaign Registry direct access). For each customer: legal business name, EIN/tax ID, business address, website, authorized representative contact, and messaging use case details. 10DLC-eligible long code numbers on your Telnyx account. Purchase numbers or use existing inventory.

Step-by-step ISV onboarding

Step 1: Register brands for each customer

Each of your customers needs their own brand registered with TCR. A brand represents a business entity. If using Telnyx as your upstream CSP, register brands directly:

curl

curl -X POST https://api.telnyx.com/v2/10dlc/brand \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "PRIVATE_PROFIT",
    "companyName": "Customer Corp LLC",
    "ein": "12-3456789",
    "einIssuingCountry": "US",
    "phone": "+12025551234",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US",
    "email": "compliance@customercorp.com",
    "website": "https://customercorp.com",
    "vertical": "TECHNOLOGY",
    "displayName": "Customer Corp"
  }'

Python

import telnyx
import os

telnyx.api_key = os.environ["TELNYX_API_KEY"]

brand = telnyx.Brand.create(
    entity_type="PRIVATE_PROFIT",
    company_name="Customer Corp LLC",
    ein="12-3456789",
    ein_issuing_country="US",
    phone="+12025551234",
    street="123 Main St",
    city="New York",
    state="NY",
    postal_code="10001",
    country="US",
    email="compliance@customercorp.com",
    website="https://customercorp.com",
    vertical="TECHNOLOGY",
    display_name="Customer Corp",
)
print(f"Brand ID: {brand.id}")

Node

import Telnyx from "telnyx";

const telnyx = new Telnyx(process.env.TELNYX_API_KEY);

const { data: brand } = await telnyx.messaging10dlc.brands.create({
  entityType: "PRIVATE_PROFIT",
  companyName: "Customer Corp LLC",
  ein: "12-3456789",
  einIssuingCountry: "US",
  phone: "+12025551234",
  street: "123 Main St",
  city: "New York",
  state: "NY",
  postalCode: "10001",
  country: "US",
  email: "compliance@customercorp.com",
  website: "https://customercorp.com",
  vertical: "TECHNOLOGY",
  displayName: "Customer Corp",
});
console.log(`Brand ID: ${brand.id}`);

Ruby

require "telnyx"

Telnyx.api_key = ENV["TELNYX_API_KEY"]

brand = Telnyx::Brand.create(
  entity_type: "PRIVATE_PROFIT",
  company_name: "Customer Corp LLC",
  ein: "12-3456789",
  ein_issuing_country: "US",
  phone: "+12025551234",
  street: "123 Main St",
  city: "New York",
  state: "NY",
  postal_code: "10001",
  country: "US",
  email: "compliance@customercorp.com",
  website: "https://customercorp.com",
  vertical: "TECHNOLOGY",
  display_name: "Customer Corp"
)
puts "Brand ID: #{brand.id}"

Java

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messaging10dlc.brands.BrandCreateParams;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

var brand = client.messaging10dlc().brands().create(BrandCreateParams.builder()
    .entityType("PRIVATE_PROFIT")
    .companyName("Customer Corp LLC")
    .ein("12-3456789")
    .einIssuingCountry("US")
    .phone("+12025551234")
    .street("123 Main St")
    .city("New York")
    .state("NY")
    .postalCode("10001")
    .country("US")
    .email("compliance@customercorp.com")
    .website("https://customercorp.com")
    .vertical("TECHNOLOGY")
    .displayName("Customer Corp")
    .build());
System.out.println("Brand ID: " + brand.id());

.NET

using Telnyx;

var client = new TelnyxClient(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var brand = await client.Messaging10dlc.Brands.CreateAsync(new BrandCreateParams
{
    EntityType = "PRIVATE_PROFIT",
    CompanyName = "Customer Corp LLC",
    Ein = "12-3456789",
    EinIssuingCountry = "US",
    Phone = "+12025551234",
    Street = "123 Main St",
    City = "New York",
    State = "NY",
    PostalCode = "10001",
    Country = "US",
    Email = "compliance@customercorp.com",
    Website = "https://customercorp.com",
    Vertical = "TECHNOLOGY",
    DisplayName = "Customer Corp"
});
Console.WriteLine($"Brand ID: {brand.Id}");

PHP

$telnyx = new \Telnyx\TelnyxClient(getenv('TELNYX_API_KEY'));

$brand = $telnyx->messaging10dlc->brands->create([
    'entity_type' => 'PRIVATE_PROFIT',
    'company_name' => 'Customer Corp LLC',
    'ein' => '12-3456789',
    'ein_issuing_country' => 'US',
    'phone' => '+12025551234',
    'street' => '123 Main St',
    'city' => 'New York',
    'state' => 'NY',
    'postal_code' => '10001',
    'country' => 'US',
    'email' => 'compliance@customercorp.com',
    'website' => 'https://customercorp.com',
    'vertical' => 'TECHNOLOGY',
    'display_name' => 'Customer Corp',
]);
echo "Brand ID: " . $brand->id . "\n";

package main

import (
    "context"
    "fmt"
    "github.com/team-telnyx/telnyx-go"
    "github.com/team-telnyx/telnyx-go/option"
)

func main() {
    client := telnyx.NewClient(
        option.WithAPIKey("YOUR_API_KEY"),
    )
    brand, err := client.Messaging10dlc.Brands.New(context.TODO(), telnyx.Messaging10dlcBrandNewParams{
        EntityType:       telnyx.String("PRIVATE_PROFIT"),
        CompanyName:      telnyx.String("Customer Corp LLC"),
        Ein:              telnyx.String("12-3456789"),
        EinIssuingCountry: telnyx.String("US"),
        Phone:            telnyx.String("+12025551234"),
        Street:           telnyx.String("123 Main St"),
        City:             telnyx.String("New York"),
        State:            telnyx.String("NY"),
        PostalCode:       telnyx.String("10001"),
        Country:          telnyx.String("US"),
        Email:            telnyx.String("compliance@customercorp.com"),
        Website:          telnyx.String("https://customercorp.com"),
        Vertical:         telnyx.String("TECHNOLOGY"),
        DisplayName:      telnyx.String("Customer Corp"),
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Brand ID: %s\n", brand.ID)
}

If using an external CSP (e.g., direct TCR access), register brands through their API and note the TCR Brand ID (format: BXXXXXX). You’ll need this when sharing campaigns to Telnyx.

Step 2: Submit brand for vetting

Higher vetting scores unlock greater throughput. For ISV use cases, enhanced vetting is strongly recommended.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/brand/{brandId}/vetting \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vettingClass": "ENHANCED"}'

Enhanced vetting costs a one-time fee and takes 1–7 business days. Brands with vetting scores above 75 get significantly higher throughput. See 10DLC Rate Limits for details.

Step 3: Create campaigns for each customer

Create one campaign per customer, selecting the use case that matches the actual message content your platform sends. See the campaign registration docs for the full list of supported use cases.

curl

curl -X POST https://api.telnyx.com/v2/10dlc/campaign \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "BRAND_ID",
    "usecase": "CUSTOMER_CARE",
    "description": "Platform notifications sent on behalf of Customer Corp customers",
    "sample1": "Hi {name}, your appointment is confirmed for {date} at {time}. Reply STOP to opt out.",
    "sample2": "Your order #{order_id} has shipped! Track at {url}. Reply STOP to unsubscribe.",
    "messageFlow": "Users opt in via web form at customercorp.com/sms-signup with clear consent language. STOP/HELP keywords are honored.",
    "helpMessage": "Customer Corp support: help@customercorp.com or call 1-800-555-0123. Reply STOP to opt out.",
    "optinKeywords": "START,YES,SUBSCRIBE",
    "optoutKeywords": "STOP,CANCEL,UNSUBSCRIBE,QUIT,END",
    "helpKeywords": "HELP,INFO",
    "numberPool": false,
    "subscriberOptin": true,
    "subscriberOptout": true,
    "subscriberHelp": true,
    "embeddedLink": true,
    "embeddedPhone": false
  }'

Python

import telnyx
import os

telnyx.api_key = os.environ["TELNYX_API_KEY"]

campaign = telnyx.Campaign.create(
    brand_id="BRAND_ID",
    usecase="CUSTOMER_CARE",
    description="Platform notifications sent on behalf of Customer Corp customers",
    sample1="Hi {name}, your appointment is confirmed for {date} at {time}. Reply STOP to opt out.",
    sample2="Your order #{order_id} has shipped! Track at {url}. Reply STOP to unsubscribe.",
    message_flow="Users opt in via web form at customercorp.com/sms-signup with clear consent language. STOP/HELP keywords are honored.",
    help_message="Customer Corp support: help@customercorp.com or call 1-800-555-0123. Reply STOP to opt out.",
    subscriber_optin=True,
    subscriber_optout=True,
    subscriber_help=True,
    embedded_link=True,
    embedded_phone=False,
)
print(f"Campaign ID: {campaign.id}")

Node

import Telnyx from "telnyx";

const telnyx = new Telnyx(process.env.TELNYX_API_KEY);

const { data: campaign } = await telnyx.messaging10dlc.campaigns.create({
  brandId: "BRAND_ID",
  usecase: "CUSTOMER_CARE",
  description: "Platform notifications on behalf of Customer Corp customers",
  sample1: "Hi {name}, your appointment is confirmed for {date} at {time}. Reply STOP to opt out.",
  sample2: "Your order #{order_id} has shipped! Track at {url}. Reply STOP to unsubscribe.",
  messageFlow: "Users opt in via web form with clear consent language. STOP/HELP honored.",
  helpMessage: "Customer Corp support: help@customercorp.com. Reply STOP to opt out.",
  subscriberOptin: true,
  subscriberOptout: true,
  subscriberHelp: true,
  embeddedLink: true,
  embeddedPhone: false,
});
console.log(`Campaign ID: ${campaign.id}`);

ISV-specific requirements:

Sample messages must accurately reflect what your platform sends
Message flow must describe how end users (not your clients) consent to receive messages
Each campaign undergoes manual review by TCR — allow 5–10 business days

Once your campaign is approved at your upstream CSP, share it to Telnyx. The sharing process depends on your CSP, but the result is a campaign visible in the Telnyx Partner Campaigns API. After sharing, verify the campaign appears on Telnyx:

curl

# List all shared campaigns
curl -s https://api.telnyx.com/v2/10dlc/partner_campaigns \
  -H "Authorization: Bearer $TELNYX_API_KEY" | python3 -m json.tool

# Get a specific shared campaign
curl -s https://api.telnyx.com/v2/10dlc/partner_campaigns/{campaignId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" | python3 -m json.tool

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

# List all shared campaigns
page = client.messaging_10dlc.partner_campaigns.list()
for campaign in page.records:
    print(f"Campaign: {campaign.tcr_campaign_id} — Status: {campaign.campaign_status}")

# Get a specific campaign
campaign = client.messaging_10dlc.partner_campaigns.retrieve("CAMPAIGN_ID")
print(f"Brand: {campaign.brand_display_name}, Status: {campaign.campaign_status}")

Node

import Telnyx from "telnyx";

const client = new Telnyx(process.env.TELNYX_API_KEY);

// List all shared campaigns
for await (const campaign of client.messaging10dlc.partnerCampaigns.list()) {
  console.log(`Campaign: ${campaign.tcrCampaignId} — Status: ${campaign.campaignStatus}`);
}

// Get a specific campaign
const specific = await client.messaging10dlc.partnerCampaigns.retrieve("CAMPAIGN_ID");
console.log(`Brand: ${specific.brandDisplayName}`);

package main

import (
    "context"
    "fmt"
    "github.com/team-telnyx/telnyx-go"
    "github.com/team-telnyx/telnyx-go/option"
)

func main() {
    client := telnyx.NewClient(option.WithAPIKey("YOUR_API_KEY"))

    page, err := client.Messaging10dlc.PartnerCampaigns.List(
        context.TODO(),
        telnyx.Messaging10dlcPartnerCampaignListParams{},
    )
    if err != nil {
        panic(err)
    }
    for _, campaign := range page.Records {
        fmt.Printf("Campaign: %s — Status: %s\n", campaign.TcrCampaignID, campaign.CampaignStatus)
    }
}

Ruby

require "telnyx"

telnyx = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

# List shared campaigns
page = telnyx.messaging_10dlc.partner_campaigns.list
page.records.each do |campaign|
  puts "Campaign: #{campaign.tcr_campaign_id} — Status: #{campaign.campaign_status}"
end

Java

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

var page = client.messaging10dlc().partnerCampaigns().list();
page.records().forEach(campaign -> {
    System.out.printf("Campaign: %s — Status: %s%n",
        campaign.tcrCampaignId(), campaign.campaignStatus());
});

PHP

$telnyx = new \Telnyx\TelnyxClient(getenv('TELNYX_API_KEY'));

$page = $telnyx->messaging10dlc->partnerCampaigns->list();
foreach ($page->records as $campaign) {
    echo "Campaign: {$campaign->tcrCampaignId} — Status: {$campaign->campaignStatus}\n";
}

Step 5: Assign phone numbers to the shared campaign

Once the campaign is accepted by Telnyx, assign your 10DLC numbers to it:

curl

curl -X POST https://api.telnyx.com/v2/10dlc/phone_number_campaigns \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+12025551234",
    "campaignId": "CAMPAIGN_ID"
  }'

Python

import telnyx
import os

telnyx.api_key = os.environ["TELNYX_API_KEY"]

assignment = telnyx.PhoneNumberCampaign.create(
    phone_number="+12025551234",
    campaign_id="CAMPAIGN_ID",
)
print(f"Assignment status: {assignment.status}")

Node

import Telnyx from "telnyx";

const telnyx = new Telnyx(process.env.TELNYX_API_KEY);

const { data } = await telnyx.messaging10dlc.phoneNumberCampaigns.create({
  phoneNumber: "+12025551234",
  campaignId: "CAMPAIGN_ID",
});
console.log(`Assignment status: ${data.status}`);

Number-to-campaign assignment typically completes within minutes. A number can only be assigned to one campaign at a time. To reassign, remove the existing assignment first. Monitor whether Telnyx has accepted the shared campaign:

curl

curl -s https://api.telnyx.com/v2/10dlc/partnerCampaign/{campaignId}/sharing \
  -H "Authorization: Bearer $TELNYX_API_KEY" | python3 -m json.tool

Possible sharing statuses:

Status	Meaning
`PENDING`	Campaign shared, awaiting Telnyx acceptance
`ACCEPTED`	Telnyx accepted — you can assign numbers and send traffic
`DECLINED`	Telnyx declined the sharing request

Step 7: Send messages

Once numbers are assigned to the accepted campaign, send messages using the standard Send Message API:

curl

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+12025551234",
    "to": "+13035551234",
    "text": "Hi Jane, your appointment is confirmed for March 15 at 2:00 PM. Reply STOP to opt out.",
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
  }'

Managing customers at scale

Multi-tenant architecture patterns

Best for: Agencies, resellers managing distinct businesses. Each customer gets their own brand and campaign. This provides:

Isolated throughput per customer
Independent compliance status
Clear separation for TCR

Trade-off: More registration overhead, but better isolation.

Your Platform Account
├── Customer A → Brand A → Campaign A → Numbers [+1xxx, +1yyy]
├── Customer B → Brand B → Campaign B → Numbers [+1zzz]
└── Customer C → Brand C → Campaign C → Numbers [+1www, +1vvv]

Best for: SaaS platforms where all customers send similar message types. One brand (yours) with shared campaigns. All customers’ traffic flows through the same campaign. Trade-off: Simpler setup, but throughput is shared and one customer’s violations affect all.

Your Platform Account
└── Your Brand → Shared Campaign → Numbers [+1xxx, +1yyy, +1zzz]
    ├── Customer A traffic
    ├── Customer B traffic
    └── Customer C traffic

Best for: Platforms with a mix of high-volume and low-volume customers.

High-volume customers get dedicated brands + campaigns
Low-volume customers share a platform campaign
Migrate customers to dedicated as they grow

Your Platform Account
├── Platform Brand → Shared Campaign → [low-volume customers]
├── Big Customer A → Brand A → Campaign A → [dedicated numbers]
└── Big Customer B → Brand B → Campaign B → [dedicated numbers]

Bulk brand registration

For platforms onboarding many customers, automate brand registration:

Python

import telnyx
import os
import time

telnyx.api_key = os.environ["TELNYX_API_KEY"]

customers = [
    {
        "company_name": "Acme Corp LLC",
        "ein": "12-3456789",
        "email": "admin@acme.com",
        "website": "https://acme.com",
        "phone": "+12025550001",
    },
    {
        "company_name": "Widget Inc",
        "ein": "98-7654321",
        "email": "admin@widget.com",
        "website": "https://widget.com",
        "phone": "+12025550002",
    },
]

results = []
for customer in customers:
    try:
        brand = telnyx.Brand.create(
            entity_type="PRIVATE_PROFIT",
            company_name=customer["company_name"],
            ein=customer["ein"],
            ein_issuing_country="US",
            phone=customer["phone"],
            street="123 Main St",
            city="New York",
            state="NY",
            postal_code="10001",
            country="US",
            email=customer["email"],
            website=customer["website"],
            vertical="TECHNOLOGY",
            display_name=customer["company_name"].split()[0],
        )
        results.append({"customer": customer["company_name"], "brand_id": brand.id, "status": "created"})
        print(f"✓ {customer['company_name']}: Brand {brand.id}")
        time.sleep(0.5)  # Rate limit courtesy
    except Exception as e:
        results.append({"customer": customer["company_name"], "error": str(e)})
        print(f"✗ {customer['company_name']}: {e}")

print(f"\nRegistered {sum(1 for r in results if 'brand_id' in r)}/{len(customers)} brands")

Webhook monitoring for partner campaigns

Set up webhooks to track campaign status changes across all your customers:

Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/10dlc", methods=["POST"])
def handle_10dlc_webhook(self):
    event = request.json
    event_type = event.get("data", {}).get("event_type", "")

    if event_type == "campaign.status_update":
        campaign_id = event["data"]["payload"]["campaignId"]
        new_status = event["data"]["payload"]["campaignStatus"]
        print(f"Campaign {campaign_id} → {new_status}")

        if new_status == "ACTIVE":
            # Campaign approved — notify customer, assign numbers
            activate_customer_messaging(campaign_id)
        elif new_status == "REJECTED":
            # Campaign rejected — notify customer with reason
            reason = event["data"]["payload"].get("rejectionReason", "Unknown")
            notify_customer_rejection(campaign_id, reason)

    elif event_type == "brand.status_update":
        brand_id = event["data"]["payload"]["brandId"]
        identity_status = event["data"]["payload"]["identityStatus"]
        print(f"Brand {brand_id} → {identity_status}")

    return jsonify({"status": "ok"}), 200

Partner campaign appeals

When a shared campaign is rejected, the appeal process differs from native campaigns. Partner campaigns use a CSP nudge mechanism: Check the campaign status and rejection details via your upstream CSP. Update the campaign details (description, samples, message flow) at your upstream CSP based on the rejection reason. Your upstream CSP sends a CAMPAIGN_NUDGE event to TCR, which triggers a re-review. The nudge mechanism is only available for partner campaigns. Native campaigns use the direct appeal API. See 10DLC Event Notifications for details. Set up webhooks to receive campaign status updates automatically.

Troubleshooting

Cause: Telnyx hasn’t processed the sharing request yet, or there’s a data mismatch. Fix:

Verify the campaign is fully approved at your upstream CSP
Confirm you shared to the correct downstream CSP (Telnyx’s TCR ID)
Contact Telnyx support with the TCR Campaign ID

Cause: Campaign sharing hasn’t been accepted, or numbers aren’t 10DLC-eligible. Fix:

Check sharing status — must be ACCEPTED
Verify numbers are long codes (not toll-free or short codes)
Ensure numbers aren’t already assigned to another campaign
Check that numbers are on the same Telnyx account

Cause: Message content doesn’t match registered campaign samples, or throughput exceeds campaign limits. Fix:

Compare actual message content against registered samples
Check 10DLC rate limits for your vetting score
Ensure opt-out keywords (STOP, etc.) are properly handled
Review the error code reference for specific guidance

Cause: Business information doesn’t match public records. Fix: See the 10DLC Troubleshooting Guide for detailed brand failure resolution steps. Steps:

Register a new brand for the customer (if not already done)
Submit brand for vetting
Create a new campaign under their brand
Wait for campaign approval
Reassign their phone numbers from the shared campaign to the new dedicated campaign
Traffic switches immediately — no downtime required

Compliance checklist for ISVs

ISVs have additional compliance responsibilities because you’re sending on behalf of customers. TCR and carriers hold you accountable for your customers’ messaging practices.

Customer vetting — Verify your customers’ business legitimacy before registration
Content monitoring — Monitor message content for compliance with campaign use case
Opt-in verification — Ensure customers collect proper consent from end users
Opt-out processing — STOP/HELP keywords must work across all customer traffic
Volume management — Don’t exceed throughput limits for your campaign’s vetting score
Incident response — Have a process to quickly disable a customer’s messaging if they violate policies
Record retention — Keep opt-in records for at least 4 years per CTIA guidelines
Sample message accuracy — Registered samples must match actual production messages

Next steps

Understand throughput by vetting score and carrier. Set up webhooks for brand and campaign status changes. Details on campaign use cases and requirements. Full API reference for shared campaign management.

Rate Limits & Scores

Source: https://developers.telnyx.com/docs/messaging/10dlc/10dlc-rate-limits.md

Your 10DLC throughput is determined by your brand vetting score and campaign type. Each carrier (AT&T, T-Mobile, Verizon) applies different rate limits. Understanding these limits helps you plan capacity and optimize for higher throughput.

AT&T throughput

AT&T assigns throughput per campaign based on a Message Class, determined by your use case type and vetting score.

Message Class	Use Case	Vetting Score	SMS TPM	MMS TPM
A	Standard (Dedicated)	75-100	4,500	2,400
B	Standard (Mixed/Marketing)	75-100	4,500	2,400
C	Standard (Dedicated)	50-74	2,400	1,200
D	Standard (Mixed/Marketing)	50-74	2,400	1,200
E	Standard (Dedicated)	1-49	240	150
F	Standard (Mixed/Marketing)	1-49	240	150
T	Low Volume Mixed	Any	75	50
W	Sole Proprietor	N/A	15	50

Special use cases (fixed throughput regardless of vetting score):

Message Class	Use Case	SMS TPM	MMS TPM
K	Political	4,500	2,400
P	Charity / Nonprofit	2,400	1,200
S	Social	9,000	2,400
X	Emergency / Public Safety	4,500	2,400
G	Proxy (per number)	60	50
N	Agents & Franchises (per number)	60	50

TPM = Throughput Per Minute. AT&T measures throughput in messages per minute, not per second. To convert: 4,500 TPM ≈ 75 MPS.

T-Mobile throughput

T-Mobile uses daily message caps at the brand level, shared across all campaigns under that brand.

Brand Tier	Vetting Score	Daily SMS Cap
Top	75-100	200,000
High	50-74	40,000
Medium	25-49	10,000
Basic	1-24	2,000
Sole Proprietor	N/A	1,000

T-Mobile caps are per brand, not per campaign. If you have 3 campaigns under one brand, they share the same daily cap. Plan accordingly for high-volume use cases. Unvetted brands default to the Basic tier (2,000/day) unless the business is listed on the Russell 3000 index.

Verizon throughput

Verizon has not published specific throughput numbers for 10DLC. They use content-based filtering rather than explicit rate limits. Messages that comply with your registered campaign use case are generally delivered without throttling.

Vetting score impact

Your brand’s vetting score (0-100) is the single most important factor in determining throughput:

Score Range	AT&T SMS TPM	T-Mobile Daily Cap	Recommendation
75-100	4,500	200,000	✅ Ideal for production
50-74	2,400	40,000	⚠️ Adequate for moderate volume
25-49	240	10,000	⚠️ Limited — consider enhanced vetting
1-24	240	2,000	❌ Very limited — improve score
Unvetted	240	2,000	❌ Get vetted immediately

Check your brand and campaign scores

curl

# Get brand details including vetting score
curl -s https://api.telnyx.com/v2/10dlc/brand/{brandId} \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '{
    brandId: .data.brandId,
    displayName: .data.displayName,
    identityStatus: .data.identityStatus,
    vettingScore: .data.vettingScore
  }'

# List campaigns with throughput info
curl -s https://api.telnyx.com/v2/10dlc/campaign \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data[] | {
    campaignId: .campaignId,
    usecase: .usecase,
    attMsgClass: .attMsgClass,
    attTpm: .attTpm,
    tMobileBrandTier: .tMobileBrandTier
  }'

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {"Authorization": f"Bearer {API_KEY}"}

# Check brand vetting score
brand_id = "your_brand_id"
response = requests.get(
    f"https://api.telnyx.com/v2/10dlc/brand/{brand_id}",
    headers=headers,
)
brand = response.json()["data"]
print(f"Brand: {brand['displayName']}")
print(f"Vetting Score: {brand.get('vettingScore', 'Not vetted')}")
print(f"Identity Status: {brand['identityStatus']}")

# Check campaign throughput
response = requests.get(
    "https://api.telnyx.com/v2/10dlc/campaign",
    headers=headers,
)
for campaign in response.json()["data"]:
    print(f"\nCampaign: {campaign['campaignId']}")
    print(f"  Use Case: {campaign['usecase']}")
    print(f"  AT&T Class: {campaign.get('attMsgClass', 'N/A')}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
};

// Check brand vetting score
const brandId = 'your_brand_id';
const brand = await axios.get(
  `https://api.telnyx.com/v2/10dlc/brand/${brandId}`,
  { headers }
);
console.log(`Brand: ${brand.data.data.displayName}`);
console.log(`Vetting Score: ${brand.data.data.vettingScore ?? 'Not vetted'}`);

// Check campaigns
const campaigns = await axios.get(
  'https://api.telnyx.com/v2/10dlc/campaign',
  { headers }
);
campaigns.data.data.forEach(c => {
  console.log(`\nCampaign: ${c.campaignId} (${c.usecase})`);
  console.log(`  AT&T Class: ${c.attMsgClass ?? 'N/A'}`);
});

Maximize your throughput

The most impactful action. Ensure before vetting:

Website is live and matches your brand information
EIN matches your legal business name exactly (IRS records)
Phone number is findable via Google for your business
Email domain matches your website domain
Business address is verifiable Some use cases have higher default throughput:
Social campaigns get 9,000 TPM on AT&T
Political and Emergency get 4,500 TPM
Mixed campaigns work for most businesses

Don’t misrepresent your use case — carriers audit campaigns. If your initial score is below 75, consider requesting enhanced vetting for a more thorough review. Contact Telnyx support for guidance. Assign multiple phone numbers to your campaign. While per-campaign limits still apply, distributing across numbers helps with carrier-level delivery patterns. Track delivery rates via Message Detail Records. High error rates may indicate you’re hitting limits. Adjust sending patterns accordingly.

Compliance checklist

Carriers can reduce your throughput or reject campaigns that don’t follow these guidelines:

Requirement	Details
✅ Website domain = email domain	`admin@acme.com` + `acme.com`
✅ Company name matches website	Consistent branding across registration
✅ Clear opt-in on website	SMS consent checkbox visible near submit button
✅ Detailed campaign description	Specific, not vague or generic
✅ Sample messages match use case	Realistic and representative
✅ No disallowed content	No SHAFT, cannabis, payday lending, sweepstakes
✅ Opt-out language in messages	Include “Reply STOP to unsubscribe”

Disallowed use cases

The following use cases will be rejected or result in very low throughput:

Unsolicited messaging (cold outreach, lead generation spam)
Non-direct lending (3rd party auto loans, payday loans)
Indirect debt collection
Cannabis or CBD marketing
Gambling (unless licensed)
SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco)
Sweepstakes and “free giveaway” campaigns

Register your brand and campaign for 10DLC messaging. Receive webhooks for brand vetting and campaign status changes. General messaging rate limits for all sender types. Track delivery rates and identify throughput issues.

Phone Number Assignment

Source: https://developers.telnyx.com/docs/messaging/10dlc/phone-number-assignment.md

After your brand is registered and campaign is approved, you need to assign phone numbers to the campaign before sending messages. Only numbers assigned to an active campaign can send 10DLC A2P messages.

How it works

Requirement	Details
Number type	US long code (10-digit) numbers only
Messaging profile	Number must be assigned to a messaging profile first
Campaign status	Campaign must be `ACTIVE` (approved by carriers)
One campaign per number	Each number can only be assigned to one campaign at a time

Numbers not assigned to an active 10DLC campaign will have messages filtered or blocked by carriers on AT&T, T-Mobile, and other major US networks.

Assign a number to a campaign

curl

curl -X POST https://api.telnyx.com/v2/10dlc/phoneNumberCampaign \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+15551234567",
    "campaignId": "CAMPAIGN_ID"
  }'

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign",
    headers=headers,
    json={
        "phoneNumber": "+15551234567",
        "campaignId": "CAMPAIGN_ID",
    },
)
result = response.json()
print(f"Number: {result['data']['phoneNumber']}")
print(f"Status: {result['data']['status']}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
  'Content-Type': 'application/json',
};

const response = await axios.post(
  'https://api.telnyx.com/v2/10dlc/phoneNumberCampaign',
  {
    phoneNumber: '+15551234567',
    campaignId: 'CAMPAIGN_ID',
  },
  { headers }
);

console.log(`Number: ${response.data.data.phoneNumber}`);
console.log(`Status: ${response.data.data.status}`);

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.telnyx.com/v2/10dlc/phoneNumberCampaign")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = {
  phoneNumber: "+15551234567",
  campaignId: "CAMPAIGN_ID"
}.to_json

response = http.request(request)
result = JSON.parse(response.body)
puts "Number: #{result['data']['phoneNumber']}"
puts "Status: #{result['data']['status']}"

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func main() {
  data := map[string]string{
    "phoneNumber": "+15551234567",
    "campaignId":  "CAMPAIGN_ID",
  }

  body, _ := json.Marshal(data)
  req, _ := http.NewRequest("POST", "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  d := result["data"].(map[string]interface{})
  fmt.Printf("Number: %s\nStatus: %s\n", d["phoneNumber"], d["status"])
}

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');

$data = [
    'phoneNumber' => '+15551234567',
    'campaignId' => 'CAMPAIGN_ID',
];

$ch = curl_init('https://api.telnyx.com/v2/10dlc/phoneNumberCampaign');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($data),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Number: {$response['data']['phoneNumber']}\n";
echo "Status: {$response['data']['status']}\n";

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var apiKey = Environment.GetEnvironmentVariable("TELNYX_API_KEY");
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

var data = new { phoneNumber = "+15551234567", campaignId = "CAMPAIGN_ID" };
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign", content);
var result = await response.Content.ReadAsStringAsync();

using var doc = JsonDocument.Parse(result);
var d = doc.RootElement.GetProperty("data");
Console.WriteLine($"Number: {d.GetProperty("phoneNumber")}");
Console.WriteLine($"Status: {d.GetProperty("status")}");

Navigate to Campaigns and select the campaign you want to assign numbers to. Click the Assign Numbers panel within your campaign details. Choose the messaging profile that contains the numbers you want to assign. Enter or select the phone numbers to assign to this campaign and click Assign.

Bulk assignment

When assigning multiple numbers to the same campaign, loop through your numbers programmatically:

Python

import os
import requests
import time

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

campaign_id = "CAMPAIGN_ID"
phone_numbers = [
    "+15551234567",
    "+15551234568",
    "+15551234569",
    "+15551234570",
    "+15551234571",
]

results = {"success": [], "failed": []}

for number in phone_numbers:
    try:
        response = requests.post(
            "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign",
            headers=headers,
            json={"phoneNumber": number, "campaignId": campaign_id},
        )
        if response.status_code in (200, 201):
            results["success"].append(number)
            print(f"✓ {number} assigned")
        else:
            error = response.json().get("errors", [{}])[0].get("detail", "Unknown")
            results["failed"].append({"number": number, "error": error})
            print(f"✗ {number}: {error}")
    except Exception as e:
        results["failed"].append({"number": number, "error": str(e)})
    time.sleep(0.5)  # Rate limit safety

print(f"\nAssigned: {len(results['success'])}, Failed: {len(results['failed'])}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
  'Content-Type': 'application/json',
};

const campaignId = 'CAMPAIGN_ID';
const phoneNumbers = [
  '+15551234567',
  '+15551234568',
  '+15551234569',
  '+15551234570',
  '+15551234571',
];

const results = { success: [], failed: [] };

for (const number of phoneNumbers) {
  try {
    await axios.post(
      'https://api.telnyx.com/v2/10dlc/phoneNumberCampaign',
      { phoneNumber: number, campaignId },
      { headers }
    );
    results.success.push(number);
    console.log(`✓ ${number} assigned`);
  } catch (err) {
    const detail = err.response?.data?.errors?.[0]?.detail || err.message;
    results.failed.push({ number, error: detail });
    console.log(`✗ ${number}: ${detail}`);
  }
  await new Promise((r) => setTimeout(r, 500)); // Rate limit safety
}

console.log(`\nAssigned: ${results.success.length}, Failed: ${results.failed.length}`);

curl

#!/bin/bash
# Bulk assign numbers to a campaign
CAMPAIGN_ID="CAMPAIGN_ID"
NUMBERS=("+15551234567" "+15551234568" "+15551234569")

for NUM in "${NUMBERS[@]}"; do
  RESULT=$(curl -s -w "\n%{http_code}" -X POST \
    https://api.telnyx.com/v2/10dlc/phoneNumberCampaign \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TELNYX_API_KEY" \
    -d "{\"phoneNumber\": \"$NUM\", \"campaignId\": \"$CAMPAIGN_ID\"}")

  HTTP_CODE=$(echo "$RESULT" | tail -1)
  if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ]; then
    echo "✓ $NUM assigned"
  else
    echo "✗ $NUM failed (HTTP $HTTP_CODE)"
  fi
  sleep 0.5
done

Number pool integration

If you’re using Number Pools, numbers in the pool must also be assigned to a 10DLC campaign. The number pool distributes sending across multiple numbers, but each number still needs campaign registration. Register your campaign via the Campaign Registration guide. Configure your messaging profile with number pool enabled. Every number in the pool must be assigned to the same campaign. Use the bulk assignment method above. List all numbers assigned to your campaign to confirm all pool numbers are included. If a number in your pool is not assigned to a campaign, messages sent from that number will be filtered by carriers. This creates inconsistent delivery — some messages succeed, others fail depending on which pool number is selected.

List assigned numbers

curl

# List all numbers assigned to a campaign
curl -s "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign?filter[campaignId]=CAMPAIGN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data[] | {phoneNumber, status}'

Python

response = requests.get(
    "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign",
    headers=headers,
    params={"filter[campaignId]": campaign_id},
)
numbers = response.json()["data"]
for n in numbers:
    print(f"{n['phoneNumber']} | {n['status']}")

Node

const response = await axios.get(
  'https://api.telnyx.com/v2/10dlc/phoneNumberCampaign',
  {
    headers,
    params: { 'filter[campaignId]': campaignId },
  }
);

response.data.data.forEach((n) => {
  console.log(`${n.phoneNumber} | ${n.status}`);
});

Remove a number from a campaign

curl

curl -X DELETE "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign/+15551234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.delete(
    "https://api.telnyx.com/v2/10dlc/phoneNumberCampaign/+15551234567",
    headers=headers,
)
print(f"Status: {response.status_code}")  # 200 = success

Node

await axios.delete(
  'https://api.telnyx.com/v2/10dlc/phoneNumberCampaign/+15551234567',
  { headers }
);
console.log('Number removed from campaign');

Removing a number from a campaign means it can no longer send 10DLC messages. You can reassign it to a different campaign afterward.

Troubleshooting

Cause: The phone number isn’t on your Telnyx account or isn’t in E.164 format. Fix:

Verify the number is in your account: GET /v2/phone_numbers?filter[phone_number]=+15551234567
Ensure E.164 format: +1 followed by 10 digits (e.g., +15551234567)

Cause: Numbers must be assigned to a messaging profile before campaign assignment. Fix:

# Assign number to a messaging profile first
curl -X PATCH https://api.telnyx.com/v2/phone_numbers/+15551234567 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messaging_profile_id": "PROFILE_ID"}'

Cause: The campaign hasn’t been approved by carriers yet. Fix:

Check campaign status: GET /v2/10dlc/campaignBuilder/{campaignId}
Wait for carrier approval (1-5 business days)
Set up Event Notifications to get notified when the campaign is approved

Cause: Each number can only be assigned to one campaign at a time. Fix:

Remove the number from the current campaign: DELETE /v2/10dlc/phoneNumberCampaign/+15551234567
Assign it to the new campaign

Cause: Carrier provisioning takes time after assignment. Fix:

Wait 24-72 hours for all carriers to propagate
Check MNO metadata on the campaign for per-carrier status
Verify the number is sending the same type of content registered in the campaign
Check Message Detail Records for specific error codes

Cause: Some numbers may have issues while others succeed. Fix:

Check each error response for the specific reason
Common issues: number on different account, already assigned, not on messaging profile
Use the bulk assignment script above with error tracking to identify which numbers failed and why

Next steps

Register your campaign use case before assigning numbers. Distribute sending across multiple numbers automatically. Understand throughput per carrier and brand score. Start sending once numbers are assigned and provisioned.

Event Notifications

Source: https://developers.telnyx.com/docs/messaging/10dlc/event-notifications.md

You can choose to be notified about events on your 10DLC Brands, Campaigns and Phone Numbers by configuring webhooks. For this mechanism to work, you’ll need a publicly accessible HTTP server that can receive our webhook requests at one or more specified URLs. We highly recommend using HTTPS (instead of HTTP). This tutorial walks through setting up a basic application for receiving webhooks.

Configuring webhooks

To receive notifications for brands you need to either provide the webhooks at the creation of the brand or you may update an existing brand. In both cases you have to pass your webhooks in the webhookURL and webhookFailoverURL. webhookFailoverURL is optional. Here is an example of updating the webhooks of a brand: Don’t forget to update YOUR_API_KEY here.

curl -X PUT https://api.telnyx.com/10dlc/brand/:brandid \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer ' \
  -d '{"webhookURL":"https://mywebhooks.com/c5e5e598-95b3-4076-bfe2-c7d2c58ec57f", "webhookFailoverURL":"https://mywebhooks.com/ae20ec14-1c23-4275-add5-3290706b450f"}'

The same applies for campaign event notifications. Webhooks can be provided either upon campaign creation or through an update. Webhooks configured for a campaign are also leveraged for event notifications with phone numbers associated with that campaign. Phone number notifications are triggered for shared campaigns as well.

Types of events

Overall structure of events

Here is an example of a webhook event:

{
  "data": {
    "event_type": "10dlc.brand.update",
    "id": "02d4f0e2-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "97091164-e814-435c-9c1b-14ab2d18e987",
      "brandName": "Some Brand LLC",
      "description": "Brand BBRAND1 is added",
      "eventType": "BRAND_ADD",
      "status": "success",
      "tcrBrandId": "BBRAND1",
      "type": "TCR_BRAND_UPDATE"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Let’s have a closer look at the data key:

Field	Description
event_type	We currently support 3 types of events: 10dlc.brand.update, 10dlc.campaign.update and 10dlc.phone_number.update for updates related to brands, campaigns and phone numbers respectively.
id	Unique ID of this event.
occurred_at	Timestamp of the event.
payload	The content of the payload varies according to the type of event. Below we listed the different payload types grouped by entity.
record_type	Always `event` for webhook events.

The meta object contains delivery metadata:

Field	Description
attempt	The delivery attempt number, starting at 1. Useful for identifying retries.
delivered_to	The webhook URL where this event was sent.

Brand events

Payload type	Description
REGISTRATION	Failures during the registration process. The payload will contain a field called reasons with more details about the errors encountered.
REVET	Success of the revetting request operation. See the revet brand endpoint for more details.
ORDER_EXTERNAL_VETTING	Notification on the process of ordering an external vetting. The status field indicates if the order succeeded or failed.
TCR_BRAND_UPDATE	Notifications received from TCR. The table below has a list of all TCR events that are included here.

Here is a list of all TCR events under the TCR_BRAND_UPDATE type:

TCR Event	Description
BRAND_ADD	Brand successfully added on TCR.
BRAND_APPEAL_ADD	A Brand appeal was added.
BRAND_APPEAL_COMPLETE	The result of a brand appeal.
BRAND_REVET	Result of a brand revet request.

Here is an example of a REGISTRATION notification:

{
  "data": {
    "event_type": "10dlc.brand.update",
    "id": "456abc67-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "b0e2ec67-b26f-4c77-affc-d10f4d1780d3",
      "status": "failed",
      "type": "REGISTRATION",
      "reasons": [
        {
          "fields": [
            "ein"
          ],
          "description": "Invalid EIN - EIN is a nine-digit number. The format is XX-XXXXXXX. The \"-\" symbol is also accepted."
        }
      ]
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a TCR_BRAND_UPDATE notification:

{
  "data": {
    "event_type": "10dlc.brand.update",
    "id": "02d4f0e2-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "97091164-e814-435c-9c1b-14ab2d18e987",
      "brandName": "Some Brand LLC",
      "description": "Brand BBRAND1 is added",
      "eventType": "BRAND_ADD",
      "status": "success",
      "tcrBrandId": "BBRAND1",
      "type": "TCR_BRAND_UPDATE"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of an ORDER_EXTERNAL_VETTING notification:

{
  "data": {
    "event_type": "10dlc.brand.update",
    "id": "a1b2c345-6789-4def-a123-456789abcdef",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "97091164-e814-435c-9c1b-14ab2d18e987",
      "status": "success",
      "type": "ORDER_EXTERNAL_VETTING",
      "reasons": []
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a REVET notification:

{
  "data": {
    "event_type": "10dlc.brand.update",
    "id": "def45678-90ab-cdef-1234-567890abcdef",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "97091164-e814-435c-9c1b-14ab2d18e987",
      "status": "success",
      "type": "REVET",
      "reasons": []
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Campaign events

Payload type	Description
REGISTRATION	Notifications about failures during the registration process. The errors will be listed in the reasons field of the payload.
TELNYX_REVIEW	Telnyx internal compliance review notification. Sent when Telnyx approves or rejects a campaign. The status field contains `ACCEPTED` or `REJECTED`. The description field contains the TCR campaign ID (e.g., C6X6M95).
NUMBER_POOL_PROVISIONED	Success on provisioning a number pool.
NUMBER_POOL_DEPROVISIONED	Success on deprovisioning a number pool.
TCR_EVENT	Notification received from TCR. See table below for specific event types.
MNO_REVIEW	MNO/DCA review results. The status field contains `ACCEPTED` or `REJECTED`. In case of rejection, the description field provides a reason.
TELNYX_EVENT	Telnyx system events such as campaign suspension. The status field contains `DORMANT` for suspended campaigns.
VERIFIED	Campaign has been successfully provisioned with MNOs. Sent when campaign reaches `MNO_PROVISIONED` status.

Here is a list of TCR events under the TCR_EVENT type:

TCR Event	Description
CAMPAIGN_ADD	Campaign successfully added to TCR.
CAMPAIGN_BILLED	Campaign billing event from TCR.
CAMPAIGN_DCA_COMPLETE	DCA processing complete for campaign.
CAMPAIGN_EXPIRED	Campaign has expired.
CAMPAIGN_NUDGE	Nudge event sent by partner CSP to trigger campaign re-review after appeal or rejection.
CAMPAIGN_RESUBMISSION	Campaign has been resubmitted.
CAMPAIGN_UPDATE	Campaign has been updated.
MNO_CAMPAIGN_OPERATION_APPROVED	MNO has approved the campaign.
MNO_CAMPAIGN_OPERATION_REJECTED	MNO has rejected the campaign.
MNO_CAMPAIGN_OPERATION_REVIEW	Campaign is under MNO review.
MNO_CAMPAIGN_OPERATION_SUSPENDED	MNO has suspended the campaign.
MNO_CAMPAIGN_OPERATION_UNSUSPENDED	MNO has unsuspended the campaign.

Here is an example of a campaign REGISTRATION failure notification:

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "c3d4e567-8901-4bcd-ef23-456789012345",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "status": "failed",
      "type": "REGISTRATION",
      "reasons": [
        {
          "fields": ["sample1"],
          "description": "Sample message does not contain required opt-out language"
        }
      ]
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a NUMBER_POOL_PROVISIONED notification:

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "d4e5f678-9012-4cde-f345-678901234567",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "97091164-e814-435c-9c1b-14ab2d18e987",
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "type": "NUMBER_POOL_PROVISIONED"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a NUMBER_POOL_DEPROVISIONED notification:

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "e5f6a789-0123-4def-a456-789012345678",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "97091164-e814-435c-9c1b-14ab2d18e987",
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "type": "NUMBER_POOL_DEPROVISIONED"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a VERIFIED notification:

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "456abc67-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "97091164-e814-435c-9c1b-14ab2d18e987",
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "createdDate": "2024-07-06T14:22:37.328+00:00",
      "cspId": "CSPID1",
      "type": "VERIFIED",
      "isTMobileRegistered": true
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a TELNYX_REVIEW notification (approval):

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "789def12-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "description": "C6X6M95 approved by Telnyx",
      "status": "ACCEPTED",
      "type": "TELNYX_REVIEW"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a TELNYX_EVENT notification (campaign suspension):

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "a1b2c345-6789-4def-a123-456789abcdef",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "description": "Campaign has been marked as dormant",
      "status": "DORMANT",
      "type": "TELNYX_EVENT"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of an MNO_REVIEW notification (rejection):

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "def45678-90ab-cdef-1234-567890abcdef",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "description": "Campaign rejected by T-Mobile due to insufficient opt-out instructions",
      "status": "REJECTED",
      "type": "MNO_REVIEW"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a TCR_EVENT notification:

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "fed98765-4321-dcba-9876-543210fedcba",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "type": "TCR_EVENT",
      "eventType": "CAMPAIGN_ADD",
      "description": "Campaign C6X6M95 successfully added to TCR"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Note: The campaignId field in webhooks contains the Telnyx UUID, not the TCR campaign ID. The TCR campaign ID (e.g., C6X6M95) may appear in the description field.

Phone number events

Payload type	Description
ASSIGNMENT	Notifications about the phone number assignment process. In case of failure, an error message is displayed in the reasons field. That field is empty in case of a successful assignment.
DELETION	Notifications about the phone number removal process. In case of failure, an error message is displayed in the reasons field. That field is empty in case of a successful removal.
STATUS_UPDATE	The status of the phone number was updated. The new status is shown in the status field.

Phone numbers in webhook payloads use E.164 format (e.g., +16715455939), which includes the country code prefix. Here is an example of a successful ASSIGNMENT notification:

{
  "data": {
    "event_type": "10dlc.phone_number.update",
    "id": "123abc67-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "phoneNumber": "+16715455939",
      "status": "success",
      "type": "ASSIGNMENT",
      "reasons": []
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Here is an example of a STATUS_UPDATE notification:

{
  "data": {
    "event_type": "10dlc.phone_number.update",
    "id": "789def12-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "tcrCampaignId": "C6X6M95",
      "phoneNumber": "+16715455939",
      "status": "ADDED",
      "type": "STATUS_UPDATE"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

The status field in STATUS_UPDATE notifications can be: ADDED, DELETED, PENDING, or FAILED. Here is an example of a DELETION notification:

{
  "data": {
    "event_type": "10dlc.phone_number.update",
    "id": "b2c3d456-7890-4abc-def1-234567890abc",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "phoneNumber": "+16715455939",
      "status": "success",
      "type": "DELETION",
      "reasons": []
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Campaign Appeals and Nudging Mechanisms

When campaigns are rejected, there are different flows for getting them back into the compliance review queue depending on the campaign type and rejection reason.

Native Campaign Appeals

For native campaigns rejected due to external factors (e.g., website compliance issues), customers can use the campaign appeal endpoint after addressing the issues: API Endpoint:

curl -X POST 'https://api.telnyx.com/10dlc/campaign/{campaignId}/appeal' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "appealReason": "The website has been updated to include the required privacy policy and terms of service."
  }'

This will update the campaign status from TELNYX_FAILED to TCR_ACCEPTED and re-enter the compliance review queue.

Partner Campaign Nudging

For partner campaigns, the appeal process involves the CSP (Campaign Service Provider) sending a CAMPAIGN_NUDGE event after reviewing and approving customer changes: CAMPAIGN_NUDGE Webhook Payload Example:

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "example-event-id",
    "occurred_at": "2025-07-30T11:07:51.259711+00:00",
    "payload": {
      "campaignId": "C4D06C2F",
      "type": "CAMPAIGN_NUDGE",
      "nudgeIntent": "APPEAL_REJECTION",
      "description": "The campaign has been reviewed and approved after appeal.",
      "cspId": "TNX"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://your-webhook-url.com"
  }
}

Note: CAMPAIGN_NUDGE events originate from TCR and use the TCR campaign ID format (e.g., C4D06C2F) in the campaignId field, unlike other campaign webhooks which use the Telnyx UUID.

Campaign Appeal Scenarios

There are several specific scenarios where campaign appeals may be needed:

1. Native Campaign Rejected for Content Issues

When a customer submits a native campaign and Telnyx rejects it due to issues with the campaign content (e.g., unclear sample messages), the customer can make adjustments to their campaign. Using the campaign update endpoint will automatically reset the campaign’s status to TCR_ACCEPTED so it goes back into the compliance team’s review queue.

2. Native Campaign Rejected for External Factors

When a customer submits a native campaign and Telnyx rejects it due to factors outside the campaign object (e.g., website compliance requirements), the customer must:

Fix the external issues (e.g., update website with required privacy policy).
Use the appeal API endpoint to get their campaign back in the review queue.

Example failure reason:

{
  "reason": "Website does not meet compliance requirements."
}

After fixes are made, the appeal request:

curl -X POST 'https://api.telnyx.com/10dlc/campaign/{campaignId}/appeal' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "appealReason": "The website has been updated to include the required privacy policy and terms of service."
  }'

3. Partner Campaign Rejected (Any Reason)

For partner campaigns rejected for either content issues or external factors, the process involves the CSP:

Customer makes required adjustments based on rejection reasons.
CSP reviews the changes and approves them.
CSP forwards a CAMPAIGN_NUDGE event to Telnyx.
Campaign status changes from TELNYX_FAILED to TCR_ACCEPTED and re-enters compliance review.

This nudging mechanism for partner campaigns cannot work with native campaigns.

4. DCA Rejection for External Factors

When Telnyx accepts a campaign but the Direct Connect Aggregator (DCA) rejects it due to external factors:

Customer makes required external changes (e.g., website updates).
Customer notifies Telnyx via appropriate appeal mechanism (scenarios 2 or 3).
Once Telnyx approves the changes, Telnyx generates a nudge webhook that the DCA receives.
Campaign re-enters DCA review queue.

5. DCA Rejection for Content Issues

When the DCA rejects a campaign due to campaign content issues:

Customer updates campaign content (e.g., sample messages).
Customer notifies Telnyx via appropriate appeal mechanism (scenarios 1 or 3).
Once Telnyx approves the changes, Telnyx generates a nudge webhook that the DCA receives.
Campaign re-enters DCA review queue.

Campaign status flow

The following diagram shows the campaign lifecycle including both success and failure paths:

Success path statuses

Status	Description
TCR_PENDING	Campaign is pending review at The Campaign Registry (TCR).
TCR_ACCEPTED	Campaign has been accepted by TCR and is ready for Telnyx/MNO review.
MNO_PENDING	Campaign is pending provisioning with Mobile Network Operators (MNOs).
MNO_PROVISIONED	Campaign has been successfully provisioned with all MNOs.

Failure and suspension statuses

Status	Description
TCR_FAILED	Campaign was rejected by TCR during initial registration.
TELNYX_FAILED	Campaign was rejected by Telnyx compliance review. Can be appealed.
MNO_REJECTED	Campaign was rejected by one or more MNOs. Can be appealed.
TCR_SUSPENDED	Campaign has been suspended due to compliance issues.
TCR_EXPIRED	Campaign has expired and is no longer active.

Campaign appeal status flow

The typical status flow for campaign appeals is:

Initial rejection: Campaign status becomes TELNYX_FAILED.
Customer action: Customer addresses the rejection reasons.
Appeal submission:
- Native campaigns: Use appeal API endpoint or campaign update.
- Partner campaigns: CSP sends CAMPAIGN_NUDGE.
Re-review: Campaign status changes to TCR_ACCEPTED and re-enters compliance review.

The nudging mechanism for partner campaigns cannot be used with native campaigns. Native campaigns must use the direct appeal API endpoint or campaign update functionality.

Process webhooks with SDK examples

Handle 10DLC event notifications in your application to track registration status, respond to failures, and automate workflows:

Python

from flask import Flask, request, jsonify
import logging

app = Flask(__name__)
logger = logging.getLogger(__name__)

@app.route("/webhooks/10dlc", methods=["POST"])
def handle_10dlc_webhook():
    """Process 10DLC event notifications."""
    event = request.json
    data = event["data"]
    event_type = data["event_type"]
    payload = data["payload"]
    event_id = data["id"]

    # Deduplicate — store processed event IDs
    if is_duplicate(event_id):
        return jsonify({"status": "already_processed"}), 200

    if event_type == "10dlc.brand.update":
        handle_brand_event(payload)
    elif event_type == "10dlc.campaign.update":
        handle_campaign_event(payload)
    elif event_type == "10dlc.phone_number.update":
        handle_phone_number_event(payload)

    mark_processed(event_id)
    return jsonify({"status": "ok"}), 200

def handle_brand_event(payload):
    brand_id = payload["brandId"]
    event_type = payload["type"]
    status = payload.get("status", "")

    if event_type == "REGISTRATION" and status == "failed":
        reasons = payload.get("reasons", [])
        logger.error(f"Brand {brand_id} registration failed: {reasons}")
        alert_team(f"10DLC brand registration failed: {reasons}")

    elif event_type == "TCR_BRAND_UPDATE":
        tcr_event = payload.get("eventType", "")
        if tcr_event == "BRAND_ADD":
            logger.info(f"Brand {brand_id} added to TCR")
        elif tcr_event == "BRAND_REVET":
            logger.info(f"Brand {brand_id} revet completed: {status}")

    elif event_type == "ORDER_EXTERNAL_VETTING":
        logger.info(f"Brand {brand_id} vetting order: {status}")

def handle_campaign_event(payload):
    campaign_id = payload.get("campaignId", "")
    event_type = payload["type"]
    status = payload.get("status", "")

    if event_type == "REGISTRATION" and status == "failed":
        reasons = payload.get("reasons", [])
        logger.error(f"Campaign {campaign_id} registration failed: {reasons}")

    elif event_type == "TELNYX_REVIEW":
        if status == "ACCEPTED":
            logger.info(f"Campaign {campaign_id} approved by Telnyx")
        elif status == "REJECTED":
            logger.warning(f"Campaign {campaign_id} rejected by Telnyx")

    elif event_type == "MNO_REVIEW":
        logger.info(f"Campaign {campaign_id} MNO review: {status}")

    elif event_type == "VERIFIED":
        logger.info(f"Campaign {campaign_id} fully provisioned!")
        # Campaign is ready — you can start sending messages

def handle_phone_number_event(payload):
    phone = payload.get("phoneNumber", "")
    status = payload.get("status", "")
    logger.info(f"Phone number {phone} 10DLC status: {status}")

Node

import express from 'express';

const app = express();
app.use(express.json());

const processedEvents = new Set();

app.post('/webhooks/10dlc', (req, res) => {
  const { data } = req.body;
  const { event_type, payload, id: eventId } = data;

  // Deduplicate
  if (processedEvents.has(eventId)) {
    return res.json({ status: 'already_processed' });
  }

  switch (event_type) {
    case '10dlc.brand.update':
      handleBrandEvent(payload);
      break;
    case '10dlc.campaign.update':
      handleCampaignEvent(payload);
      break;
    case '10dlc.phone_number.update':
      handlePhoneNumberEvent(payload);
      break;
  }

  processedEvents.add(eventId);
  res.json({ status: 'ok' });
});

function handleBrandEvent(payload) {
  const { brandId, type, status, reasons } = payload;

  if (type === 'REGISTRATION' && status === 'failed') {
    console.error(`Brand ${brandId} registration failed:`, reasons);
    alertTeam(`10DLC brand registration failed: ${JSON.stringify(reasons)}`);
  } else if (type === 'TCR_BRAND_UPDATE') {
    console.log(`Brand ${brandId} TCR event: ${payload.eventType} (${status})`);
  } else if (type === 'ORDER_EXTERNAL_VETTING') {
    console.log(`Brand ${brandId} vetting: ${status}`);
  }
}

function handleCampaignEvent(payload) {
  const { campaignId, type, status, reasons } = payload;

  if (type === 'REGISTRATION' && status === 'failed') {
    console.error(`Campaign ${campaignId} failed:`, reasons);
  } else if (type === 'TELNYX_REVIEW') {
    console.log(`Campaign ${campaignId} Telnyx review: ${status}`);
  } else if (type === 'VERIFIED') {
    console.log(`Campaign ${campaignId} fully provisioned — ready to send!`);
  }
}

function handlePhoneNumberEvent(payload) {
  console.log(`Phone ${payload.phoneNumber} status: ${payload.status}`);
}

app.listen(3000, () => console.log('Webhook server running on port 3000'));

Ruby

require "sinatra"
require "json"

processed_events = Set.new

post "/webhooks/10dlc" do
  event = JSON.parse(request.body.read)
  data = event["data"]
  event_type = data["event_type"]
  payload = data["payload"]
  event_id = data["id"]

  return { status: "already_processed" }.to_json if processed_events.include?(event_id)

  case event_type
  when "10dlc.brand.update"
    if payload["type"] == "REGISTRATION" && payload["status"] == "failed"
      puts "Brand #{payload['brandId']} registration failed: #{payload['reasons']}"
    else
      puts "Brand #{payload['brandId']} event: #{payload['type']} (#{payload['status']})"
    end
  when "10dlc.campaign.update"
    if payload["type"] == "VERIFIED"
      puts "Campaign #{payload['campaignId']} fully provisioned!"
    else
      puts "Campaign event: #{payload['type']} (#{payload['status']})"
    end
  when "10dlc.phone_number.update"
    puts "Phone #{payload['phoneNumber']} status: #{payload['status']}"
  end

  processed_events.add(event_id)
  { status: "ok" }.to_json
end

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "sync"
)

var (
  processed = make(map[string]bool)
  mu        sync.Mutex
)

type WebhookEvent struct {
  Data struct {
    EventType string                 `json:"event_type"`
    ID        string                 `json:"id"`
    Payload   map[string]interface{} `json:"payload"`
  } `json:"data"`
}

func handler(w http.ResponseWriter, r *http.Request) {
  var event WebhookEvent
  json.NewDecoder(r.Body).Decode(&event)

  mu.Lock()
  if processed[event.Data.ID] {
    mu.Unlock()
    json.NewEncoder(w).Encode(map[string]string{"status": "already_processed"})
    return
  }
  processed[event.Data.ID] = true
  mu.Unlock()

  p := event.Data.Payload
  switch event.Data.EventType {
  case "10dlc.brand.update":
    log.Printf("Brand %s event: %s (%s)", p["brandId"], p["type"], p["status"])
  case "10dlc.campaign.update":
    if p["type"] == "VERIFIED" {
      log.Printf("Campaign %s fully provisioned!", p["campaignId"])
    } else {
      log.Printf("Campaign %s event: %s (%s)", p["campaignId"], p["type"], p["status"])
    }
  case "10dlc.phone_number.update":
    log.Printf("Phone %s status: %s", p["phoneNumber"], p["status"])
  }

  w.Header().Set("Content-Type", "application/json")
  fmt.Fprintf(w, `{"status":"ok"}`)
}

func main() {
  http.HandleFunc("/webhooks/10dlc", handler)
  log.Println("Webhook server on :3000")
  log.Fatal(http.ListenAndServe(":3000", nil))
}

PHP

<?php
$processedEvents = [];

$input = json_decode(file_get_contents('php://input'), true);
$data = $input['data'];
$eventType = $data['event_type'];
$payload = $data['payload'];
$eventId = $data['id'];

header('Content-Type: application/json');

if (in_array($eventId, $processedEvents)) {
    echo json_encode(['status' => 'already_processed']);
    exit;
}

switch ($eventType) {
    case '10dlc.brand.update':
        if ($payload['type'] === 'REGISTRATION' && $payload['status'] === 'failed') {
            error_log("Brand {$payload['brandId']} registration failed: " . json_encode($payload['reasons']));
        } else {
            error_log("Brand {$payload['brandId']} event: {$payload['type']} ({$payload['status']})");
        }
        break;

    case '10dlc.campaign.update':
        if ($payload['type'] === 'VERIFIED') {
            error_log("Campaign {$payload['campaignId']} fully provisioned!");
        } else {
            error_log("Campaign event: {$payload['type']} ({$payload['status']})");
        }
        break;

    case '10dlc.phone_number.update':
        error_log("Phone {$payload['phoneNumber']} status: {$payload['status']}");
        break;
}

echo json_encode(['status' => 'ok']);

Important: Always return a 200 response immediately, then process the webhook asynchronously. For production applications, use a message queue (Redis, RabbitMQ, SQS) to decouple webhook receipt from processing.

Webhook delivery

Retry policy

If your webhook endpoint returns a non-2xx HTTP status code or times out, Telnyx will retry delivery. The meta.attempt field in the webhook payload indicates which delivery attempt this is (starting at 1).

Default retry attempts: 5
Default retry interval: 30 seconds between attempts

After 5 failed attempts, the webhook will be marked as failed and no further retries will be made.

Best practices

Return 2xx quickly: Return a 200 response as soon as possible, then process the webhook asynchronously.
Handle duplicates: Webhooks may be delivered more than once. Use the id field to deduplicate.
Use HTTPS: Always use HTTPS endpoints to ensure webhook data is encrypted in transit.
Verify the source: Consider implementing signature verification for added security.
Set up failover: Configure a webhookFailoverURL to receive webhooks if your primary endpoint is unavailable.

Testing webhooks locally

During development, you can use tunneling tools to expose your local server to the internet for webhook testing:

ngrok: Run ngrok http 3000 to create a public URL that forwards to your local port 3000.
Cloudflare Tunnel: Use cloudflared tunnel for a similar tunneling solution.
localtunnel: Run lt --port 3000 for a quick temporary URL.

Update your brand or campaign webhook URL to the tunnel URL, then monitor incoming webhooks as you trigger events in your 10DLC registration flow.

Glossary

Term	Definition
10DLC	10-Digit Long Code. Standard 10-digit phone numbers used for application-to-person (A2P) messaging.
CSP	Campaign Service Provider. A company authorized to submit and manage campaigns on behalf of brands with The Campaign Registry.
DCA	Direct Connect Aggregator. An entity that has a direct connection to mobile carriers for message delivery.
MNO	Mobile Network Operator. Wireless carriers such as T-Mobile, AT&T, and Verizon that deliver SMS/MMS messages to end users.
TCR	The Campaign Registry. The central registry that manages brand and campaign registration for 10DLC messaging in the United States.

Get started with 10DLC brand and campaign registration. Understand throughput limits based on vetting scores. Set up a server to receive webhook notifications. Track delivery status and troubleshoot issues.

Troubleshooting

Source: https://developers.telnyx.com/docs/messaging/10dlc/troubleshooting.md

This guide covers the most common 10DLC failures across brand registration, campaign approval, phone number assignment, and message delivery — with specific error codes, root causes, and fixes. Quick links: Brand issues · Campaign issues · Number assignment issues · Delivery issues · Carrier-specific issues

Brand registration failures

Brand registration fails when TCR cannot verify your business identity. The identityStatus field on your brand object indicates the result.

Status	Meaning
`VERIFIED`	Brand identity confirmed
`UNVERIFIED`	Verification failed — action required
`VETTED_VERIFIED`	External vetting completed successfully
`SELF_DECLARED`	Sole proprietor — limited verification

Common brand failures and fixes

Error: Brand identity verification failed — company name mismatch. Root cause: The companyName you submitted doesn’t match what the IRS has on file for that EIN. Fix:

Look up your exact legal name on the IRS Tax Exempt Organization Search or your incorporation documents
Update your brand with the exact legal name (including suffixes like “Inc.”, “LLC”)
Re-submit for vetting

curl

curl -X PATCH https://api.telnyx.com/v2/10dlc/brand/{brandId} \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyName": "Exact Legal Name Inc."}'

Error: Brand address could not be verified. Root cause: The address doesn’t match USPS records, or uses an incomplete format (e.g., missing suite number). Fix:

Verify your address via USPS Address Lookup
Use the exact USPS-standardized format
Include suite/unit numbers if applicable
Update the brand and re-submit

PO Boxes are generally not accepted. Use a physical business address. Error: Brand website could not be verified. Root cause: TCR checks that the website is live and relates to the registered business. Common issues:

Website is down or returns errors
URL redirects to a different domain
Website content doesn’t match the business name

Fix:

Ensure your website is live and loads without errors
Use the root domain (e.g., https://example.com, not a deep link)
Verify the website clearly identifies your business name
Don’t use placeholder/under-construction pages

Error: A brand with this EIN already exists. Root cause: Your business was already registered with TCR, either by you or another Telnyx account (or through another CSP). Fix:

Check your existing brands: GET /v2/10dlc/brand
If registered under another account, contact Telnyx support to transfer ownership
If registered through another CSP, you can still create campaigns through Telnyx as a secondary CSP

Error: 400 / code 10012. The detail message reads “An external vetting for evpId ‘X’ and vettingClass ‘Y’ already exists for this brand” or “is already being processed for this brand.” Root cause: A successful vetting for the same (evpId, vettingClass) exists within the last 180 days, or one is currently being processed. Fix:

Retrieve existing vettings: GET /v2/10dlc/brand/{brandId}/externalVetting
To order a different vetting, use a different vettingClass (for example ENHANCED instead of STANDARD) or a different evpId
Failed vettings are excluded from this check, so you can retry immediately after a real failure
Successful vettings expire after 6 to 12 months; once expired (TCR EXPIRED status), re-submission is allowed

Error: Brand vetting score too low for desired throughput. Root cause: The third-party vetting partner (Campaign Verify) scored your brand below the threshold for your desired messaging volume. Fix:

Review your brand profile for accuracy — incomplete or inconsistent data lowers scores
Ensure your website, social media, and public records align with your brand information
Request a re-vet after updating information (each vetting attempt has a fee)
See 10DLC Rate Limits for score-to-throughput mapping

Vetting score ranges: 0–24 (low), 25–49 (medium-low), 50–74 (medium), 75–100 (high). Each tier unlocks higher throughput per carrier. Error: OTP verification timed out or failed. Root cause: The one-time password sent to your registered phone number wasn’t confirmed in time, or the phone number can’t receive SMS. Fix:

Ensure the phone number on file can receive SMS
Request a new OTP and complete verification within the time window
Check that the phone number matches your identity documents
See the Sole Proprietor guide for detailed steps

Check brand status via API

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"

brand = telnyx.TenDlcBrand.retrieve("BRAND_ID")
print(f"Status: {brand.identityStatus}")
print(f"Entity Type: {brand.entityType}")

if brand.identityStatus == "UNVERIFIED":
    print("⚠ Brand verification failed. Check rejection reason and update brand info.")

Node

const telnyx = require("telnyx")("YOUR_API_KEY");

const brand = await telnyx.tenDlcBrands.retrieve("BRAND_ID");
console.log(`Status: ${brand.data.identityStatus}`);

if (brand.data.identityStatus === "UNVERIFIED") {
  console.log("⚠ Brand verification failed. Check rejection reason and update brand info.");
}

curl

curl -s https://api.telnyx.com/v2/10dlc/brand/BRAND_ID \
  -H "Authorization: Bearer $TELNYX_API_KEY" | python3 -m json.tool

Campaign rejection reasons

Campaign rejections happen during carrier review. The rejection reason is delivered via 10DLC Event Notifications webhooks.

Rejection Reason	Common Cause	Fix
Samples don’t match use case	Sample messages describe a different use case than declared	Rewrite samples to match the exact declared use case
Missing opt-out language	No STOP/unsubscribe instructions in samples	Add “Reply STOP to unsubscribe” to every sample
Inadequate opt-in description	Opt-in workflow is vague or missing	Describe the exact opt-in mechanism (web form URL, keyword, etc.)
Prohibited content	SHAFT content (sex, hate, alcohol, firearms, tobacco) or cannabis	Remove prohibited content or apply for special use case approval
Brand not vetted	Campaign submitted before brand vetting completed	Complete brand vetting first
Duplicate campaign	Similar campaign already registered for this brand	Use the existing campaign or differentiate the use case
Insufficient sample messages	Not enough variety in sample messages	Provide 2–5 diverse samples showing different message types

Writing samples that pass review

If you registered as “Customer Care,” every sample should be a customer service message:

✅ “Hi Jane, your support ticket #4521 has been resolved. Reply HELP for assistance or STOP to opt out.”

❌ “Flash sale! 50% off today only!” (this is marketing, not customer care)

Every sample message should include opt-out instructions:

✅ “Your order #1234 has shipped. Track: https://example.com/track. Reply STOP to unsubscribe.”

Carriers reject generic or placeholder text:

❌ “This is a test message” ❌ “Hello {name}, this is {company}”

✅ “Hi Sarah, your appointment at Downtown Clinic is confirmed for March 5 at 2:00 PM. Reply C to confirm or R to reschedule. Reply STOP to opt out.”

Provide 2–5 samples that demonstrate different message types within your use case:

Confirmation messages
Follow-up messages
Status update messages
Opt-in confirmation messages

Resubmitting after rejection

You cannot edit a rejected campaign. Create a new one with corrected information:

Python

import telnyx

telnyx.api_key = "YOUR_API_KEY"

# Create a new campaign with corrected samples
campaign = telnyx.TenDlcCampaign.create(
    brandId="BRAND_ID",
    usecase="CUSTOMER_CARE",
    description="Customer support notifications for order updates and ticket resolution",
    sample1="Hi Jane, your support ticket #4521 has been resolved. Let us know if you need anything else. Reply STOP to opt out.",
    sample2="Your order #8876 is out for delivery and should arrive by 3 PM today. Reply STOP to unsubscribe.",
    messageFlow="Customers opt in via checkbox on our website checkout page at https://example.com/checkout. They can opt out at any time by replying STOP.",
    helpMessage="Reply HELP for support options or visit https://example.com/help",
    optoutMessage="You have been unsubscribed and will no longer receive messages from us."
)

print(f"New campaign ID: {campaign.id}")
print(f"Status: {campaign.campaignStatus}")

Each campaign submission incurs a TCR registration fee (

15 standard /

4 low-volume). Review samples carefully before submitting to avoid repeated fees.

Phone number assignment failures

After campaign approval, you must assign phone numbers to the campaign. Failures typically involve number eligibility or carrier registration issues. Error: Phone number is not eligible for 10DLC campaign assignment. Root cause: The number may be:

A toll-free number (use toll-free verification instead)
A short code
Not provisioned for messaging
Already assigned to another campaign

Fix:

Verify the number type: GET /v2/phone_numbers/{id}
Ensure it’s a standard long code (10-digit US number)
Enable messaging on the number if not already configured
Unassign from any existing campaign before reassigning

Error: Phone number registration with AT&T timed out. Root cause: AT&T’s 10DLC registration system can be slow, especially during high-volume periods. Registration can take up to 7 business days. Fix:

Wait 7 business days before escalating
Check the number’s registration status via webhooks or API
If still pending after 7 days, contact Telnyx support

AT&T processes 10DLC number registrations in batches. Delays of 3–5 business days are normal. Error: T-Mobile rejected the phone number registration. Root cause: T-Mobile applies additional scrutiny to numbers with low-score brands or campaigns flagged for review. Fix:

Ensure your brand vetting score is sufficient
Verify the campaign isn’t flagged or suspended
Try reassigning the number after the campaign is fully approved
Contact Telnyx support if the issue persists

Error: Some numbers in a bulk assignment request failed while others succeeded. Root cause: Mixed eligibility in the batch — some numbers may already be assigned or not eligible. Fix: Check results individually and retry only the failed numbers:

Python

import telnyx
import time

telnyx.api_key = "YOUR_API_KEY"

failed_numbers = ["+12125551234", "+12125555678"]  # Numbers that failed

for number in failed_numbers:
    try:
        # Check current assignment status
        resp = telnyx.PhoneNumber.retrieve(number)
        print(f"{number}: messaging_profile={resp.messaging_profile_id}")

        # Retry assignment
        telnyx.TenDlcPhoneNumberCampaign.create(
            phoneNumber=number,
            campaignId="CAMPAIGN_ID"
        )
        print(f"✓ {number} assigned successfully")
    except Exception as e:
        print(f"✗ {number}: {e}")
    time.sleep(1)

Message delivery failures

Even with approved campaigns and assigned numbers, messages can still fail. These are the most common 10DLC-specific delivery errors.

Error Code	Description	Fix
`40300`	Number not registered for 10DLC	Assign the sending number to an approved campaign
`40301`	Campaign suspended	Check campaign status; contact support if unexpected
`40302`	Brand suspended	Review brand status and resolve compliance issues
`40310`	Rate limit exceeded	Reduce sending rate; see 10DLC Rate Limits
`40311`	Daily message limit reached	Wait for daily reset or request higher throughput via vetting
`40320`	Content flagged by carrier	Review message content for SHAFT violations
`40321`	URL blocked by carrier	Remove or replace flagged URLs; use branded short links

Debugging delivery issues

Python

import telnyx
import json

telnyx.api_key = "YOUR_API_KEY"

# Check message detail record for error info
mdr = telnyx.MessageDetailRecord.list(
    direction="outbound",
    phone_number="+12125551234",
    start_date="2026-03-01T00:00:00Z",
    end_date="2026-03-02T00:00:00Z"
)

for record in mdr.data:
    if record.status != "delivered":
        print(f"Message {record.id}")
        print(f"  Status: {record.status}")
        print(f"  Error: {record.errors}")
        print(f"  To: {record.to}")
        print(f"  Sent at: {record.created_at}")

Node

const telnyx = require("telnyx")("YOUR_API_KEY");

const mdrs = await telnyx.messageDetailRecords.list({
  direction: "outbound",
  phone_number: "+12125551234",
  start_date: "2026-03-01T00:00:00Z",
  end_date: "2026-03-02T00:00:00Z",
});

for (const record of mdrs.data) {
  if (record.status !== "delivered") {
    console.log(`Message ${record.id}`);
    console.log(`  Status: ${record.status}`);
    console.log(`  Error: ${JSON.stringify(record.errors)}`);
  }
}

curl

curl -s "https://api.telnyx.com/v2/message_detail_records?direction=outbound&phone_number=%2B12125551234&start_date=2026-03-01T00:00:00Z&end_date=2026-03-02T00:00:00Z" \
  -H "Authorization: Bearer $TELNYX_API_KEY" | python3 -m json.tool

Carrier-specific issues

Each major US carrier handles 10DLC differently. Here are carrier-specific behaviors to be aware of:

AT&T

Issue	Details
Registration delay	3–7 business days for number registration
Content filtering	Aggressive URL filtering; avoid URL shorteners (bit.ly, tinyurl)
Rate limits	Lowest per-campaign limits; vetting score has largest impact
Suspension	Will suspend campaigns with spam complaints without warning

T-Mobile

Issue	Details
Content filtering	Blocks messages with prohibited content patterns
Number reassignment	Requires 24h cooldown when moving numbers between campaigns
Daily limits	Enforces strict daily per-number limits
Opt-out enforcement	Automatically blocks messages to numbers that texted STOP

Verizon

Issue	Details
Registration	Generally fastest registration processing
Content	Less aggressive filtering than AT&T/T-Mobile
Rate limits	More generous throughput at all vetting tiers

Diagnostic checklist

Use this checklist when troubleshooting any 10DLC issue: GET /v2/10dlc/brand/{brandId} — confirm identityStatus is VERIFIED or VETTED_VERIFIED GET /v2/10dlc/campaign/{campaignId} — confirm campaignStatus is ACTIVE GET /v2/10dlc/phoneNumberCampaign?phoneNumber={number} — confirm the sending number is assigned to the active campaign Review 10DLC webhooks for rejection, suspension, or status change events Check MDRs for specific error codes on failed messages Compare your sending rate against your campaign throughput limits. Vetting score determines your ceiling.

Get help

If you’ve followed this guide and still have issues: Open a support ticket with your brand ID, campaign ID, and error details. Check brand, campaign, and number status in Mission Control. Set up webhooks to catch status changes in real time. Review throughput limits by vetting score tier.

RCS

RCS Getting Started

Source: https://developers.telnyx.com/docs/messaging/messages/rcs-getting-started.md

Send rich, interactive messages with RCS (Rich Communication Services). This guide covers the setup process, approval timeline, and how to send your first RCS message.

What is RCS?

RCS is a messaging protocol that delivers app-like experiences in the native messaging app—no app download required. Unlike SMS/MMS, RCS supports:

Rich cards with images, titles, and action buttons
Carousels for product showcases
Suggested replies for quick responses
Read receipts and typing indicators
High-resolution media (images, video, files)

RCS is currently supported on Android devices. Apple announced RCS support in iOS 18.

Prerequisites

A Telnyx account

Approval process

RCS requires agent registration and carrier approval before you can send messages to the general public. The process is similar to short code approval: Contact sales to start the onboarding process. Provide your brand details, use case, and sample message content. Once submitted, Telnyx moves your agent into a testing stage. During this phase, you can invite beta test numbers using the API to test your integration while waiting for carrier approval. Carriers review and approve your agent. This process typically takes 4-6 weeks, similar to short code approval. Once approved, your RCS Agent can send messages to any RCS-capable device. Testing during approval: You don’t have to wait for full carrier approval to start testing. Once your agent is in testing stage, you can add beta numbers and send test messages via the API.

1. Create a Messaging Profile

Navigate to Messaging in the portal. Click Add new profile, give it a name (e.g., “RCS Profile”), and click Save. Copy the Messaging Profile ID—you’ll need it when sending messages.

2. Get your API key

Go to API Keys and copy your API key (or create one if needed).

3. Send an RCS message

Once your RCS Agent is in testing stage (or fully approved), you can send messages to your beta test numbers or approved destinations. Send a simple text message via RCS:

curl

curl -X POST https://api.telnyx.com/v2/messages/rcs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_rcs_agent_id",
    "to": "+15559876543",
    "messaging_profile_id": "your_messaging_profile_id",
    "agent_message": {
      "content_message": {
        "text": "Hello from Telnyx RCS!"
      }
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.rcs.send({
  agent_id: 'your_rcs_agent_id',
  to: '+15559876543',
  messaging_profile_id: 'your_messaging_profile_id',
  agent_message: {
    content_message: {
      text: 'Hello from Telnyx RCS!'
    }
  }
});

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.rcs.send(
    agent_id="your_rcs_agent_id",
    to="+15559876543",
    messaging_profile_id="your_messaging_profile_id",
    agent_message={
        "content_message": {
            "text": "Hello from Telnyx RCS!"
        }
    }
)

print(response.data)

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

response = client.messages.rcs.send(
  agent_id: "your_rcs_agent_id",
  to: "+15559876543",
  messaging_profile_id: "your_messaging_profile_id",
  agent_message: {
    content_message: {
      text: "Hello from Telnyx RCS!"
    }
  }
)

puts(response)

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go/v4"
  "github.com/team-telnyx/telnyx-go/v4/option"
)

func main() {
  client := telnyx.NewClient(
    option.WithAPIKey(os.Getenv("TELNYX_API_KEY")),
  )
  response, err := client.Messages.Rcs.Send(context.TODO(), telnyx.MessageRcSendParams{
    AgentID:            telnyx.String("your_rcs_agent_id"),
    To:                 telnyx.String("+15559876543"),
    MessagingProfileID: telnyx.String("your_messaging_profile_id"),
    AgentMessage: telnyx.RcsAgentMessageParam{
      ContentMessage: telnyx.RcsAgentMessageContentMessageParam{
        Text: telnyx.String("Hello from Telnyx RCS!"),
      },
    },
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.messages.RcsMessageSendParams;
import com.telnyx.sdk.models.messages.RcsMessageSendResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        RcsMessageSendParams params = RcsMessageSendParams.builder()
            .agentId("your_rcs_agent_id")
            .to("+15559876543")
            .messagingProfileId("your_messaging_profile_id")
            .agentMessage(RcsAgentMessage.builder()
                .contentMessage(RcsContentMessage.builder()
                    .text("Hello from Telnyx RCS!")
                    .build())
                .build())
            .build();

        RcsMessageSendResponse response = client.messages().sendRcs(params);
        System.out.println(response);
    }
}

.NET

using Telnyx;

var client = new TelnyxClient(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var response = await client.Messages.SendRcsAsync(new RcsMessageSendParams
{
    AgentId = "your_rcs_agent_id",
    To = "+15559876543",
    MessagingProfileId = "your_messaging_profile_id",
    AgentMessage = new RcsAgentMessage
    {
        ContentMessage = new RcsContentMessage
        {
            Text = "Hello from Telnyx RCS!"
        }
    }
});

Console.WriteLine(response);

PHP

<?php
require 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$response = \Telnyx\Message::createRcs([
    'agent_id' => 'your_rcs_agent_id',
    'to' => '+15559876543',
    'messaging_profile_id' => 'your_messaging_profile_id',
    'agent_message' => [
        'content_message' => [
            'text' => 'Hello from Telnyx RCS!'
        ]
    ]
]);

print_r($response);

Send a rich card with an image and action button:

curl

curl -X POST https://api.telnyx.com/v2/messages/rcs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_rcs_agent_id",
    "to": "+15559876543",
    "messaging_profile_id": "your_messaging_profile_id",
    "agent_message": {
      "content_message": {
        "rich_card": {
          "standalone_card": {
            "card_orientation": "VERTICAL",
            "thumbnail_image_alignment": "LEFT",
            "card_content": {
              "title": "Welcome to Telnyx",
              "description": "Experience rich messaging with RCS",
              "media": {
                "height": "MEDIUM",
                "content_info": {
                  "file_url": "https://example.com/image.jpg"
                }
              },
              "suggestions": [
                {
                  "action": {
                    "text": "Learn More",
                    "postback_data": "learn_more_clicked",
                    "open_url_action": {
                      "url": "https://telnyx.com"
                    }
                  }
                }
              ]
            }
          }
        }
      }
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.rcs.send({
  agent_id: 'your_rcs_agent_id',
  to: '+15559876543',
  messaging_profile_id: 'your_messaging_profile_id',
  agent_message: {
    content_message: {
      rich_card: {
        standalone_card: {
          card_orientation: 'VERTICAL',
          thumbnail_image_alignment: 'LEFT',
          card_content: {
            title: 'Welcome to Telnyx',
            description: 'Experience rich messaging with RCS',
            media: {
              height: 'MEDIUM',
              content_info: {
                file_url: 'https://example.com/image.jpg'
              }
            },
            suggestions: [
              {
                action: {
                  text: 'Learn More',
                  postback_data: 'learn_more_clicked',
                  open_url_action: {
                    url: 'https://telnyx.com'
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
});

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.rcs.send(
    agent_id="your_rcs_agent_id",
    to="+15559876543",
    messaging_profile_id="your_messaging_profile_id",
    agent_message={
        "content_message": {
            "rich_card": {
                "standalone_card": {
                    "card_orientation": "VERTICAL",
                    "thumbnail_image_alignment": "LEFT",
                    "card_content": {
                        "title": "Welcome to Telnyx",
                        "description": "Experience rich messaging with RCS",
                        "media": {
                            "height": "MEDIUM",
                            "content_info": {
                                "file_url": "https://example.com/image.jpg"
                            }
                        },
                        "suggestions": [
                            {
                                "action": {
                                    "text": "Learn More",
                                    "postback_data": "learn_more_clicked",
                                    "open_url_action": {
                                        "url": "https://telnyx.com"
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        }
    }
)

print(response.data)

Media URLs must be publicly accessible. Supported formats include JPEG, PNG, and GIF for images. Add suggested reply buttons for quick customer responses:

curl

curl -X POST https://api.telnyx.com/v2/messages/rcs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_rcs_agent_id",
    "to": "+15559876543",
    "messaging_profile_id": "your_messaging_profile_id",
    "agent_message": {
      "content_message": {
        "text": "How would you rate your experience?",
        "suggestions": [
          {
            "reply": {
              "text": "Great!",
              "postback_data": "rating_great"
            }
          },
          {
            "reply": {
              "text": "Good",
              "postback_data": "rating_good"
            }
          },
          {
            "reply": {
              "text": "Could be better",
              "postback_data": "rating_poor"
            }
          }
        ]
      }
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.rcs.send({
  agent_id: 'your_rcs_agent_id',
  to: '+15559876543',
  messaging_profile_id: 'your_messaging_profile_id',
  agent_message: {
    content_message: {
      text: 'How would you rate your experience?',
      suggestions: [
        {
          reply: {
            text: 'Great!',
            postback_data: 'rating_great'
          }
        },
        {
          reply: {
            text: 'Good',
            postback_data: 'rating_good'
          }
        },
        {
          reply: {
            text: 'Could be better',
            postback_data: 'rating_poor'
          }
        }
      ]
    }
  }
});

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.rcs.send(
    agent_id="your_rcs_agent_id",
    to="+15559876543",
    messaging_profile_id="your_messaging_profile_id",
    agent_message={
        "content_message": {
            "text": "How would you rate your experience?",
            "suggestions": [
                {
                    "reply": {
                        "text": "Great!",
                        "postback_data": "rating_great"
                    }
                },
                {
                    "reply": {
                        "text": "Good",
                        "postback_data": "rating_good"
                    }
                },
                {
                    "reply": {
                        "text": "Could be better",
                        "postback_data": "rating_poor"
                    }
                }
            ]
        }
    }
)

print(response.data)

Response

A successful response looks like this:

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "40319c33-f083-4d2a-a433-a91983b41be5",
    "type": "RCS",
    "messaging_profile_id": "400199c4-6145-43d2-a471-4c459220fcae",
    "from": {
      "agent_id": "your_rcs_agent_id",
      "carrier": "Telnyx",
      "agent_name": "Your Brand"
    },
    "to": [
      {
        "phone_number": "+15559876543",
        "status": "queued",
        "carrier": "T-MOBILE USA, INC.",
        "line_type": "Wireless"
      }
    ],
    "encoding": "utf-8",
    "parts": 1,
    "rcs_message_category": "basic_message"
  }
}

4. Handle incoming messages

Set up a webhook to receive customer replies. See Receiving RCS Webhooks for details.

RCS vs SMS comparison

Feature	RCS	SMS
Rich media	✅ Images, video, files	❌ Text only (MMS for media)
Interactive buttons	✅ Suggested replies & actions	❌
Read receipts	✅	❌
Typing indicators	✅	❌
Branding	✅ Logo, colors, verified sender	❌
Character limit	None	160 (GSM-7)
Carrier registration	Required	10DLC/Toll-free required

Next steps

Add AI-powered responses to your RCS agent Handle incoming RCS messages Check if a number supports RCS Explore all RCS parameters

RCS with AI Assistant

Source: https://developers.telnyx.com/docs/messaging/messages/rcs-ai-assistant.md

Build an AI-powered RCS agent that answers customer questions automatically. By connecting your RCS agent to Telnyx AI Assistant, you get intelligent responses powered by your knowledge base—no custom backend code required.

Why RCS + AI Assistant?

Combining RCS with AI Assistant solves two problems:

RCS carrier onboarding is complex — Carriers require functional agents before approval. AI Assistant gives your agent real functionality instantly.
Building conversational AI is hard — Instead of coding your own NLP/LLM integration, AI Assistant handles it with your knowledge sources.

Traditional approach	With Telnyx AI Assistant
Build custom webhook handler	Configure in portal
Integrate LLM (OpenAI, etc.)	Built-in LLM
Manage conversation state	Handled automatically
Build knowledge retrieval	Upload docs or connect sources
Weeks of development	Minutes to configure

How it works

The key integration point is the Messaging Profile, which links your RCS Agent to an AI Assistant via the ai_assistant_id field.

Prerequisites

A Telnyx account
An approved RCS Agent (or one in the approval process)
Content for your AI Assistant (FAQs, docs, or knowledge base)

1. Create an AI Assistant

Navigate to AI Assistants in the portal. Click Create Assistant and give it a name (e.g., “Support Bot”). Write instructions that define your assistant’s behavior:

You are a helpful customer support agent for [Your Company].

Guidelines:
- Be friendly and professional
- Keep responses concise (under 160 characters when possible)
- If you don't know something, offer to connect them with a human
- Always greet new customers warmly

Upload documents or connect to your knowledge base:

Documents: Upload PDFs, text files, or markdown
Websites: Crawl your help center or documentation
Custom: Connect via API for dynamic content Save your assistant and copy the Assistant ID (e.g., assistant-11deda65-f3f0-457a-9946-ec021622b061).

2. Create a Messaging Profile with AI

Navigate to Messaging in the portal. Click Add new profile and name it (e.g., “RCS AI Profile”). In the profile settings, find AI Assistant and select your assistant from the dropdown (or enter the Assistant ID). Save the profile and copy the Messaging Profile ID.

3. Link your RCS Agent to the AI-enabled profile

Once your RCS Agent is approved by carriers, link it to your AI-enabled messaging profile. If you already have an approved RCS Agent, update it to use your AI-enabled messaging profile:

curl

curl -X PATCH https://api.telnyx.com/v2/rcs_agents/YOUR_RCS_AGENT_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "profile_id": "your_ai_messaging_profile_id"
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.rcsAgents.update('YOUR_RCS_AGENT_ID', {
  profile_id: 'your_ai_messaging_profile_id'
});

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.rcs_agents.update(
    "YOUR_RCS_AGENT_ID",
    profile_id="your_ai_messaging_profile_id"
)

print(response.data)

When submitting your RCS Agent for carrier approval, request that Telnyx provisions it on your existing AI Assistant messaging profile. Contact sales with:

Your AI Assistant ID
Your Messaging Profile ID
Your RCS Agent details

This way, your agent is ready to use AI responses as soon as it’s approved. With a functional AI Assistant attached, your RCS agent has real capabilities to demonstrate during carrier review—making approval easier.

4. Test your AI-powered RCS agent

Once your RCS Agent is approved (or using test numbers), send a message to trigger the AI:

curl

curl -X POST https://api.telnyx.com/v2/messages/rcs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_rcs_agent_id",
    "to": "+15559876543",
    "messaging_profile_id": "your_ai_messaging_profile_id",
    "agent_message": {
      "content_message": {
        "text": "Hello! How can I help you today?"
      }
    }
  }'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const response = await client.messages.rcs.send({
  agent_id: 'your_rcs_agent_id',
  to: '+15559876543',
  messaging_profile_id: 'your_ai_messaging_profile_id',
  agent_message: {
    content_message: {
      text: 'Hello! How can I help you today?'
    }
  }
});

console.log(response.data);

Python

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

response = client.messages.rcs.send(
    agent_id="your_rcs_agent_id",
    to="+15559876543",
    messaging_profile_id="your_ai_messaging_profile_id",
    agent_message={
        "content_message": {
            "text": "Hello! How can I help you today?"
        }
    }
)

print(response.data)

When the customer replies, the AI Assistant automatically:

Receives the inbound message via the messaging profile
Processes it with your configured LLM and knowledge base
Sends an intelligent response back via RCS

No webhook code required—the AI handles the conversation.

Best practices

RCS messages display on mobile devices. Configure your AI to:

Keep responses concise (under 160 characters when possible)
Use bullet points for lists
Avoid long paragraphs

Configure a greeting in your AI Assistant to welcome new customers:

Welcome to [Company] Support! I'm here to help with questions about
our products and services. What can I assist you with today?

Include instructions for when the AI should hand off to a human:

If the customer:
- Asks to speak to a human
- Has a billing dispute
- Is frustrated after 3 exchanges

Respond: "I'd be happy to connect you with our support team.
Please call 1-800-XXX-XXXX or visit support.example.com"

Before going live, test with questions your customers actually ask:

Check your support ticket history
Review FAQ page analytics
Test edge cases and ambiguous questions

Monitoring and analytics

Track your AI Assistant’s performance in the portal:

Conversation logs: Review AI responses and customer satisfaction
Knowledge gaps: Identify questions the AI couldn’t answer
Response times: Monitor latency and throughput

Navigate to AI Assistants > Insights to access analytics.

Pricing

Component	Pricing
RCS messages	See RCS pricing
AI Assistant	See AI pricing

AI Assistant charges are based on tokens processed. Simple Q&A conversations typically cost fractions of a cent per exchange.

Try it yourself

Experience RCS + AI Assistant firsthand by chatting with our demo bot. Requirements: US phone number and RCS-enabled device (Android with Google Messages, or iOS 18+) {/* Deeplink URL from /v2/messages/rcs/deeplinks API - sms: scheme with @rbm.goog is the Google RCS standard */} Tap to open a conversation with our AI-powered support agent This demo uses an RCS deeplink to start the conversation. The deeplink URL is generated by the Telnyx API and uses the standard Google RCS sms: scheme with an @rbm.goog address:

curl -L 'https://api.telnyx.com/v2/messages/rcs/deeplinks/telnyx_support_v9d1aaax_agent' \
  -H 'Authorization: Bearer '

The deeplink opens your messaging app and connects you to our AI-powered support agent, which uses:

Telnyx AI Assistant for natural language understanding
Knowledge retrieval from our documentation
RCS rich messaging for a native chat experience

Next steps

Deep dive into AI Assistant configuration Learn RCS fundamentals Send interactive rich cards Create deeplinks for your own agents

Send RCS Messages

Source: https://developers.telnyx.com/docs/messaging/messages/send-an-rcs-message.md

Send rich, interactive messages using RCS (Rich Communication Services). This guide covers sending text, rich cards, carousels, and configuring SMS fallback for non-RCS devices. New to RCS? Start with the RCS Getting Started guide to set up your RCS agent and get approved by Google.

Prerequisites

A verified RCS agent approved by Google
A messaging profile with RCS enabled
Your agent ID (from the RCS agent setup)

Send a text message

The simplest RCS message — plain text with optional suggested replies:

curl

curl -X POST https://api.telnyx.com/v2/messages/rcs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_agent_id",
    "to": "+15559876543",
    "messaging_profile_id": "your_messaging_profile_id",
    "agent_message": {
      "content_message": {
        "text": "Hi! How can we help you today?"
      }
    }
  }'

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.telnyx.com/v2/messages/rcs",
    headers=headers,
    json={
        "agent_id": "your_agent_id",
        "to": "+15559876543",
        "messaging_profile_id": "your_messaging_profile_id",
        "agent_message": {
            "content_message": {
                "text": "Hi! How can we help you today?"
            }
        },
    },
)

print(f"Message sent: {response.json()['data']['id']}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
  'Content-Type': 'application/json',
};

const response = await axios.post(
  'https://api.telnyx.com/v2/messages/rcs',
  {
    agent_id: 'your_agent_id',
    to: '+15559876543',
    messaging_profile_id: 'your_messaging_profile_id',
    agent_message: {
      content_message: {
        text: 'Hi! How can we help you today?',
      },
    },
  },
  { headers }
);

console.log(`Message sent: ${response.data.data.id}`);

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.telnyx.com/v2/messages/rcs")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
request["Content-Type"] = "application/json"
request.body = {
  agent_id: "your_agent_id",
  to: "+15559876543",
  messaging_profile_id: "your_messaging_profile_id",
  agent_message: {
    content_message: {
      text: "Hi! How can we help you today?"
    }
  }
}.to_json

response = http.request(request)
data = JSON.parse(response.body)
puts "Message sent: #{data['data']['id']}"

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func main() {
  payload := map[string]interface{}{
    "agent_id":              "your_agent_id",
    "to":                    "+15559876543",
    "messaging_profile_id":  "your_messaging_profile_id",
    "agent_message": map[string]interface{}{
      "content_message": map[string]interface{}{
        "text": "Hi! How can we help you today?",
      },
    },
  }

  body, _ := json.Marshal(payload)
  req, _ := http.NewRequest("POST", "https://api.telnyx.com/v2/messages/rcs", bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  data := result["data"].(map[string]interface{})
  fmt.Printf("Message sent: %s\n", data["id"])
}

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');

$payload = [
    'agent_id' => 'your_agent_id',
    'to' => '+15559876543',
    'messaging_profile_id' => 'your_messaging_profile_id',
    'agent_message' => [
        'content_message' => [
            'text' => 'Hi! How can we help you today?'
        ]
    ]
];

$ch = curl_init('https://api.telnyx.com/v2/messages/rcs');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Message sent: {$response['data']['id']}\n";

Send a rich card

Rich cards display media, text, and action buttons in an interactive format:

curl

curl -X POST https://api.telnyx.com/v2/messages/rcs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_agent_id",
    "to": "+15559876543",
    "messaging_profile_id": "your_messaging_profile_id",
    "agent_message": {
      "content_message": {
        "rich_card": {
          "standalone_card": {
            "card_orientation": "VERTICAL",
            "thumbnail_image_alignment": "LEFT",
            "card_content": {
              "title": "Order Shipped! 📦",
              "description": "Your order #12345 is on its way. Expected delivery: March 15.",
              "media": {
                "height": "MEDIUM",
                "content_info": {
                  "file_url": "https://example.com/shipping.jpg",
                  "content_type": "image/jpeg"
                }
              },
              "suggestions": [
                {
                  "action": {
                    "text": "Track Order",
                    "open_url_action": {
                      "url": "https://example.com/track/12345"
                    }
                  }
                },
                {
                  "reply": {
                    "text": "Contact Support",
                    "postback_data": "support_request"
                  }
                }
              ]
            }
          }
        }
      }
    }
  }'

Python

response = requests.post(
    "https://api.telnyx.com/v2/messages/rcs",
    headers=headers,
    json={
        "agent_id": "your_agent_id",
        "to": "+15559876543",
        "messaging_profile_id": "your_messaging_profile_id",
        "agent_message": {
            "content_message": {
                "rich_card": {
                    "standalone_card": {
                        "card_orientation": "VERTICAL",
                        "thumbnail_image_alignment": "LEFT",
                        "card_content": {
                            "title": "Order Shipped! 📦",
                            "description": "Your order #12345 is on its way.",
                            "media": {
                                "height": "MEDIUM",
                                "content_info": {
                                    "file_url": "https://example.com/shipping.jpg",
                                    "content_type": "image/jpeg",
                                },
                            },
                            "suggestions": [
                                {
                                    "action": {
                                        "text": "Track Order",
                                        "open_url_action": {
                                            "url": "https://example.com/track/12345"
                                        },
                                    }
                                },
                                {
                                    "reply": {
                                        "text": "Contact Support",
                                        "postback_data": "support_request",
                                    }
                                },
                            ],
                        },
                    }
                }
            }
        },
    },
)

print(f"Rich card sent: {response.json()['data']['id']}")

Node

const response = await axios.post(
  'https://api.telnyx.com/v2/messages/rcs',
  {
    agent_id: 'your_agent_id',
    to: '+15559876543',
    messaging_profile_id: 'your_messaging_profile_id',
    agent_message: {
      content_message: {
        rich_card: {
          standalone_card: {
            card_orientation: 'VERTICAL',
            thumbnail_image_alignment: 'LEFT',
            card_content: {
              title: 'Order Shipped! 📦',
              description: 'Your order #12345 is on its way.',
              media: {
                height: 'MEDIUM',
                content_info: {
                  file_url: 'https://example.com/shipping.jpg',
                  content_type: 'image/jpeg',
                },
              },
              suggestions: [
                {
                  action: {
                    text: 'Track Order',
                    open_url_action: {
                      url: 'https://example.com/track/12345',
                    },
                  },
                },
                {
                  reply: {
                    text: 'Contact Support',
                    postback_data: 'support_request',
                  },
                },
              ],
            },
          },
        },
      },
    },
  },
  { headers }
);

console.log(`Rich card sent: ${response.data.data.id}`);

Card options

Property	Values	Description
`card_orientation`	`VERTICAL`, `HORIZONTAL`	Card layout direction
`thumbnail_image_alignment`	`LEFT`, `RIGHT`	Image position (horizontal cards only)
`media.height`	`SHORT`, `MEDIUM`, `TALL`	Image display height

Send a carousel

Display multiple cards in a swipeable carousel — ideal for product listings:

curl

curl -X POST https://api.telnyx.com/v2/messages/rcs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_agent_id",
    "to": "+15559876543",
    "messaging_profile_id": "your_messaging_profile_id",
    "agent_message": {
      "content_message": {
        "rich_card": {
          "carousel_card": {
            "card_width": "MEDIUM",
            "card_contents": [
              {
                "title": "Classic Burger",
                "description": "$8.99 — Our signature burger",
                "media": {
                  "height": "MEDIUM",
                  "content_info": {
                    "file_url": "https://example.com/burger.jpg"
                  }
                },
                "suggestions": [
                  {
                    "action": {
                      "text": "Order Now",
                      "open_url_action": {
                        "url": "https://example.com/order/burger"
                      }
                    }
                  }
                ]
              },
              {
                "title": "Veggie Wrap",
                "description": "$7.49 — Fresh and healthy",
                "media": {
                  "height": "MEDIUM",
                  "content_info": {
                    "file_url": "https://example.com/wrap.jpg"
                  }
                },
                "suggestions": [
                  {
                    "action": {
                      "text": "Order Now",
                      "open_url_action": {
                        "url": "https://example.com/order/wrap"
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }'

Carousels require a minimum of 2 cards and a maximum of 10. All cards in a carousel use the same card_width.

Add suggested actions

Suggestions appear as tappable buttons below your message: Quick reply buttons that send a predefined response back to your webhook:

"suggestions": [
  {
    "reply": {
      "text": "Yes, confirm",
      "postback_data": "confirm_order_12345"
    }
  },
  {
    "reply": {
      "text": "No, cancel",
      "postback_data": "cancel_order_12345"
    }
  }
]

Open a URL in the device browser:

"suggestions": [
  {
    "action": {
      "text": "Visit Website",
      "open_url_action": {
        "url": "https://example.com"
      }
    }
  }
]

Initiate a phone call:

"suggestions": [
  {
    "action": {
      "text": "Call Us",
      "dial_action": {
        "phone_number": "+15551234567"
      }
    }
  }
]

Open a map location:

"suggestions": [
  {
    "action": {
      "text": "Get Directions",
      "view_location_action": {
        "lat_long": {
          "latitude": 40.7128,
          "longitude": -74.0060
        },
        "label": "Acme Corp HQ"
      }
    }
  }
]

SMS fallback

Not all devices support RCS. Configure automatic SMS fallback for non-RCS recipients:

curl

curl -X POST https://api.telnyx.com/v2/messages/rcs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_agent_id",
    "to": "+15559876543",
    "messaging_profile_id": "your_messaging_profile_id",
    "agent_message": {
      "content_message": {
        "text": "Your order #12345 has shipped! Track at https://example.com/track/12345"
      }
    },
    "fallback": {
      "from": "+15551234567",
      "text": "Your order #12345 has shipped! Track at https://example.com/track/12345"
    }
  }'

Python

response = requests.post(
    "https://api.telnyx.com/v2/messages/rcs",
    headers=headers,
    json={
        "agent_id": "your_agent_id",
        "to": "+15559876543",
        "messaging_profile_id": "your_messaging_profile_id",
        "agent_message": {
            "content_message": {
                "text": "Your order #12345 has shipped! Track at https://example.com/track/12345"
            }
        },
        "fallback": {
            "from": "+15551234567",
            "text": "Your order #12345 has shipped! Track at https://example.com/track/12345",
        },
    },
)

data = response.json()["data"]
print(f"Sent via: {data['type']}")  # "RCS" or "SMS" depending on device support

Node

const response = await axios.post(
  'https://api.telnyx.com/v2/messages/rcs',
  {
    agent_id: 'your_agent_id',
    to: '+15559876543',
    messaging_profile_id: 'your_messaging_profile_id',
    agent_message: {
      content_message: {
        text: 'Your order #12345 has shipped!',
      },
    },
    fallback: {
      from: '+15551234567',
      text: 'Your order #12345 has shipped! Track at https://example.com/track/12345',
    },
  },
  { headers }
);

console.log(`Sent via: ${response.data.data.type}`);

The fallback.from number must be a Telnyx number on your messaging profile with SMS capability. The fallback message is plain text only — rich card content is not included.

RCS vs. SMS/MMS comparison

Feature	RCS	SMS	MMS
Rich cards	✅	❌	❌
Carousels	✅	❌	❌
Suggested actions	✅	❌	❌
Read receipts	✅	❌	❌
Typing indicators	✅	❌	❌
Images/video	✅ High-res	❌	✅ Compressed
Character limit	None	160/segment	None
Device support	Android (+ iOS 18)	Universal	Universal
Encoding	UTF-8	GSM-7/UTF-16	UTF-8

Set up your RCS agent and get approved by Google. Check device RCS capability before sending. Handle inbound RCS messages and delivery events. Full API reference for RCS messaging.

Capabilities & Deeplinks

Source: https://developers.telnyx.com/docs/messaging/messages/rcs-capabilities.md

Check whether a recipient’s device supports RCS — and which features it supports — before sending. This lets you adapt your message format (rich card vs. plain text) and fall back to SMS when needed.

Query single number

Check RCS capabilities for a single phone number:

curl

curl -s https://api.telnyx.com/v2/messaging/rcs/capabilities/{agent_id}/{phone_number} \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import os
import requests

API_KEY = os.environ.get("TELNYX_API_KEY")
AGENT_ID = "your_agent_id"

headers = {"Authorization": f"Bearer {API_KEY}"}

def check_rcs_capabilities(phone_number: str) -> dict:
    """Check if a phone number supports RCS and which features."""
    response = requests.get(
        f"https://api.telnyx.com/v2/messaging/rcs/capabilities/{AGENT_ID}/{phone_number}",
        headers=headers,
    )
    data = response.json()["data"]
    return {
        "phone_number": data["phone_number"],
        "rcs_enabled": bool(data.get("features")),
        "features": data.get("features") or [],
        "supports_rich_cards": "RICHCARD_STANDALONE" in (data.get("features") or []),
        "supports_carousel": "RICHCARD_CAROUSEL" in (data.get("features") or []),
    }

result = check_rcs_capabilities("+15559876543")
print(f"RCS enabled: {result['rcs_enabled']}")
print(f"Features: {result['features']}")

Node

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
};
const agentId = 'your_agent_id';

async function checkRcsCapabilities(phoneNumber) {
  const response = await axios.get(
    `https://api.telnyx.com/v2/messaging/rcs/capabilities/${agentId}/${phoneNumber}`,
    { headers }
  );
  const { data } = response.data;
  return {
    phoneNumber: data.phone_number,
    rcsEnabled: Boolean(data.features?.length),
    features: data.features || [],
    supportsRichCards: data.features?.includes('RICHCARD_STANDALONE') ?? false,
    supportsCarousel: data.features?.includes('RICHCARD_CAROUSEL') ?? false,
  };
}

const result = await checkRcsCapabilities('+15559876543');
console.log(`RCS enabled: ${result.rcsEnabled}`);
console.log(`Features: ${result.features.join(', ')}`);

Ruby

require "net/http"
require "json"
require "uri"

api_key = ENV["TELNYX_API_KEY"]
agent_id = "your_agent_id"

def check_rcs(agent_id, phone_number, api_key)
  uri = URI("https://api.telnyx.com/v2/messaging/rcs/capabilities/#{agent_id}/#{phone_number}")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer #{api_key}"
  response = http.request(request)
  data = JSON.parse(response.body)["data"]
  {
    rcs_enabled: !data["features"].nil? && !data["features"].empty?,
    features: data["features"] || []
  }
end

result = check_rcs(agent_id, "+15559876543", api_key)
puts "RCS enabled: #{result[:rcs_enabled]}"

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func checkRCS(agentID, phoneNumber string) ([]string, error) {
  url := fmt.Sprintf("https://api.telnyx.com/v2/messaging/rcs/capabilities/%s/%s", agentID, phoneNumber)
  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TELNYX_API_KEY"))

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    return nil, err
  }
  defer resp.Body.Close()

  var result struct {
    Data struct {
      Features []string `json:"features"`
    } `json:"data"`
  }
  json.NewDecoder(resp.Body).Decode(&result)
  return result.Data.Features, nil
}

func main() {
  features, _ := checkRCS("your_agent_id", "+15559876543")
  fmt.Printf("Features: %v\n", features)
}

PHP

<?php
$apiKey = getenv('TELNYX_API_KEY');
$agentId = 'your_agent_id';
$phoneNumber = '+15559876543';

$ch = curl_init("https://api.telnyx.com/v2/messaging/rcs/capabilities/{$agentId}/{$phoneNumber}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer {$apiKey}"],
]);

$data = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);

$rcsEnabled = !empty($data['features']);
echo "RCS enabled: " . ($rcsEnabled ? 'yes' : 'no') . "\n";
echo "Features: " . implode(', ', $data['features'] ?? []) . "\n";

Response examples

{
  "data": {
    "record_type": "rcs.capabilities",
    "phone_number": "+15559876543",
    "agent_id": "your_agent_id",
    "agent_name": "Acme Bot",
    "features": [
      "ACTION_CREATE_CALENDAR_EVENT",
      "ACTION_DIAL",
      "ACTION_OPEN_URL",
      "ACTION_OPEN_URL_IN_WEBVIEW",
      "ACTION_SHARE_LOCATION",
      "ACTION_VIEW_LOCATION",
      "RICHCARD_CAROUSEL",
      "RICHCARD_STANDALONE"
    ],
    "status": "Success"
  }
}

{
  "data": {
    "features": ["GENERIC_RCS_FEATURE"],
    "status": "Success"
  }
}

The device supports RCS but specific features couldn’t be determined. Send basic RCS text — avoid rich cards.

{
  "data": {
    "features": null,
    "status": "RCS is disabled or agent is not provisioned for the carrier"
  }
}

Fall back to SMS/MMS for this recipient.

Feature reference

Feature	Description	Use for
`RICHCARD_STANDALONE`	Single rich card support	Product cards, order updates
`RICHCARD_CAROUSEL`	Swipeable carousel cards	Product listings, menus
`ACTION_OPEN_URL`	Open URL button	Links to websites
`ACTION_OPEN_URL_IN_WEBVIEW`	Open URL in webview	In-app browsing
`ACTION_DIAL`	Phone call button	Click-to-call
`ACTION_VIEW_LOCATION`	View map location	Directions, store locator
`ACTION_SHARE_LOCATION`	Share user’s location	Delivery tracking
`ACTION_CREATE_CALENDAR_EVENT`	Add calendar event	Appointment booking
`ACTION_COMPOSE`	Compose message	Message drafting
`GENERIC_RCS_FEATURE`	Basic RCS (details unknown)	Text-only RCS

Bulk capability query

Check up to 100 numbers at once to efficiently segment your audience:

curl

curl -X POST https://api.telnyx.com/v2/messaging/rcs/bulk_capabilities \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your_agent_id",
    "phone_numbers": ["+15551234567", "+15559876543", "+15550001111"]
  }'

Python

def bulk_check_rcs(phone_numbers: list[str]) -> dict:
    """Check RCS capabilities for up to 100 numbers."""
    response = requests.post(
        "https://api.telnyx.com/v2/messaging/rcs/bulk_capabilities",
        headers={**headers, "Content-Type": "application/json"},
        json={
            "agent_id": AGENT_ID,
            "phone_numbers": phone_numbers,
        },
    )

    results = {"rcs": [], "sms_fallback": []}
    for entry in response.json()["data"]:
        if entry.get("features"):
            results["rcs"].append(entry["phone_number"])
        else:
            results["sms_fallback"].append(entry["phone_number"])

    return results

# Segment audience
numbers = ["+15551234567", "+15559876543", "+15550001111"]
segments = bulk_check_rcs(numbers)
print(f"RCS capable: {len(segments['rcs'])}")
print(f"SMS fallback: {len(segments['sms_fallback'])}")

Node

async function bulkCheckRcs(phoneNumbers) {
  const response = await axios.post(
    'https://api.telnyx.com/v2/messaging/rcs/bulk_capabilities',
    {
      agent_id: agentId,
      phone_numbers: phoneNumbers,
    },
    { headers: { ...headers, 'Content-Type': 'application/json' } }
  );

  const results = { rcs: [], smsFallback: [] };
  for (const entry of response.data.data) {
    if (entry.features?.length) {
      results.rcs.push(entry.phone_number);
    } else {
      results.smsFallback.push(entry.phone_number);
    }
  }
  return results;
}

const segments = await bulkCheckRcs(['+15551234567', '+15559876543']);
console.log(`RCS: ${segments.rcs.length}, SMS: ${segments.smsFallback.length}`);

RCS capability queries can be slow (several seconds per request). For time-sensitive applications, cache results and refresh periodically rather than querying before every message.

Send with automatic fallback

Use capability queries to send the best possible message format:

Python

def send_adaptive_message(to: str, title: str, body: str, image_url: str = None):
    """Send RCS rich card if supported, otherwise fall back to SMS."""
    caps = check_rcs_capabilities(to)

    if caps["supports_rich_cards"] and image_url:
        # Send rich card
        requests.post(
            "https://api.telnyx.com/v2/messages/rcs",
            headers={**headers, "Content-Type": "application/json"},
            json={
                "agent_id": AGENT_ID,
                "to": to,
                "messaging_profile_id": PROFILE_ID,
                "agent_message": {
                    "content_message": {
                        "rich_card": {
                            "standalone_card": {
                                "card_orientation": "VERTICAL",
                                "card_content": {
                                    "title": title,
                                    "description": body,
                                    "media": {
                                        "height": "MEDIUM",
                                        "content_info": {"file_url": image_url},
                                    },
                                },
                            }
                        }
                    }
                },
                "fallback": {
                    "from": FROM_NUMBER,
                    "text": f"{title}\n{body}",
                },
            },
        )
    elif caps["rcs_enabled"]:
        # Send RCS text (no rich card support)
        requests.post(
            "https://api.telnyx.com/v2/messages/rcs",
            headers={**headers, "Content-Type": "application/json"},
            json={
                "agent_id": AGENT_ID,
                "to": to,
                "messaging_profile_id": PROFILE_ID,
                "agent_message": {
                    "content_message": {"text": f"{title}\n{body}"}
                },
                "fallback": {"from": FROM_NUMBER, "text": f"{title}\n{body}"},
            },
        )
    else:
        # Send SMS directly
        requests.post(
            "https://api.telnyx.com/v2/messages",
            headers={**headers, "Content-Type": "application/json"},
            json={"from": FROM_NUMBER, "to": to, "text": f"{title}\n{body}"},
        )

RCS Deeplinks

Deeplinks let users start an RCS conversation from a website, email, or QR code — without having your number saved.

Generate a deeplink

curl

# With fallback phone number and message body
curl -s 'https://api.telnyx.com/v2/messages/rcs/deeplinks/{agent_id}?phone_number=%2B15554443333&body=hello%20world' \
  -H "Authorization: Bearer YOUR_API_KEY"

# Without fallback (RCS only)
curl -s 'https://api.telnyx.com/v2/messages/rcs/deeplinks/{agent_id}' \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import urllib.parse

def generate_deeplink(
    agent_id: str,
    fallback_phone: str = None,
    message_body: str = None,
) -> str:
    """Generate an RCS deeplink URL."""
    url = f"https://api.telnyx.com/v2/messages/rcs/deeplinks/{agent_id}"
    params = {}
    if fallback_phone:
        params["phone_number"] = fallback_phone
    if message_body:
        params["body"] = message_body

    if params:
        url += "?" + urllib.parse.urlencode(params)

    response = requests.get(url, headers=headers)
    return response.json()["data"]["url"]

# Generate deeplink with fallback
link = generate_deeplink(
    agent_id="your_agent_id",
    fallback_phone="+15554443333",
    message_body="Hi, I'd like to learn more!",
)
print(f"Deeplink: {link}")

Node

async function generateDeeplink(agentId, fallbackPhone, messageBody) {
  const params = new URLSearchParams();
  if (fallbackPhone) params.set('phone_number', fallbackPhone);
  if (messageBody) params.set('body', messageBody);

  const url = `https://api.telnyx.com/v2/messages/rcs/deeplinks/${agentId}${
    params.toString() ? '?' + params.toString() : ''
  }`;

  const response = await axios.get(url, { headers });
  return response.data.data.url;
}

const link = await generateDeeplink('your_agent_id', '+15554443333', 'Hi!');
console.log(`Deeplink: ${link}`);

Response

{
  "data": {
    "url": "sms:+18445550001?service_id=agent_id%40rbm.goog&body=hello%20world"
  }
}

Use deeplinks

Embed the deeplink in an HTML button or link. The URL won’t open directly in a browser — it must be an “ tag or button click:


  💬 Chat with us on RCS

Convert the deeplink URL to a QR code for print materials, in-store signage, or business cards. Users scan with their camera to open an RCS conversation. Include the deeplink in marketing emails as a CTA button. When tapped on Android with Google Messages, it opens the RCS conversation directly.

Requirements

Requirement	Details
Device	Android with Google Messages installed
OS version	`messages.android_20241029_00` or later
Fallback	Use `phone_number` parameter for non-RCS devices (opens SMS instead)

Send text, rich cards, carousels, and suggested actions. Handle inbound RCS messages and delivery events. Set up your RCS agent and get approved. Full API reference for RCS messaging.

RCS Deeplinks

Source: https://developers.telnyx.com/docs/messaging/messages/rcs-deeplinks.md

RCS Deeplinks content has been consolidated into the RCS Capabilities & Deeplinks guide. See the RCS Deeplinks section for full documentation including SDK examples and usage patterns.

Quick reference

Generate a deeplink to start an RCS conversation:

curl -s 'https://api.telnyx.com/v2/messages/rcs/deeplinks/{agent_id}?phone_number=%2B15554443333&body=hello%20world' \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "url": "sms:+18445550001?service_id=agent_id%40rbm.goog&body=hello%20world"
  }
}

For SDK examples, fallback configuration, and usage patterns (website buttons, QR codes, email campaigns), see: Full guide including capability queries, adaptive sending, and deeplink generation.

RCS Webhooks

Source: https://developers.telnyx.com/docs/messaging/messages/receiving-rcs-webhooks.md

Telnyx sends webhooks to notify your application about RCS messaging events — delivery status updates, inbound messages, read receipts, and suggestion responses. This guide covers RCS-specific webhook payloads, how they differ from SMS/MMS, and how to handle them in your application.

Prerequisites

A Telnyx account with an RCS Agent
A publicly accessible HTTPS endpoint (or ngrok for local development)
Your API key and public key (for signature verification)

RCS vs SMS/MMS webhooks

RCS webhooks have significant structural differences from SMS/MMS. Understanding these is critical when building a multi-channel messaging application.

Feature	SMS/MMS	RCS
Message body	`payload.text` (string)	`payload.body.text` (nested object)
Media format	`payload.media[]` with Telnyx URLs	`payload.body.user_file` with GCS URLs
Sender identifier	`from.phone_number`	`from.phone_number` (inbound) or `from.agent_id` + `from.agent_name` (outbound)
Recipient identifier	`to[].phone_number`	`to[].phone_number` (outbound) or `to[].agent_id` + `to[].agent_name` (inbound)
Read receipts	Not supported	✅ `message.read` event
Suggestion responses	Not applicable	✅ `body.suggestion_response`
Location sharing	Not supported	✅ `body.location`
JSON schema	Telnyx messaging schema	Snake-case schema based on Google RCS API
Webhook URL source	Messaging profile or per-request	RCS Agent config (inbound) + messaging profile (outbound status)

For SMS/MMS webhook handling, see Receiving Webhooks for Messaging.

Webhook URL configuration

RCS webhook routing differs from SMS/MMS:

Event Type	Webhook Source
Inbound messages (`message.received`)	Configured on the RCS Agent
Outbound status (`message.sent`, `message.finalized`, `message.read`)	Per-request URL → messaging profile URL → none

URL priority for outbound status

If webhook_url and webhook_failover_url are provided in the send request body, those are used. If the messaging profile has webhook URLs configured, those are used. If neither is configured, no webhook is delivered. Events are still logged in Message Detail Records.

Webhook event types

Event	Description	Direction
`message.sent`	Message sent to the upstream RCS provider	Outbound
`message.finalized`	Delivery confirmed or failed by carrier	Outbound
`message.read`	Recipient read the message on their device	Outbound
`message.received`	Inbound message received by your RCS Agent	Inbound

Delivery status webhooks

When you send an RCS message, Telnyx notifies you as the message progresses through each status.

Delivery status flow

Status reference

Status	Description
`queued`	Message queued on Telnyx’s side
`sending`	Being sent to the upstream RCS provider
`sent`	Sent to the upstream provider
`delivered`	Carrier confirmed delivery to the device
`read`	Message read on the recipient’s device
`sending_failed`	Failed to send to the upstream provider
`delivery_failed`	Carrier could not deliver to the recipient
`delivery_unconfirmed`	No delivery confirmation received

Example: Delivery receipt payload

{
  "data": {
    "event_type": "message.finalized",
    "id": "4ee8c3a6-4995-4309-a3c6-38e3db9ea4be",
    "occurred_at": "2024-12-09T21:32:14.148+00:00",
    "payload": {
      "body": {
        "text": "Hello there!"
      },
      "completed_at": "2024-12-09T21:32:14.148+00:00",
      "cost": null,
      "direction": "outbound",
      "errors": [],
      "from": {
        "agent_id": "e4448a5c0670c2a9",
        "agent_name": "My RCS Agent"
      },
      "id": "ac012cbf-5e09-46af-a69a-7c0e2d90993c",
      "messaging_profile_id": "83d2343b-553f-4c5f-b8c8-fd27004f94bf",
      "organization_id": "9d76d591-1b7d-405d-8c64-1320ee070245",
      "received_at": "2024-12-09T21:32:13.552+00:00",
      "record_type": "message",
      "sent_at": "2024-12-09T21:32:13.596+00:00",
      "tags": [],
      "to": [
        {
          "carrier": "T-MOBILE USA, INC.",
          "line_type": "Wireless",
          "phone_number": "+13125000000",
          "status": "delivered"
        }
      ],
      "type": "RCS",
      "valid_until": "2024-12-09T22:32:13.552+00:00",
      "webhook_failover_url": "",
      "webhook_url": "http://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "http://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
  }
}

Read receipts

RCS uniquely supports read receipts — a message.read event is sent when the recipient opens and views your message. This is not available with SMS/MMS.

Example: Read receipt payload

{
  "data": {
    "event_type": "message.read",
    "id": "7bc4d2e1-3f89-4a12-b5c7-9e8d1a2f3b4c",
    "occurred_at": "2024-12-09T21:35:22.000+00:00",
    "payload": {
      "body": {
        "text": "Hello there!"
      },
      "direction": "outbound",
      "from": {
        "agent_id": "e4448a5c0670c2a9",
        "agent_name": "My RCS Agent"
      },
      "id": "ac012cbf-5e09-46af-a69a-7c0e2d90993c",
      "messaging_profile_id": "83d2343b-553f-4c5f-b8c8-fd27004f94bf",
      "to": [
        {
          "phone_number": "+13125000000",
          "status": "read"
        }
      ],
      "type": "RCS"
    },
    "record_type": "event"
  }
}

Handling read receipts

Use read receipts to:

Track engagement — Know which messages were actually read vs. just delivered
Trigger follow-ups — Send a follow-up if a message was delivered but not read after a threshold
Analytics — Calculate read rates for different message types or campaigns
UI updates — Show “read” indicators in your chat interface (like blue checkmarks)

Not all devices or carriers support read receipts. A missing message.read event doesn’t necessarily mean the message wasn’t read — the user may have disabled read receipts on their device.

Inbound message webhooks

When someone sends an RCS message to your agent, Telnyx delivers a message.received webhook to the URL configured on your RCS Agent.

Inbound message types

RCS supports richer inbound message types than SMS/MMS:

{
  "data": {
    "event_type": "message.received",
    "id": "b301ed3f-1490-491f-995f-6e64e69674d4",
    "occurred_at": "2024-12-09T20:16:07.588+00:00",
    "payload": {
      "body": {
        "text": "Hello from Telnyx!"
      },
      "direction": "inbound",
      "from": {
        "carrier": "T-Mobile USA",
        "line_type": "long_code",
        "phone_number": "+13125000000",
        "status": "webhook_delivered"
      },
      "id": "84cca175-9755-4859-b67f-4730d7f58aa3",
      "messaging_profile_id": "740572b6-099c-44a1-89b9-6c92163bc68d",
      "to": [
        {
          "agent_id": "e4448a5c0670c2a9",
          "agent_name": "My RCS Agent"
        }
      ],
      "type": "RCS"
    },
    "record_type": "event"
  }
}

{
  "data": {
    "event_type": "message.received",
    "payload": {
      "body": {
        "user_file": {
          "payload": {
            "file_name": "photo.jpg",
            "file_size_bytes": 179099,
            "file_uri": "https://rcs-inbound.us-central-1.telnyxcloudstorage.com/rcs/.../photo.jpg",
            "mime_type": "image/jpeg"
          },
          "thumbnail": {
            "file_name": "photo_thumb.jpg",
            "file_size_bytes": 12074,
            "file_uri": "https://rcs-inbound.us-central-1.telnyxcloudstorage.com/rcs/.../photo_thumb.jpg",
            "mime_type": "image/jpeg"
          }
        }
      },
      "direction": "inbound",
      "type": "RCS"
    }
  }
}

Unlike MMS where media URLs are in payload.media[], RCS file attachments are nested under payload.body.user_file with both a full-resolution payload and a thumbnail.

{
  "data": {
    "event_type": "message.received",
    "payload": {
      "body": {
        "location": {
          "latitude": 38.24961321640261,
          "longitude": -85.78378468751907
        }
      },
      "direction": "inbound",
      "type": "RCS"
    }
  }
}

When a user taps a suggested action or reply that you included in a previous message:

{
  "data": {
    "event_type": "message.received",
    "payload": {
      "body": {
        "suggestion_response": {
          "postback_data": "action_visit_store",
          "text": "Explore the online store"
        }
      },
      "direction": "inbound",
      "type": "RCS"
    }
  }
}

Use postback_data for programmatic routing and text for the user-visible label.

SDK webhook handling examples

Handle RCS webhooks in your application with proper event routing, signature verification, and message type detection.

Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/rcs", methods=["POST"])
def handle_rcs_webhook():
    event = request.json
    event_type = event["data"]["event_type"]
    payload = event["data"]["payload"]

    if event_type == "message.received":
        handle_inbound(payload)
    elif event_type == "message.sent":
        print(f"Message {payload['id']} sent")
    elif event_type == "message.finalized":
        handle_delivery(payload)
    elif event_type == "message.read":
        handle_read_receipt(payload)

    return jsonify({"status": "ok"}), 200

def handle_inbound(payload):
    body = payload["body"]
    sender = payload["from"]["phone_number"]

    if "text" in body:
        print(f"Text from {sender}: {body['text']}")
    elif "user_file" in body:
        file_info = body["user_file"]["payload"]
        print(f"File from {sender}: {file_info['file_name']} ({file_info['mime_type']})")
    elif "location" in body:
        loc = body["location"]
        print(f"Location from {sender}: {loc['latitude']}, {loc['longitude']}")
    elif "suggestion_response" in body:
        resp = body["suggestion_response"]
        print(f"Suggestion from {sender}: {resp['text']} (postback: {resp['postback_data']})")

def handle_delivery(payload):
    message_id = payload["id"]
    for recipient in payload.get("to", []):
        status = recipient.get("status")
        phone = recipient.get("phone_number")
        print(f"Message {message_id} to {phone}: {status}")

        if status == "delivery_failed":
            # Implement fallback — e.g., send via SMS
            print(f"Delivery failed for {phone}, triggering SMS fallback")

def handle_read_receipt(payload):
    message_id = payload["id"]
    for recipient in payload.get("to", []):
        phone = recipient.get("phone_number")
        print(f"Message {message_id} read by {phone}")
        # Update message status in your database
        # db.messages.update(message_id, read=True, read_at=datetime.utcnow())

if __name__ == "__main__":
    app.run(port=5000)

Node

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/rcs', (req, res) => {
  const event = req.body;
  const eventType = event.data.event_type;
  const payload = event.data.payload;

  switch (eventType) {
    case 'message.received':
      handleInbound(payload);
      break;
    case 'message.sent':
      console.log(`Message ${payload.id} sent`);
      break;
    case 'message.finalized':
      handleDelivery(payload);
      break;
    case 'message.read':
      handleReadReceipt(payload);
      break;
  }

  res.status(200).json({ status: 'ok' });
});

function handleInbound(payload) {
  const body = payload.body;
  const sender = payload.from.phone_number;

  if (body.text) {
    console.log(`Text from ${sender}: ${body.text}`);
  } else if (body.user_file) {
    const file = body.user_file.payload;
    console.log(`File from ${sender}: ${file.file_name} (${file.mime_type})`);
  } else if (body.location) {
    console.log(`Location from ${sender}: ${body.location.latitude}, ${body.location.longitude}`);
  } else if (body.suggestion_response) {
    const resp = body.suggestion_response;
    console.log(`Suggestion from ${sender}: ${resp.text} (postback: ${resp.postback_data})`);
  }
}

function handleDelivery(payload) {
  const messageId = payload.id;
  for (const recipient of payload.to || []) {
    console.log(`Message ${messageId} to ${recipient.phone_number}: ${recipient.status}`);

    if (recipient.status === 'delivery_failed') {
      console.log(`Delivery failed for ${recipient.phone_number}, triggering SMS fallback`);
    }
  }
}

function handleReadReceipt(payload) {
  const messageId = payload.id;
  for (const recipient of payload.to || []) {
    console.log(`Message ${messageId} read by ${recipient.phone_number}`);
    // Update message status in your database
  }
}

app.listen(5000, () => console.log('RCS webhook server running on port 5000'));

Ruby

require "sinatra"
require "json"

set :port, 5000

post "/webhooks/rcs" do
  event = JSON.parse(request.body.read)
  event_type = event.dig("data", "event_type")
  payload = event.dig("data", "payload")

  case event_type
  when "message.received"
    handle_inbound(payload)
  when "message.sent"
    puts "Message #{payload['id']} sent"
  when "message.finalized"
    handle_delivery(payload)
  when "message.read"
    handle_read_receipt(payload)
  end

  { status: "ok" }.to_json
end

def handle_inbound(payload)
  body = payload["body"]
  sender = payload.dig("from", "phone_number")

  if body["text"]
    puts "Text from #{sender}: #{body['text']}"
  elsif body["user_file"]
    file = body.dig("user_file", "payload")
    puts "File from #{sender}: #{file['file_name']} (#{file['mime_type']})"
  elsif body["location"]
    loc = body["location"]
    puts "Location from #{sender}: #{loc['latitude']}, #{loc['longitude']}"
  elsif body["suggestion_response"]
    resp = body["suggestion_response"]
    puts "Suggestion from #{sender}: #{resp['text']} (postback: #{resp['postback_data']})"
  end
end

def handle_delivery(payload)
  payload.fetch("to", []).each do |recipient|
    puts "Message #{payload['id']} to #{recipient['phone_number']}: #{recipient['status']}"
  end
end

def handle_read_receipt(payload)
  payload.fetch("to", []).each do |recipient|
    puts "Message #{payload['id']} read by #{recipient['phone_number']}"
  end
end

Java

import com.sun.net.httpserver.*;
import java.io.*;
import java.net.InetSocketAddress;
import org.json.*;

public class RcsWebhookServer {
    public static void main(String[] args) throws Exception {
        HttpServer server = HttpServer.create(new InetSocketAddress(5000), 0);
        server.createContext("/webhooks/rcs", exchange -> {
            if (!"POST".equals(exchange.getRequestMethod())) {
                exchange.sendResponseHeaders(405, -1);
                return;
            }

            String body = new String(exchange.getRequestBody().readAllBytes());
            JSONObject event = new JSONObject(body);
            String eventType = event.getJSONObject("data").getString("event_type");
            JSONObject payload = event.getJSONObject("data").getJSONObject("payload");

            switch (eventType) {
                case "message.received" -> handleInbound(payload);
                case "message.finalized" -> handleDelivery(payload);
                case "message.read" -> handleReadReceipt(payload);
                default -> System.out.println("Event: " + eventType);
            }

            String response = "{\"status\":\"ok\"}";
            exchange.sendResponseHeaders(200, response.length());
            exchange.getResponseBody().write(response.getBytes());
            exchange.close();
        });
        server.start();
        System.out.println("RCS webhook server running on port 5000");
    }

    static void handleInbound(JSONObject payload) {
        JSONObject body = payload.getJSONObject("body");
        String sender = payload.getJSONObject("from").getString("phone_number");

        if (body.has("text")) {
            System.out.printf("Text from %s: %s%n", sender, body.getString("text"));
        } else if (body.has("suggestion_response")) {
            JSONObject resp = body.getJSONObject("suggestion_response");
            System.out.printf("Suggestion from %s: %s%n", sender, resp.getString("text"));
        }
    }

    static void handleDelivery(JSONObject payload) {
        String msgId = payload.getString("id");
        JSONArray to = payload.getJSONArray("to");
        for (int i = 0; i < to.length(); i++) {
            JSONObject r = to.getJSONObject(i);
            System.out.printf("Message %s to %s: %s%n",
                msgId, r.getString("phone_number"), r.getString("status"));
        }
    }

    static void handleReadReceipt(JSONObject payload) {
        String msgId = payload.getString("id");
        JSONArray to = payload.getJSONArray("to");
        for (int i = 0; i < to.length(); i++) {
            System.out.printf("Message %s read by %s%n",
                msgId, to.getJSONObject(i).getString("phone_number"));
        }
    }
}

.NET

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/webhooks/rcs", async (HttpContext context) =>
{
    var body = await new StreamReader(context.Request.Body).ReadToEndAsync();
    var doc = JsonDocument.Parse(body);
    var data = doc.RootElement.GetProperty("data");
    var eventType = data.GetProperty("event_type").GetString();
    var payload = data.GetProperty("payload");

    switch (eventType)
    {
        case "message.received":
            HandleInbound(payload);
            break;
        case "message.finalized":
            HandleDelivery(payload);
            break;
        case "message.read":
            HandleReadReceipt(payload);
            break;
    }

    return Results.Json(new { status = "ok" });
});

void HandleInbound(JsonElement payload)
{
    var body = payload.GetProperty("body");
    var sender = payload.GetProperty("from").GetProperty("phone_number").GetString();

    if (body.TryGetProperty("text", out var text))
        Console.WriteLine($"Text from {sender}: {text}");
    else if (body.TryGetProperty("suggestion_response", out var suggestion))
        Console.WriteLine($"Suggestion from {sender}: {suggestion.GetProperty("text")}");
    else if (body.TryGetProperty("location", out var location))
        Console.WriteLine($"Location from {sender}: {location.GetProperty("latitude")}, {location.GetProperty("longitude")}");
}

void HandleDelivery(JsonElement payload)
{
    var msgId = payload.GetProperty("id").GetString();
    foreach (var r in payload.GetProperty("to").EnumerateArray())
        Console.WriteLine($"Message {msgId} to {r.GetProperty("phone_number")}: {r.GetProperty("status")}");
}

void HandleReadReceipt(JsonElement payload)
{
    var msgId = payload.GetProperty("id").GetString();
    foreach (var r in payload.GetProperty("to").EnumerateArray())
        Console.WriteLine($"Message {msgId} read by {r.GetProperty("phone_number")}");
}

app.Run("http://0.0.0.0:5000");

PHP

<?php
$payload = file_get_contents('php://input');
$event = json_decode($payload, true);

$eventType = $event['data']['event_type'];
$data = $event['data']['payload'];

switch ($eventType) {
    case 'message.received':
        handleInbound($data);
        break;
    case 'message.finalized':
        handleDelivery($data);
        break;
    case 'message.read':
        handleReadReceipt($data);
        break;
}

http_response_code(200);
echo json_encode(['status' => 'ok']);

function handleInbound(array $payload): void
{
    $body = $payload['body'];
    $sender = $payload['from']['phone_number'];

    if (isset($body['text'])) {
        echo "Text from {$sender}: {$body['text']}\n";
    } elseif (isset($body['user_file'])) {
        $file = $body['user_file']['payload'];
        echo "File from {$sender}: {$file['file_name']} ({$file['mime_type']})\n";
    } elseif (isset($body['location'])) {
        $loc = $body['location'];
        echo "Location from {$sender}: {$loc['latitude']}, {$loc['longitude']}\n";
    } elseif (isset($body['suggestion_response'])) {
        $resp = $body['suggestion_response'];
        echo "Suggestion from {$sender}: {$resp['text']} (postback: {$resp['postback_data']})\n";
    }
}

function handleDelivery(array $payload): void
{
    foreach ($payload['to'] ?? [] as $recipient) {
        echo "Message {$payload['id']} to {$recipient['phone_number']}: {$recipient['status']}\n";
    }
}

function handleReadReceipt(array $payload): void
{
    foreach ($payload['to'] ?? [] as $recipient) {
        echo "Message {$payload['id']} read by {$recipient['phone_number']}\n";
    }
}

package main

import (
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

type WebhookEvent struct {
  Data struct {
    EventType string `json:"event_type"`
    Payload   struct {
      ID   string `json:"id"`
      Body struct {
        Text               string                 `json:"text,omitempty"`
        Location           map[string]float64     `json:"location,omitempty"`
        SuggestionResponse map[string]string      `json:"suggestion_response,omitempty"`
        UserFile           map[string]interface{} `json:"user_file,omitempty"`
      } `json:"body"`
      From struct {
        PhoneNumber string `json:"phone_number"`
        AgentID     string `json:"agent_id"`
      } `json:"from"`
      To []struct {
        PhoneNumber string `json:"phone_number"`
        Status      string `json:"status"`
      } `json:"to"`
    } `json:"payload"`
  } `json:"data"`
}

func main() {
  http.HandleFunc("/webhooks/rcs", func(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    var event WebhookEvent
    json.Unmarshal(body, &event)

    switch event.Data.EventType {
    case "message.received":
      handleInbound(event)
    case "message.finalized":
      handleDelivery(event)
    case "message.read":
      handleReadReceipt(event)
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(200)
    fmt.Fprint(w, `{"status":"ok"}`)
  })

  fmt.Println("RCS webhook server running on port 5000")
  http.ListenAndServe(":5000", nil)
}

func handleInbound(event WebhookEvent) {
  p := event.Data.Payload
  sender := p.From.PhoneNumber

  if p.Body.Text != "" {
    fmt.Printf("Text from %s: %s\n", sender, p.Body.Text)
  } else if p.Body.SuggestionResponse != nil {
    fmt.Printf("Suggestion from %s: %s (postback: %s)\n",
      sender, p.Body.SuggestionResponse["text"], p.Body.SuggestionResponse["postback_data"])
  } else if p.Body.Location != nil {
    fmt.Printf("Location from %s: %f, %f\n",
      sender, p.Body.Location["latitude"], p.Body.Location["longitude"])
  }
}

func handleDelivery(event WebhookEvent) {
  for _, r := range event.Data.Payload.To {
    fmt.Printf("Message %s to %s: %s\n", event.Data.Payload.ID, r.PhoneNumber, r.Status)
  }
}

func handleReadReceipt(event WebhookEvent) {
  for _, r := range event.Data.Payload.To {
    fmt.Printf("Message %s read by %s\n", event.Data.Payload.ID, r.PhoneNumber)
  }
}

Building a unified SMS + RCS webhook handler

If your application handles both SMS/MMS and RCS, you need to normalize the different payload structures:

Python

def normalize_message(event):
    """Normalize SMS/MMS and RCS webhook payloads into a common format."""
    payload = event["data"]["payload"]
    msg_type = payload.get("type", "SMS")

    if msg_type == "RCS":
        # RCS: body is nested object
        body = payload.get("body", {})
        text = body.get("text", "")
        media = []
        if "user_file" in body:
            file_info = body["user_file"]["payload"]
            media.append({
                "url": file_info["file_uri"],
                "content_type": file_info["mime_type"],
                "size": file_info.get("file_size_bytes"),
            })
        sender = payload.get("from", {}).get("phone_number", "")
    else:
        # SMS/MMS: body is flat
        text = payload.get("text", "")
        media = [
            {"url": m["url"], "content_type": m["content_type"]}
            for m in payload.get("media", [])
        ]
        sender = payload.get("from", {}).get("phone_number", "")

    return {
        "id": payload["id"],
        "type": msg_type,
        "sender": sender,
        "text": text,
        "media": media,
        "direction": payload.get("direction"),
    }

Node

function normalizeMessage(event) {
  const payload = event.data.payload;
  const msgType = payload.type || 'SMS';

  if (msgType === 'RCS') {
    const body = payload.body || {};
    const media = [];
    if (body.user_file) {
      const file = body.user_file.payload;
      media.push({
        url: file.file_uri,
        contentType: file.mime_type,
        size: file.file_size_bytes,
      });
    }
    return {
      id: payload.id,
      type: msgType,
      sender: payload.from?.phone_number || '',
      text: body.text || '',
      media,
      direction: payload.direction,
    };
  }

  // SMS/MMS
  return {
    id: payload.id,
    type: msgType,
    sender: payload.from?.phone_number || '',
    text: payload.text || '',
    media: (payload.media || []).map(m => ({
      url: m.url,
      contentType: m.content_type,
    })),
    direction: payload.direction,
  };
}

Webhook IP allowlist

If your server uses a firewall or ACL, allowlist the Telnyx webhook source subnet:

CIDR	Description
`192.76.120.192/27`	Telnyx webhook delivery IPs

Best practices

Process webhooks asynchronously. Acknowledge receipt immediately and handle the event in a background job. If your server doesn’t respond within 2 seconds, Telnyx retries the webhook. The same webhook may be delivered multiple times (up to 3 attempts). Use the event.data.id as a deduplication key to avoid processing the same event twice. Validate the telnyx-signature-ed25519 and telnyx-timestamp headers using your account’s public key. See webhook security for implementation details. When an RCS message fails (delivery_failed status), automatically fall back to SMS to ensure message delivery. Check the to[].status field in message.finalized events. Read receipts provide valuable engagement data but aren’t guaranteed. Don’t make critical business logic dependent on receiving a message.read event — some users disable read receipts.

Next steps

Send rich cards, carousels, and suggested actions via RCS. Check device support and RCS feature availability. Compare with the SMS/MMS webhook handling guide. Set up your RCS Agent and start messaging.

Quickstart

Source: https://developers.telnyx.com/docs/messaging/whatsapp/quickstart.md

Send Your First WhatsApp Message

Get started with WhatsApp Business messaging via Telnyx in minutes. This guide covers account setup, template creation, and sending your first message with delivery confirmation.

Prerequisites

Before sending WhatsApp messages, ensure you have:

Telnyx Account — Sign up and verify your account
Meta Business Manager Account — Required for WhatsApp Business Platform access
WhatsApp Business Account (WABA) — Connected via Telnyx’s Embedded Signup
Verified phone number — Added to your WABA and verified with Meta

WhatsApp Business Platform requires business verification through Meta’s process. Personal WhatsApp accounts cannot send template messages via the API.

Create a Telnyx account and verify your email
Navigate to the Portal and complete account verification
Add billing information to enable message sending
Generate an API key from Developer Center → API Keys → Create API Key

Store your API key securely — you’ll need it for all API requests. Complete the WhatsApp Embedded Signup to connect your Meta Business Manager:

Navigate to Messaging → WhatsApp in the Telnyx Portal
Click Connect WhatsApp Business Account
Sign in with your Facebook Business Manager credentials
Select the Business Manager account to connect
Follow Meta’s prompts to create or select a WhatsApp Business Account
Verify your business phone number when prompted

Use a Telnyx number with an active messaging profile that you haven’t used with personal WhatsApp. The embedded signup flow currently requires Telnyx-owned numbers — bring-your-own-number is not yet supported through the portal. If you’re registering a landline number, choose phone call verification instead of SMS when prompted. SMS delivery to landline numbers can be unreliable — call verification is more consistent. WhatsApp requires pre-approved templates for outbound marketing and notifications: Set a display name for the phone number before submitting templates. Templates submitted from numbers without an approved display name are rejected by Meta. When a template contains parameters (e.g., \{\{1\}\}), provide sample values in the example field. Meta reviewers use these to evaluate the template. Without sample values, templates are typically rejected. Complete the business profile (website, description, industry category) before submitting templates. Incomplete profiles increase rejection rates, especially for new WhatsApp Business Accounts. Create a message template using the API:

cURL

curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "category": "MARKETING",
    "language": "en_US",
    "waba_id": "YOUR_WABA_ID",
    "components": [
      {
        "type": "BODY",
        "text": "Hello {{1}}! Welcome to our WhatsApp updates.",
        "example": {
          "body_text": [["John"]]
        }
      }
    ]
  }'

JavaScript

import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const template = await client.whatsapp.templates.create({
  name: 'welcome_message',
  category: 'MARKETING',
  language: 'en_US',
  waba_id: 'YOUR_WABA_ID',
  components: [
    {
      type: 'BODY',
      text: 'Hello {{1}}! Welcome to our WhatsApp updates.',
      example: {
        body_text: [['John']]
      }
    }
  ]
});

Python

from telnyx import Telnyx
client = Telnyx(api_key='YOUR_API_KEY')

template = client.whatsapp.templates.create(
    name='welcome_message',
    category='MARKETING',
    language='en_US',
    waba_id='YOUR_WABA_ID',
    components=[
        {
            'type': 'BODY',
            'text': 'Hello {{1}}! Welcome to our WhatsApp updates.',
            'example': {
                'body_text': [['John']]
            }
        }
    ]
)

Ruby

require 'telnyx'

telnyx.whatsapp.templates.create(
  name: 'welcome_message',
  category: 'MARKETING',
  language: 'en_US',
  waba_id: 'YOUR_WABA_ID',
  components: [
    {
      type: 'BODY',
      text: 'Hello {{1}}! Welcome to our WhatsApp updates.',
      example: {
        body_text: [['John']]
      }
    }
  ]
)

Meta typically reviews templates within 24-48 hours. You’ll receive an email when approved. Start with simple templates for faster approval. Avoid promotional language or special characters in your first template. Once your template is approved, send your first message:

cURL

curl -X POST "https://api.telnyx.com/v2/messages/whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15557654321",
    "whatsapp_message": {
      "type": "template",
      "template": {
        "name": "welcome_message",
        "language": {
          "policy": "deterministic",
          "code": "en_US"
        },
        "components": [
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "John"
              }
            ]
          }
        ]
      }
    }
  }'

Python

from telnyx import Telnyx
client = Telnyx(api_key='YOUR_API_KEY')

response = client.messages.send_whatsapp(
    from_="+15551234567",
    to="+15557654321",
    whatsapp_message={
        "type": "template",
        "template": {
            "name": "welcome_message",
            "language": {
                "policy": "deterministic",
                "code": "en_US"
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "John"
                        }
                    ]
                }
            ]
        }
    }
)

print(f"Message ID: {response.data.id}")
print(f"Status: {response.data.to[0].status}")

Node.js

import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const message = await client.messages.sendWhatsapp({
  from: '+15551234567',
  to: '+15557654321',
  whatsapp_message: {
    type: 'template',
    template: {
      name: 'welcome_message',
      language: {
        policy: 'deterministic',
        code: 'en_US'
      },
      components: [
        {
          type: 'body',
          parameters: [
            {
              type: 'text',
              text: 'John'
            }
          ]
        }
      ]
    }
  }
});

console.log(`Message ID: ${message.data.id}`);
console.log(`Status: ${message.data.to[0].status}`);

Ruby

require 'telnyx'

response = telnyx.messages.send_whatsapp(
  from: '+15551234567',
  to: '+15557654321',
  whatsapp_message: {
    type: 'template',
    template: {
      name: 'welcome_message',
      language: {
        policy: 'deterministic',
        code: 'en_US'
      },
      components: [
        {
          type: 'body',
          parameters: [
            {
              type: 'text',
              text: 'John'
            }
          ]
        }
      ]
    }
  }
)

puts "Message ID: #{response.data.id}"
puts "Status: #{response.data.to[0].status}"

package main

import (
    "context"
    "fmt"
    "github.com/team-telnyx/telnyx-go/v2"
)

func main() {
    client := telnyx.NewAPIClient(telnyx.NewConfiguration())
    client.GetConfig().AddDefaultHeader("Authorization", "Bearer YOUR_API_KEY")

    parameters := []telnyx.TemplateParameter{
        {
            Type: telnyx.PtrString("text"),
            Text: telnyx.PtrString("John"),
        },
    }

    components := []telnyx.TemplateComponent{
        {
            Type:       telnyx.PtrString("body"),
            Parameters: parameters,
        },
    }

    template := telnyx.WhatsAppTemplate{
        Name: telnyx.PtrString("welcome_message"),
        Language: &telnyx.TemplateLanguage{
            Policy: telnyx.PtrString("deterministic"),
            Code:   telnyx.PtrString("en_US"),
        },
        Components: components,
    }

    whatsappMessage := telnyx.WhatsAppMessageContent{
        Type:     telnyx.PtrString("template"),
        Template: &template,
    }

    params := telnyx.MessageSendWhatsappParams{
        From:            "+15551234567",
        To:              "+15557654321",
        WhatsappMessage: whatsappMessage,
    }

    response, err := client.Messages.SendWhatsapp(context.TODO(), params)

    if err != nil {
        panic(err)
    }

    fmt.Printf("Message ID: %s\n", response.Data.Id)
    fmt.Printf("Status: %s\n", response.Data.To[0].Status)
}

Java

import com.telnyx.sdk.ApiClient;
import com.telnyx.sdk.ApiException;
import com.telnyx.sdk.Configuration;
import com.telnyx.sdk.auth.HttpBearerAuth;
import com.telnyx.sdk.api.MessagesApi;
import com.telnyx.sdk.model.*;
import java.util.Arrays;

public class WhatsAppQuickstart {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        HttpBearerAuth bearerAuth = (HttpBearerAuth) defaultClient.getAuthentication("bearerAuth");
        bearerAuth.setBearerToken("YOUR_API_KEY");

        MessagesApi apiInstance = new MessagesApi(defaultClient);

        TemplateParameter parameter = new TemplateParameter()
            .type("text")
            .text("John");

        TemplateComponent component = new TemplateComponent()
            .type("body")
            .parameters(Arrays.asList(parameter));

        TemplateLanguage language = new TemplateLanguage()
            .policy("deterministic")
            .code("en_US");

        WhatsAppTemplate template = new WhatsAppTemplate()
            .name("welcome_message")
            .language(language)
            .components(Arrays.asList(component));

        WhatsAppMessageContent whatsappMessage = new WhatsAppMessageContent()
            .type("template")
            .template(template);

        MessageSendWhatsappRequest request = new MessageSendWhatsappRequest()
            .from("+15551234567")
            .to("+15557654321")
            .whatsappMessage(whatsappMessage);

        try {
            var result = apiInstance.sendWhatsapp(request);
            System.out.println("Message ID: " + result.getData().getId());
            System.out.println("Status: " + result.getData().getTo().get(0).getStatus());
        } catch (ApiException e) {
            System.err.println("Exception: " + e.getResponseBody());
        }
    }
}

The messaging profile is automatically resolved from your WhatsApp-enabled phone number specified in the from field. Configure webhooks to receive real-time delivery status updates:

In the Telnyx Portal, navigate to Messaging → Messaging Profiles
Select your messaging profile
Set Webhook URL to your endpoint (e.g., https://yourapp.com/webhooks/telnyx)
Enable Failover URL for redundancy (optional)
Save the configuration

Your webhook endpoint will receive delivery reports and inbound message notifications.

{
  "data": {
    "event_type": "message.sent",
    "id": "msg_123abc",
    "occurred_at": "2023-01-01T12:00:00.000Z",
    "payload": {
      "id": "msg_123abc",
      "type": "whatsapp",
      "to": "+15557654321",
      "from": "+15551234567",
      "text": "Hello John! Welcome to our WhatsApp updates.",
      "direction": "outbound",
      "parts": 1,
      "tags": [],
      "messaging_profile_id": "your_messaging_profile_id",
      "billing_type": "whatsapp_marketing",
      "valid_until": "2023-01-01T12:30:00.000Z"
    }
  }
}

Implement webhook handling to track message status and respond to inbound messages:

Python

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhooks/telnyx', methods=['POST'])
def handle_webhook():
    webhook_data = request.json
    event_type = webhook_data['data']['event_type']
    payload = webhook_data['data']['payload']

    if event_type == 'message.sent':
        print(f"WhatsApp message sent: {payload['id']}")
        print(f"Status: {payload.get('to', [{}])[0].get('status', 'unknown')}")

    elif event_type == 'message.received':
        print(f"WhatsApp message received: {payload['text']}")
        print(f"From: {payload['from']}")

        # Auto-reply during 24-hour window
        reply_to_customer(payload['from'], payload['to'])

    return '', 200

def reply_to_customer(customer_number, business_number):
    from telnyx import Telnyx
    client = Telnyx(api_key="YOUR_API_KEY")

    # Send free-form message (no template required in 24hr window)
    client.messages.send_whatsapp(
        from_=business_number,
        to=customer_number,
        whatsapp_message={
            "type": "text",
            "text": {
                "body": "Thanks for your message! We'll get back to you soon.",
                "preview_url": False
            }
        }
    )

if __name__ == '__main__':
    app.run(debug=True)

Node.js

const express = require('express');
import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const app = express();
app.use(express.json());

app.post('/webhooks/telnyx', async (req, res) => {
  const { data } = req.body;
  const { event_type, payload } = data;

  if (event_type === 'message.sent') {
    console.log(`WhatsApp message sent: ${payload.id}`);
    console.log(`Status: ${payload.to[0]?.status || 'unknown'}`);

  } else if (event_type === 'message.received') {
    console.log(`WhatsApp message received: ${payload.text}`);
    console.log(`From: ${payload.from}`);

    // Auto-reply during 24-hour window
    await replyToCustomer(payload.from, payload.to);
  }

  res.status(200).send();
});

async function replyToCustomer(customerNumber, businessNumber) {
  try {
    await client.messages.sendWhatsapp({
      from: businessNumber,
      to: customerNumber,
      whatsapp_message: {
        type: 'text',
        text: {
          body: "Thanks for your message! We'll get back to you soon.",
          preview_url: false
        }
      }
    });
  } catch (error) {
    console.error('Error sending reply:', error);
  }
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Verify Message Delivery

Check message delivery through multiple channels:

Portal Dashboard

Navigate to Messaging → Message Logs in the Telnyx Portal
Filter by Channel: WhatsApp and Date Range
View delivery status, timestamps, and any error codes
Click individual messages for detailed delivery information

Webhook Events

Monitor these key webhook events:

message.sent — Message successfully submitted to WhatsApp
message.delivered — Message delivered to recipient’s device
message.read — Recipient opened and read the message (when enabled by recipient)
message.failed — Message delivery failed (with error details)

API Response

The initial API response includes:

{
  "data": {
    "id": "msg_123abc",
    "to": [
      {
        "phone_number": "+15557654321",
        "status": "queued",
        "carrier": "WhatsApp"
      }
    ]
  }
}

Common Issues

Symptoms: API returns a 40008 error indicating the template was not found or not approved Solutions:

Verify template status in Portal under Messaging → WhatsApp → Send Messages
Ensure template name matches exactly (case-sensitive)
Wait for Meta’s approval (typically 24-48 hours for first templates)
Review Meta’s template guidelines for approval requirements

Symptoms: API returns a 40008 error indicating the sender phone number is not registered with WhatsApp Solutions:

Complete phone number verification in the Telnyx Portal
Ensure number is added to your WhatsApp Business Account
Verify the number through Meta’s verification process
Check that the number hasn’t been used with personal WhatsApp

Symptoms: Free-form (session) message fails with a 40008 error. WhatsApp requires a template to initiate conversations outside the 24-hour window Solutions:

Use approved message templates for outbound messaging
Only send free-form messages within 24 hours of customer’s last message
Check conversation window status via webhook events
Consider switching to template-based messaging for customer re-engagement

Symptoms: Message status webhook returns undeliverable with Meta API error details in the response Solutions:

Verify recipient has WhatsApp installed and active
Ensure phone number format includes country code (+1…)
Check that recipient hasn’t blocked your business number
Confirm recipient’s WhatsApp account is not banned or restricted

Next Steps

Send templates, text, media, and interactive messages Set up your WhatsApp Business Account and verify your number Handle inbound messages and delivery status callbacks

Source: https://developers.telnyx.com/docs/messaging/whatsapp/embedded-signup.md

WhatsApp Embedded Signup enables businesses to connect their Facebook Business Manager account to Telnyx and provision WhatsApp Business Account (WABA) resources through a streamlined browser-based workflow.

Prerequisites

Before starting the embedded signup process: Required account status:

Active Telnyx account with messaging enabled
Valid payment method configured
Account in good standing with no billing issues

Portal access:

Log in to Telnyx Portal
Navigate to Messaging → WhatsApp
Ensure you have admin permissions for your organization

Business Manager requirements:

Facebook Business Manager account (business.facebook.com)
Admin access to the Business Manager account
Business verification completed (recommended for production use)

Important limitations:

Each phone number can only be associated with one Business Manager
Business Manager must have appropriate permissions for WhatsApp Business API
Account must comply with Facebook Business policies

Ensure your Facebook Business Manager is fully set up and verified before starting embedded signup. Incomplete Business Manager setup can cause signup failures that require manual intervention. The embedded signup process follows a multi-step finite state machine (FSM) that progresses through these states: Each state represents a checkpoint in the signup process with specific completion criteria and potential failure points. From Telnyx Portal:

Navigate to Messaging → WhatsApp → Getting Started
Click Connect WhatsApp Business
Review the permissions and requirements displayed
Click Begin Setup to start the embedded signup flow

What happens:

Telnyx creates a signup session with state initiated
Portal generates a secure OAuth URL for Facebook authorization
Session tracking begins for completion monitoring

Verification: Signup session monitoring is handled automatically by the portal. API-based signup tracking may not be available in all configurations.

# Check signup session status via API
curl -X GET "https://api.telnyx.com/v2/whatsapp/signup/{signup_id}/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "id": "signup_123abc",
    "state": "initiated",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Facebook authorization flow:

Browser redirects to Facebook Business Manager OAuth consent screen
Review the requested permissions:
- WhatsApp Business Management — Create and manage WABA
- Business Asset Management — Associate phone numbers and templates
- Webhook Management — Configure message and status webhooks
Click Continue to grant permissions
Select target Business Manager if you have multiple

What happens:

Facebook validates your Business Manager admin status
OAuth token is generated and securely transmitted to Telnyx
Signup state advances to facebook_auth

Common issues:

Permission denied: Ensure you have admin access to Business Manager
Business not verified: Some features require verified Business Manager
Already connected: Phone number may be connected to another provider

Verification: The Portal will show “Connected to Facebook” with Business Manager details when successful. WABA provisioning: Telnyx automatically creates your WhatsApp Business Account using the connected Business Manager:

WABA is created under your Business Manager
Telnyx is granted the necessary permissions as a solution partner
Initial configuration is applied (timezone, business category)
Webhook endpoints are pre-configured for Telnyx integration

What happens:

Facebook creates the WABA resource
Telnyx receives WABA credentials and configuration details
Signup state advances to waba_created
WABA settings are synced to Telnyx systems

WABA configuration:

Business category: Inherited from Business Manager
Webhooks: Configured via your messaging profile webhook settings

Verification:

# List WABAs for your account
curl -X GET "https://api.telnyx.com/v2/whatsapp/business_accounts" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "waba_456def",
      "name": "Your Business Name",
      "status": "APPROVED",
      "waba_id": "2019979452207634"
    }
  ]
}

Number selection and registration:

Portal displays available phone numbers from your Telnyx inventory
Select the phone number to register for WhatsApp
Choose the WABA to associate with the number
Confirm the registration request

Phone number requirements:

Must be a Telnyx number with an active messaging profile assigned
Cannot be currently registered with another WhatsApp provider
Can be used alongside SMS/voice on the same number — WhatsApp uses a separate API path

The embedded signup flow currently requires a Telnyx-owned number with a messaging profile. Bring-your-own-number (non-Telnyx numbers) is not yet supported through the portal signup flow. If you need to register an external number, contact support for assistance. What happens:

Phone number is submitted to Facebook for WhatsApp registration
Facebook begins the verification process
Signup state advances to phone_registered
Number status changes to “pending verification”

Registration details:

Number format: E.164 format (+1234567890)
Verification method: Automatically determined by Facebook
Processing time: Usually 1-5 minutes for verification

Verification:

# Check phone number registration status
curl -X GET "https://api.telnyx.com/v2/whatsapp/phone_numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "phone_number": "+15551234567",
      "business_account_id": "waba_456def",
      "status": "pending_verification",
      "registered_at": "2024-01-15T11:15:00Z"
    }
  ]
}

Facebook verification process: Facebook automatically verifies phone numbers using multiple methods:

Carrier validation: Facebook verifies number ownership with telecom provider
SMS verification: Test SMS may be sent to validate delivery capability
API validation: Facebook tests webhook delivery and response handling

Verification timeline:

Typical duration: 1-15 minutes
Complex cases: Up to 24 hours for carrier validation
Failed attempts: May require manual review or different number

What happens:

Facebook completes all verification checks
Number status updates to “verified” in Facebook systems
Signup state advances to verified
Number becomes available for sending messages

Verification methods Facebook may use: Automated voice call to verify number is operational and accessible. Duration: 30 seconds Requirements: Number must accept incoming calls Test SMS sent to verify message delivery capability. Message: “Facebook verification code: [CODE]” Requirements: Number must receive SMS messages Direct verification with mobile carrier for number ownership. Duration: Instant to 24 hours Requirements: Carrier must support Facebook verification API Verification completion:

# Final verification status
curl -X GET "https://api.telnyx.com/v2/whatsapp/phone_numbers/+15551234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "phone_number": "+15551234567",
    "business_account_id": "waba_456def",
    "status": "verified",
    "verified_at": "2024-01-15T11:20:00Z",
    "enabled": true,
    "calling_enabled": false
  }
}

When verification succeeds, your WhatsApp integration is ready:

Account Status

WABA Status: Active and ready for messaging
Phone Number: Verified and enabled for sending/receiving
Webhooks: Configured and receiving events
Templates: Ready for submission and approval

Send templates, text, media, and interactive messages Send your first WhatsApp message end-to-end Handle inbound messages and delivery status callbacks

Troubleshooting Common Issues

Error: “You don’t have permission to complete this action” Causes:

Not admin of Business Manager account
Business Manager doesn’t have WhatsApp permissions
Account suspended or restricted

Solutions:

Verify admin access in Business Manager
Contact Facebook Business Support if account restricted
Use different Business Manager account
Check account verification status

Error: “Unable to create WhatsApp Business Account” Causes:

Business Manager doesn’t meet Facebook requirements
Too many existing WABAs on Business Manager
Business policy violations

Solutions:

Complete Business Manager verification
Review and resolve any policy violations
Remove unused WABAs from Business Manager
Contact Telnyx support with signup session ID

Error: “This phone number is already connected to WhatsApp Business API” Causes:

Number registered with another Business Service Provider
Number previously registered but not properly disconnected
Number registered to different WABA

Solutions:

Disconnect number from previous provider
Contact previous provider to release number
Use different phone number for registration
Contact Facebook Business Support for assistance

Error: “Phone number verification failed” or timeout Causes:

Number doesn’t support voice calls or SMS
Carrier blocking verification attempts
Number routing issues

Solutions:

Verify number accepts incoming calls and SMS
Try different phone number if possible
Contact carrier to check for blocks
Wait and retry verification process
Contact Telnyx support with verification details

Error: Webhooks not receiving events after successful signup Causes:

Webhook URL not properly configured
Firewall blocking webhook delivery
Invalid webhook signature verification

Solutions:

Verify webhook URL accessibility from Facebook servers
Check webhook signature verification implementation
Review webhook configuration in Portal
Test webhook endpoint with manual POST requests
Check logs for delivery attempts and errors

Symptom: Embedded signup popup fails to load, shows a blank page, or gets stuck during the Facebook OAuth step. Causes:

Ad blockers (uBlock Origin, Adblock Plus, etc.) blocking Facebook/Meta domains
Privacy extensions (Privacy Badger, Ghostery) blocking third-party scripts
Browser security settings blocking cross-origin popups

Solutions:

Temporarily disable ad blockers and privacy extensions for the signup flow
Add facebook.com and meta.com domains to your extension’s allowlist
Try using a different browser profile without extensions
Use Chrome Incognito mode (extensions are typically disabled by default)
Ensure popup blockers allow popups from the Telnyx Portal domain

Note: The WhatsApp embedded signup flow is powered by Meta/Facebook. The OAuth consent screen and business verification steps are hosted on Facebook’s servers, which means browser extensions that block Facebook domains will prevent the signup from completing.

API Integration

Monitor signup progress programmatically using the Signup API:

cURL

curl -X GET "https://api.telnyx.com/v2/whatsapp/signup/{signup_id}/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Events

Receive real-time signup progress updates:

{
  "data": {
    "event_type": "whatsapp.signup.state_updated",
    "payload": {
      "signup_id": "signup_123abc",
      "state": "verified",
      "previous_state": "phone_registered",
      "waba_id": "waba_456def",
      "phone_number": "+15551234567",
      "occurred_at": "2024-01-15T11:20:00Z"
    }
  }
}

Source: https://developers.telnyx.com/docs/messaging/whatsapp/embedded-signup/tech-provider.md

WhatsApp Tech Provider Embedded Signup lets ISVs and SaaS platforms embed Meta’s WhatsApp onboarding flow directly into their own portal. Your end-customers can create and register a WhatsApp Business Account (WABA), claim a phone number, and begin messaging — all without leaving your application. Unlike the standard embedded signup flow, which is designed for direct Telnyx customers, the Tech Provider flow is built for partners who manage multiple end-customers and need programmatic control over WABA provisioning.

Overview

As a Tech Provider, you build the onboarding experience into your own product. The end-customer clicks a button in your portal, completes Meta’s embedded signup flow, and your backend receives the resulting WABA ID and phone number ID. You then register the WABA with Telnyx so that it can use Telnyx’s messaging infrastructure. Telnyx offers two integration paths: a hosted signup option where Telnyx manages the entire signup UI and backend processing (recommended for most Tech Providers), and a custom integration option where you embed Meta’s Facebook SDK directly into your own portal for full control over the experience. See Step 3 for a comparison.

Tech Provider vs. Direct Customer

	Tech Provider	Direct Customer
Who uses this?	ISVs, SaaS platforms, resellers	Individual businesses
Onboarding	Embedded in your portal	Via Telnyx portal or API
WABA ownership	Your end-customers own their WABAs	You own your WABA
API calls	You call Telnyx on behalf of customers	You call Telnyx directly
Scale	Many WABAs under one integration	One WABA per integration

Prerequisites

Before you begin, make sure you have:

A Meta Business Account with admin access
A Meta Tech Provider App that has been approved by Meta with the following permissions:
- whatsapp_business_messaging
- whatsapp_business_management
The Tech Provider onboarding process completed in Meta App Dashboard
A Telnyx account with an API key

All links to Meta documentation in this guide require that you are logged in to a Meta Business account. If you don’t have one, create one at business.facebook.com before proceeding.

Step 1: Create and configure your Meta Tech Provider App

Go to Meta App Dashboard and create a new app. Select Business as the app type. In your app’s dashboard, add the WhatsApp product. This will generate the permissions you need. Under App Review > Permissions and Features, request the following permissions:

Permission	Purpose
`whatsapp_business_messaging`	Send and receive WhatsApp messages on behalf of your customers
`whatsapp_business_management`	Manage WhatsApp Business Accounts and phone numbers

Both permissions require Advanced Access for production use. Follow Meta’s Tech Provider onboarding guide to complete the Tech Provider registration process. This includes business verification and agreeing to Meta’s Tech Provider terms. Submit your app for Meta’s App Review. Meta will evaluate your use case and grant (or deny) the requested permissions. This process typically takes several business days. While waiting for App Review approval, you can test in Development Mode with your own test users. Production use requires Live Mode and Advanced Access permissions.

Step 2: Link your Meta App to Telnyx

Once your Meta App is configured, you need to link it to Telnyx so that WABAs created through your embedded signup flow are registered on Telnyx’s infrastructure. In the Meta App Dashboard, change your app mode from Development to Live. This is required for Telnyx to initiate the partner invitation. Reach out to your Telnyx representative or contact support and provide:

Your Meta App ID (found in your app’s dashboard)
Your business name as registered with Meta Within 1–2 business days, you’ll receive an email from Meta containing a partner invitation link. Click the link and accept the invitation to link your app with Telnyx. After accepting the invitation, you can switch your app back to Development mode for testing. The link persists regardless of the app mode.

You must switch your app to Live mode before Telnyx can send the partner invitation. The invitation will fail if your app is in Development mode. After accepting the invite, you can switch back to Development mode for testing.

Step 3: Choose your integration path

After your Meta App is linked to Telnyx, you have two ways to onboard your end-customers’ WABAs. Both paths complete the same Meta embedded signup — the difference is where the signup UI lives and how much you build.

	Option A: Hosted signup (recommended)	Option B: Custom integration
Who it’s for	Most Tech Providers — fastest to ship	ISVs who want full control over the UX
What you build	One API call to generate a shareable URL	Facebook SDK integration in your own frontend
Signup UI	Telnyx-hosted page at `acct.fyi`	Embedded directly in your portal
End-customer experience	Clicks a link → completes Meta signup → done	Clicks a button in your app → Meta popup → you handle the response
Backend code exchange	Telnyx handles it automatically	You exchange the code with Meta’s Graph API
WABA registration	Telnyx handles it automatically	You call Telnyx’s registration API

With the hosted signup flow, Telnyx hosts the embedded signup page. You generate a time-limited onboarding URL via API and share it with your end-customer. The customer visits the URL, completes Meta’s signup, and Telnyx handles the rest — code exchange, webhook subscription, credit line sharing, and phone number registration. No Facebook SDK, no custom JavaScript.

Step 3A.1: Generate an onboarding URL

Call the Telnyx API to create a JWT-authenticated onboarding URL for your end-customer. The URL is valid for up to 3 days.

curl -X POST https://api.telnyx.com/v2/whatsapp/hosted_signups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "app_id": "123456789012345"
  }'

Request body parameters

Parameter	Type	Required	Description
`app_id`	string	Yes	Your Meta App ID (the same one linked to Telnyx in Step 2)
`expires_at`	string (RFC 3339)	No	When the URL expires. Must be at most 3 days in the future. Defaults to 24 hours.

This endpoint requires authentication with a Telnyx API key. You can create one in the API Keys page.

Response

{
  "data": {
    "id": "0192345a-7b8c-7d9e-0f12-3456789abcde",
    "record_type": "whatsapp_jwt",
    "app_id": "123456789012345",
    "created_at": "2026-07-08T12:00:00Z",
    "expires_at": "2026-07-09T12:00:00Z",
    "jwt": "eyJhbGciOiJSUzI1NiIs...",
    "url": "https://acct.fyi?token=eyJhbGciOiJSUzI1NiIs..."
  }
}

Field	Description
`url`	The hosted onboarding URL to share with your end-customer
`jwt`	The raw JWT token (also embedded in the URL)
`expires_at`	When the URL expires (max 3 days)
`id`	Unique identifier for this signup session

Send the url to your end-customer via email, SMS, or embed it as a link in your own portal. When the customer visits the URL:

Telnyx validates the JWT and renders a signup page branded with your app’s Meta configuration
The customer clicks Get Started to launch Meta’s embedded signup popup
The customer signs in to Facebook, creates or selects a WABA, and verifies their phone number
On completion, Telnyx automatically handles the backend: code exchange, webhook subscription, credit line sharing, and phone number registration

You can poll the signup status via GET /v2/whatsapp/signup/{session_id}/status to track progress and surface it in your own dashboard.

curl -X GET "https://api.telnyx.com/v2/whatsapp/signup/019f4253-e09a-7622-bc6f-625378711d78/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the signup session record with status, state, waba_id, and any errors. Use this to build a progress indicator in your portal or trigger downstream workflows when onboarding completes. When the end-customer completes the hosted signup:

Credit line is applied — The WABA is associated with your Telnyx billing account
WABA is registered — The WhatsApp Business Account is linked to Telnyx’s messaging infrastructure
Webhooks are subscribed — Telnyx subscribes to Meta webhook events on the WABA’s behalf
Number is ready for messaging — The phone number can send and receive WhatsApp messages through Telnyx

If you prefer to embed Meta’s signup flow directly into your own portal and handle the code exchange yourself, follow the steps below. This gives you full control over the UX but requires integrating the Facebook JavaScript SDK and calling Meta’s Graph API. Meta’s embedded signup flow is triggered from your web application using the Facebook JavaScript SDK. Your frontend launches the signup dialog, the end-customer completes it, and you receive the resulting credentials. Add the Facebook SDK to your web application:

  window.fbAsyncInit = function () {
    FB.init({
      appId: 'YOUR_APP_ID',
      autoLogAppEvents: true,
      xfbml: true,
      version: 'v19.0',
    });
  };

Call FB.login() with the config_id of your WhatsApp Business Configuration. This opens Meta’s embedded signup dialog for your end-customer.

function launchWhatsAppSignup() {
  // The response_type must include 'code' and 'setup_token'
  FB.login(
    function (response) {
      if (response.authResponse) {
        const code = response.authResponse.code;
        // Send the code to your backend to exchange for credentials
        sendCodeToBackend(code);
      } else {
        console.error('User cancelled login or did not fully authorize.');
      }
    },
    {
      config_id: 'YOUR_CONFIG_ID',
      response_type: 'code',
      override_default_response_type: true,
      extras: {
        setup: {},
        featureType: '',
        sessionInfoVersion: '3',
      },
    }
  );
}

After the user completes the signup, Meta returns an authorization code. Exchange this code using Meta’s API to obtain the WABA ID and phone number ID.

curl -X GET \
  "https://graph.facebook.com/v19.0/oauth/access_token?\
client_id=YOUR_APP_ID\
&client_secret=YOUR_APP_SECRET\
&code=AUTHORIZATION_CODE"

The response contains access token information. Use this access token to retrieve the WABA ID and phone number ID from the signed request or the response payload:

{
  "access_token": "EAAJc...",
  "token_type": "bearer",
  "expires_in": 5183814
}

From the embedded signup response, extract the two critical identifiers:

Field	Description
`waba_id`	The WhatsApp Business Account ID (e.g., `123456789012345`)
`phone_number_id`	The phone number ID within that WABA (e.g., `987654321098765`)

Refer to Meta’s embedded signup documentation for full details on parsing the response. You only need the frontend (web) portion of Meta’s guide — the backend registration is handled by Telnyx in the next step.

Step 3B.2: Register the WABA with Telnyx

Once you have the waba_id and phone_number_id from the embedded signup flow, send them to Telnyx to register the WABA and activate messaging.

Request

curl -X POST https://api.telnyx.com/v2/whatsapp/business_accounts/tech_provider \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "waba_id": "123456789012345",
    "phone_number_id": "987654321098765",
    "app_id": "123456789012345",
    "customer_id": "acme-corp-42"
  }'

Request body parameters

Parameter	Type	Required	Description
`waba_id`	string	Yes	The WABA ID returned by Meta’s embedded signup flow
`phone_number_id`	string	Yes	The phone number ID returned by Meta’s embedded signup flow
`app_id`	string	Yes	Your Meta App ID
`customer_id`	string	No	An optional identifier you assign to track this customer (e.g., your internal customer ID)

This endpoint requires authentication with a Telnyx API key via the Authorization: Bearer header. Use an API key from your Telnyx account — you can create one in the API Keys page.

Response

A successful response confirms that the WABA has been registered with Telnyx:

{
  "data": {
    "waba_id": "123456789012345",
    "phone_number_id": "987654321098765",
    "status": "registered",
    "customer_id": "acme-corp-42"
  }
}

What happens after registration

When the Telnyx API returns a successful response:

Credit line is applied — The WABA is associated with your Telnyx billing account
WABA is registered — The WhatsApp Business Account is linked to Telnyx’s messaging infrastructure
Number is ready for messaging — The phone number can send and receive WhatsApp messages through Telnyx

Troubleshooting

Verify that your app was in Live mode when you contacted Telnyx
Check your spam and junk folders
Ensure the email associated with your Meta Business account is correct
Confirm with your Telnyx representative that they initiated the invitation
The invitation typically arrives within 1–2 business days
Review Meta’s rejection reasons carefully in the App Review section of your dashboard
Common reasons include: insufficient permissions justification, unclear use case description, or missing screencast
Update your submission with clearer documentation and resubmit
Ensure your app is functional and testable during the review period
Confirm the Facebook SDK is loaded before calling FB.login()
Check that your config_id is correct and matches a WhatsApp Business Configuration in your app
Ensure your app has the whatsapp_business_messaging and whatsapp_business_management permissions
Open your browser’s developer console for error messages from the SDK
Verify you are using a valid Telnyx API key
Ensure the Authorization: Bearer YOUR_API_KEY header is included in your request
Check that your API key has not expired or been revoked
Ensure the response_type parameter includes code
Check that override_default_response_type is set to true
Verify the user completed all steps in the Meta signup flow (business verification, phone number selection)
Inspect the full response object in your FB.login() callback for debug information
Ensure you’re using the full URL returned by POST /v2/whatsapp_hosted_signups, including the ?token= query parameter
Check that the JWT hasn’t expired — tokens are valid for a maximum of 3 days from creation
If the token has expired, generate a new one via the API
Verify the phone number entered by the end-customer is correct and can receive SMS
Check that the phone number is not already registered with another WhatsApp account
Try requesting the verification code via phone call instead of SMS
Ensure the end-customer’s phone carrier is not blocking Meta’s verification messages

Next steps

Send your first WhatsApp message with Telnyx Direct customer embedded signup flow Explore WhatsApp API endpoints Send messages across all channels

Send Messages

Source: https://developers.telnyx.com/docs/messaging/whatsapp/send-messages.md

Send WhatsApp messages using POST /v2/messages/whatsapp. All message types use the same endpoint — the whatsapp_message object determines the message type.

POST https://api.telnyx.com/v2/messages/whatsapp

Request Structure

Every request requires these fields:

Field	Type	Required	Description
`from`	string	Yes	Your WhatsApp-enabled phone number (E.164)
`to`	string	Yes	Recipient phone number (E.164)
`whatsapp_message`	object	Yes	Message content — structure varies by type
`webhook_url`	string	No	URL for delivery status callbacks

The messaging profile is automatically resolved from the from number. You do not need to pass messaging_profile_id. The whatsapp_message object must include a type field and the corresponding content object. Supported types: text, template, image, video, document, audio, sticker, location, contacts, interactive, reaction.

Template Messages

Template messages are required to start conversations outside the 24-hour window. Templates must be pre-approved by Meta. Error code 40008 indicates the template could not be used for sending. Possible causes include: the template is still pending review, was rejected by Meta, has been paused due to quality issues, or was disabled. Check template status in the Telnyx Portal or via GET /v2/whatsapp/message_templates. Text, media, and interactive messages can only be sent within a 24-hour conversation window. The window opens when the recipient sends a message to the business number. Outside this window, use an approved template message to initiate the conversation. For comprehensive template creation guidance, see the Manage Templates guide.

cURL

curl -X POST https://api.telnyx.com/v2/messages/whatsapp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15557654321",
    "whatsapp_message": {
      "type": "template",
      "template": {
        "name": "order_confirmation",
        "language": {
          "policy": "deterministic",
          "code": "en_US"
        },
        "components": [
          {
            "type": "body",
            "parameters": [
              {"type": "text", "text": "John"},
              {"type": "text", "text": "ORD-12345"}
            ]
          }
        ]
      }
    }
  }'

Python

from telnyx import Telnyx
client = Telnyx(api_key="YOUR_API_KEY")

client.messages.send_whatsapp(
    from_="+15551234567",
    to="+15557654321",
    whatsapp_message={
        "type": "template",
        "template": {
            "name": "order_confirmation",
            "language": {"policy": "deterministic", "code": "en_US"},
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "text": "John"},
                        {"type": "text", "text": "ORD-12345"}
                    ]
                }
            ]
        }
    }
)

Node.js

import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const message = await client.messages.sendWhatsapp({
  from: '+15551234567',
  to: '+15557654321',
  whatsapp_message: {
    type: 'template',
    template: {
      name: 'order_confirmation',
      language: { policy: 'deterministic', code: 'en_US' },
      components: [
        {
          type: 'body',
          parameters: [
            { type: 'text', text: 'John' },
            { type: 'text', text: 'ORD-12345' }
          ]
        }
      ]
    }
  }
});

Sending by Template ID

Instead of specifying name and language, you can reference a template by its Telnyx UUID (template_id). The name and language are resolved automatically from the database.

cURL

curl -X POST https://api.telnyx.com/v2/messages/whatsapp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15557654321",
    "whatsapp_message": {
      "type": "template",
      "template": {
        "template_id": "019cd44b-3a1c-781b-956e-bd33e9fd2ac6",
        "components": [
          {
            "type": "body",
            "parameters": [
              {"type": "text", "text": "John"},
              {"type": "text", "text": "ORD-12345"}
            ]
          }
        ]
      }
    }
  }'

You can find a template’s UUID by listing templates via GET /v2/whatsapp/message_templates. The id field in the response is the template_id you can use when sending.

Template Components

Templates use components to pass dynamic content into header, body, and button slots:

Component `type`	`sub_type`	Use
`header`	—	Media or text for template header
`body`	—	Variable substitution in body text
`button`	`quick_reply`	Quick reply button payload
`button`	`url`	Dynamic URL suffix for CTA buttons

Media Header Template

To send a template with an image header:

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "template",
    "template": {
      "name": "promo_with_image",
      "language": {"policy": "deterministic", "code": "en_US"},
      "components": [
        {
          "type": "header",
          "parameters": [
            {"type": "image", "image": {"link": "https://example.com/promo.jpg"}}
          ]
        },
        {
          "type": "body",
          "parameters": [
            {"type": "text", "text": "20%"}
          ]
        }
      ]
    }
  }
}

Header parameters also support document and video types with the same {link, caption, filename} structure.

Text Messages

Send plain text within the 24-hour conversation window. Body must be 1–4096 bytes.

cURL

curl -X POST https://api.telnyx.com/v2/messages/whatsapp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15557654321",
    "whatsapp_message": {
      "type": "text",
      "text": {
        "body": "Thanks for reaching out! How can we help?",
        "preview_url": false
      }
    }
  }'

Python

from telnyx import Telnyx
client = Telnyx(api_key="YOUR_API_KEY")

client.messages.send_whatsapp(
    from_="+15551234567",
    to="+15557654321",
    whatsapp_message={
        "type": "text",
        "text": {
            "body": "Thanks for reaching out! How can we help?",
            "preview_url": False
        }
    }
)

Node.js

import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const message = await client.messages.sendWhatsapp({
  from: '+15551234567',
  to: '+15557654321',
  whatsapp_message: {
    type: 'text',
    text: {
      body: 'Thanks for reaching out! How can we help?',
      preview_url: false
    }
  }
});

Set preview_url: true to render link previews when the message body contains a URL.

Media Messages

Send images, videos, documents, audio, and stickers. Each media object requires exactly one of link (URL) or id (Meta media ID). Captions are optional and limited to 1024 bytes.

Image

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "image",
    "image": {
      "link": "https://example.com/receipt.png",
      "caption": "Your receipt for order #12345"
    }
  }
}

Document

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "document",
    "document": {
      "link": "https://example.com/invoice.pdf",
      "filename": "invoice_12345.pdf",
      "caption": "Invoice for March 2026"
    }
  }
}

Video

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "video",
    "video": {
      "link": "https://example.com/tutorial.mp4",
      "caption": "Setup walkthrough"
    }
  }
}

Audio

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "audio",
    "audio": {
      "link": "https://example.com/voicenote.ogg"
    }
  }
}

Sticker

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "sticker",
    "sticker": {
      "link": "https://example.com/sticker.webp"
    }
  }
}

Stickers do not support captions. Audio does not support captions. Only one media type per message.

Location Messages

Share a location pin. Latitude and longitude are passed as strings (decimal format).

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "location",
    "location": {
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "name": "Telnyx HQ",
      "address": "311 W 43rd St, New York, NY"
    }
  }
}

Latitude must be between -90 and 90. Longitude must be between -180 and 180.

Contact Messages

Share one or more contact cards (1–257 contacts per message).

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "contacts",
    "contacts": [
      {
        "name": {
          "formatted_name": "Jane Smith",
          "first_name": "Jane",
          "last_name": "Smith"
        },
        "phones": [
          {"phone": "+15559876543", "type": "WORK"}
        ],
        "emails": [
          {"email": "jane@example.com", "type": "WORK"}
        ]
      }
    ]
  }
}

Interactive Messages

Interactive messages let recipients tap buttons, select from lists, or open URLs. Supported interactive.type values:

Type	Description
`button`	Up to 3 quick reply buttons
`cta_url`	Call-to-action URL button
`list`	Selectable list with sections and rows
`location_request_message`	Request the recipient’s location
`carousel`	Scrollable cards with media and buttons

Quick Reply Buttons

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": {"text": "Would you like to schedule a callback?"},
      "action": {
        "buttons": [
          {"type": "reply", "reply": {"id": "yes_callback", "title": "Yes, call me"}},
          {"type": "reply", "reply": {"id": "no_thanks", "title": "No thanks"}}
        ]
      }
    }
  }
}

When a recipient taps a button, you receive an inbound webhook with the button’s id in the payload.

CTA URL Button

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "interactive",
    "interactive": {
      "type": "cta_url",
      "body": {"text": "Track your shipment"},
      "action": {
        "name": "cta_url",
        "parameters": {
          "display_text": "Track Order",
          "url": "https://example.com/track/12345"
        }
      }
    }
  }
}

List Messages

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "interactive",
    "interactive": {
      "type": "list",
      "body": {"text": "Select a support topic:"},
      "action": {
        "button": "Choose topic",
        "sections": [
          {
            "title": "Account",
            "rows": [
              {"id": "billing", "title": "Billing", "description": "Payment and invoice questions"},
              {"id": "access", "title": "Account Access", "description": "Login and permissions"}
            ]
          },
          {
            "title": "Technical",
            "rows": [
              {"id": "api", "title": "API Issues", "description": "Integration and endpoint help"},
              {"id": "webhooks", "title": "Webhooks", "description": "Delivery and configuration"}
            ]
          }
        ]
      }
    }
  }
}

Location Request

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "interactive",
    "interactive": {
      "type": "location_request_message",
      "body": {"text": "Share your location so we can find the nearest store."},
      "action": {"name": "send_location"}
    }
  }
}

Reactions

React to a received message with an emoji.

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXhvRm",
      "emoji": "👍"
    }
  }
}

Reply Context

Reply to a specific message by including context.message_id:

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "text",
    "context": {
      "message_id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXhvRm"
    },
    "text": {
      "body": "Thanks for your order! It will ship tomorrow."
    }
  }
}

Callback Tracking

Use biz_opaque_callback_data to attach tracking data that will be returned in delivery webhooks:

{
  "from": "+15551234567",
  "to": "+15557654321",
  "whatsapp_message": {
    "type": "text",
    "biz_opaque_callback_data": "order_12345_confirmation",
    "text": {
      "body": "Your order has been confirmed."
    }
  }
}

API Response

All message types return the same response structure:

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "WHATSAPP",
    "from": {"phone_number": "+15551234567"},
    "to": [{"phone_number": "+15557654321", "status": "queued"}],
    "webhook_url": "https://example.com/webhooks"
  }
}

Validation Rules

Constraint	Limit
Text body	1–4096 bytes
Media caption	Max 1024 bytes
Header text	Max 1024 bytes
Contacts per message	1–257
Location latitude	-90 to 90 (string)
Location longitude	-180 to 180 (string)
Media per message	Exactly 1
Media source	Exactly one of `link` or `id`

Error Handling

Common WhatsApp errors return error code 40008. This is a catch-all code covering template issues (pending, rejected, paused, disabled) and delivery failures. For general API errors, see the Error Codes Reference. Template, text, media, and interactive messages all use the same endpoint. The type field inside whatsapp_message determines which content object is required.

Next Steps

Send your first WhatsApp message end-to-end Set up your WhatsApp Business Account and verify your number Handle inbound messages and delivery status callbacks

Manage Templates

Source: https://developers.telnyx.com/docs/messaging/whatsapp/manage-templates.md

Manage WhatsApp Message Templates

WhatsApp requires pre-approved message templates for business-initiated conversations. Use the Telnyx Management API to create, review, and manage templates programmatically. For template best practices and approval tips, see the Approval Tips guide.

Template Lifecycle

Templates must be approved by Meta before they can be used. Review typically takes 24-48 hours.

List Templates

Retrieve all templates for your WhatsApp Business Account.

cURL

curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

from telnyx import Telnyx
client = Telnyx(api_key="YOUR_API_KEY")

templates = client.whatsapp.templates.list()
for template in templates.data:
    print(f"{template.name} ({template.category}) - {template.status}")

Node.js

import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const { data } = await client.whatsapp.templates.list();
data.forEach(t => console.log(`${t.name} (${t.category}) - ${t.status}`));

Filter by Status

# List only approved templates
curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates?filter[status]=APPROVED" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by name
curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates?filter[search]=welcome" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "019cd44b-3a1c-781b-956e-bd33e9fd2ac6",
      "record_type": "whatsapp_message_template",
      "name": "welcome_message",
      "category": "MARKETING",
      "language": "en_US",
      "status": "APPROVED",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}! Welcome to our WhatsApp updates.",
          "example": {
            "body_text": [["John"]]
          }
        }
      ],
      "quality_rating": "HIGH",
      "created_at": "2026-03-15T12:00:00.000Z",
      "updated_at": "2026-03-15T14:30:00.000Z"
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_results": 1
  }
}

Create a Template

Submit a new template for Meta review. Set a display name for the phone number before submitting templates. Templates submitted from numbers without an approved display name are rejected by Meta. Always include sample values in the example field when your template contains parameters (\{\{1\}\}, \{\{2\}\}). Templates without examples are typically rejected.

Authentication Template

Authentication templates include an OTP code with a copy-code button.

cURL

curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "login_verification",
    "category": "AUTHENTICATION",
    "language": "en_US",
    "components": [
      {
        "type": "BODY",
        "text": "Your verification code is {{1}}. Do not share this code.",
        "example": {
          "body_text": [["123456"]]
        }
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "OTP",
            "otp_type": "COPY_CODE",
            "text": "Copy Code"
          }
        ]
      }
    ]
  }'

Python

from telnyx import Telnyx
client = Telnyx(api_key="YOUR_API_KEY")

template = client.whatsapp.templates.create(
    name="login_verification",
    category="AUTHENTICATION",
    language="en_US",
    waba_id="YOUR_WABA_ID",
    components=[
        {
            "type": "BODY",
            "text": "Your verification code is {{1}}. Do not share this code.",
            "example": {"body_text": [["123456"]]}
        },
        {
            "type": "BUTTONS",
            "buttons": [{"type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code"}]
        }
    ]
)
print(f"Template ID: {template.id}, Status: {template.status}")

Node.js

import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const template = await client.whatsapp.templates.create({
  name: 'login_verification',
  category: 'AUTHENTICATION',
  language: 'en_US',
  waba_id: 'YOUR_WABA_ID',
  components: [
    {
      type: 'BODY',
      text: 'Your verification code is {{1}}. Do not share this code.',
      example: { body_text: [['123456']] }
    },
    {
      type: 'BUTTONS',
      buttons: [{ type: 'OTP', otp_type: 'COPY_CODE', text: 'Copy Code' }]
    }
  ]
});
console.log(`Template ID: ${template.data.id}`);

Marketing Template

Marketing templates support rich media headers, body text with parameters, and call-to-action buttons.

curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "spring_promotion",
    "category": "MARKETING",
    "language": "en_US",
    "components": [
      {
        "type": "HEADER",
        "format": "TEXT",
        "text": "Spring Sale!"
      },
      {
        "type": "BODY",
        "text": "Hi {{1}}, enjoy {{2}}% off your next order with code {{3}}. Offer ends soon!",
        "example": {
          "body_text": [["Sarah", "25", "SPRING25"]]
        }
      },
      {
        "type": "FOOTER",
        "text": "Reply STOP to opt out"
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "URL",
            "text": "Shop Now",
            "url": "https://example.com/shop?promo={{1}}",
            "example": ["SPRING25"]
          }
        ]
      }
    ]
  }'

Utility Template

Utility templates are for transactional updates like order confirmations, shipping notifications, and account alerts.

curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      {
        "type": "BODY",
        "text": "Your order {{1}} has shipped! Expected delivery: {{2}}. Track your package here.",
        "example": {
          "body_text": [["ORD-12345", "March 20, 2026"]]
        }
      }
    ]
  }'

Get a Template

Retrieve details of a specific template by ID.

curl -X GET "https://api.telnyx.com/v2/whatsapp/message_templates/{template_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a Template

Edit a template’s content. Only templates in APPROVED or REJECTED status can be updated. Updated templates are re-submitted for Meta review. Editing an approved template resets its status to PENDING while Meta reviews the changes. Your template will be temporarily unavailable for sending.

curl -X PATCH "https://api.telnyx.com/v2/whatsapp/message_templates/{template_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "components": [
      {
        "type": "BODY",
        "text": "Your order {{1}} has shipped! Estimated arrival: {{2}}.",
        "example": {
          "body_text": [["ORD-12345", "March 22, 2026"]]
        }
      }
    ]
  }'

Edit and resubmit rejected templates rather than creating new ones. Meta enforces a 30-day restriction on reusing template names.

Delete a Template

Remove a template permanently. This action cannot be undone.

curl -X DELETE "https://api.telnyx.com/v2/whatsapp/message_templates/{template_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Template Categories

Category	Use Case	Requires Opt-in	Pricing Tier
AUTHENTICATION	OTP codes, login verification	No	Lowest
UTILITY	Order updates, shipping, account alerts	Yes	Medium
MARKETING	Promotions, newsletters, product launches	Yes	Highest

Choose the most specific category. Meta may reclassify templates that don’t match their declared category, which can affect pricing and delivery.

Authentication Rules

Must contain a one-time code or password
Must include a copy-code or one-tap button
Cannot include URLs or media (except the OTP button)
Limited to one code parameter

Naming Rules

Lowercase letters, numbers, and underscores only
Maximum 512 characters
Must be unique within your WABA for each language
Avoid words like test, sample, demo — Meta flags these for extra review

Approval Tips

Always include sample values — Templates with parameters but no example field are almost always rejected
Set a display name first — Templates submitted from numbers without an approved display name get rejected
Complete your business profile — Add website, description, and category before submitting. Incomplete profiles increase rejection rates
Edit rejected templates, don’t recreate — Meta enforces a 30-day restriction on reusing template names
Match category to content — Meta may reclassify miscategorized templates, affecting pricing and delivery

For detailed best practices and troubleshooting, see our WhatsApp Message Templates Guide on the support center.

Multi-Language Templates

Create the same template in multiple languages. Each language variant is reviewed independently.

# English version
curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      {
        "type": "BODY",
        "text": "Order {{1}} confirmed. Delivery by {{2}}.",
        "example": {"body_text": [["ORD-789", "March 20"]]}
      }
    ]
  }'

# Spanish version
curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "category": "UTILITY",
    "language": "es",
    "components": [
      {
        "type": "BODY",
        "text": "Pedido {{1}} confirmado. Entrega estimada: {{2}}.",
        "example": {"body_text": [["ORD-789", "20 de marzo"]]}
      }
    ]
  }'

Error Handling

Error Code	Description	Resolution
`40008`	Template operation failed (catch-all)	Check template status and Meta error details
`10004`	Missing required parameter	Ensure all required fields are included
`10032`	Invalid enumerated value	Check category and language codes

Common issues:

Rejected templates: Review Template Best Practices for approval tips
Duplicate name: Template names must be unique per language within a WABA
Invalid parameters: Ensure example values match parameter count in template body

Next Steps

Send Messages — Use approved templates to send messages
Approval Tips — Tips for getting templates approved
Quickstart — End-to-end setup guide

API Reference (Messaging)

Messages

Send a message: Send a message with a Phone Number, Alphanumeric Sender ID, Short Code or Number Pool.
Retrieve a message: Note: This API endpoint can only retrieve messages that are no older than 10 days since their creation. If you require messages older than this, please generat…
Cancel a scheduled message: Cancel a scheduled message that has not yet been sent. Only messages with status=scheduled and send_at more than a minute from now can be cancelled.
Send a group MMS message
Send a long code message
Send a message using number pool
Schedule a message: Schedule a message with a Phone Number, Alphanumeric Sender ID, Short Code or Number Pool.
Send a short code message
Send a message using an alphanumeric sender ID: Send an SMS message using an alphanumeric sender ID. This is SMS only.
Retrieve group MMS messages: Retrieve all messages in a group MMS conversation by the group message ID.

Whatsapp messaging

Send a Whatsapp message

Callbacks

Profiles

Opt-Out Management

List Auto-Response Settings
Create auto-response setting
Get Auto-Response Setting
Update Auto-Response Setting
Delete Auto-Response Setting
List opt-outs: Retrieve a list of opt-out blocks.

Messaging

Regenerate messaging profile secret: Regenerate the v1 secret for a messaging profile.
List alphanumeric sender IDs for a messaging profile: List all alphanumeric sender IDs associated with a specific messaging profile.
Get detailed messaging profile metrics: Get detailed metrics for a specific messaging profile, broken down by time interval.
Retrieve a messaging hosted number: Retrieve a specific messaging hosted number by its ID or phone number.
Update a messaging hosted number: Update the messaging settings for a hosted number.
List messaging hosted numbers: List all hosted numbers associated with the authenticated user.

Short Codes

List short codes
Retrieve a short code
Update short code: Update the settings for a specific short code. To unbind a short code from a profile, set the messaging_profile_id to null or an empty string.

Hosted Numbers

List messaging hosted number orders
Create a messaging hosted number order
Retrieve a messaging hosted number order
Delete a messaging hosted number order: Delete a messaging hosted number order and all associated phone numbers.
Upload hosted number document
Validate hosted number codes: Validate the verification codes sent to the numbers of the hosted order. The verification codes must be created in the verification codes endpoint.
Create hosted number verification codes: Create verification codes to validate numbers of the hosted order. The verification codes will be sent to the numbers of the hosted order.
Check hosted messaging eligibility
Delete a messaging hosted number

Number Settings

Verification Requests

List Verification Requests: Get a list of previously-submitted tollfree verification requests
Submit Verification Request: Submit a new tollfree verification request
Get Verification Request: Get a single verification request by its ID.
Update Verification Request: Update an existing tollfree verification request. This is particularly useful when there are pending customer actions to be taken.
Delete Verification Request: Delete a verification request
Get Verification Request Status History: Get the history of status changes for a verification request.

Campaign

Submit Campaign: Before creating a campaign, use the Qualify By Usecase endpoint to ensure that the brand you want to assign a new campaign to is qualified for the desired use…
Qualify By Usecase: This endpoint allows you to see whether or not the supplied brand is suitable for your desired campaign use case.
List Campaigns: Retrieve a list of campaigns associated with a supplied brandId.
Get campaign: Retrieve campaign details by campaignId.
Update campaign: Update a campaign’s properties by campaignId. Please note: only sample messages are editable.
Deactivate campaign: Terminate a campaign. Note that once deactivated, a campaign cannot be restored.
Submit campaign appeal for manual review: Submits an appeal for rejected native campaigns in TELNYX_FAILED or MNO_REJECTED status. The appeal is recorded for manual compliance team review and the campa…
Get Campaign Mno Metadata: Get the campaign metadata for each MNO it was submitted to.
Get campaign operation status: Retrieve campaign’s operation status at MNO level.
Get OSR campaign attributes
Get Sharing Status
Accept Shared Campaign: Manually accept a campaign shared with Telnyx
Get Campaign Cost

Brands

List Brands: This endpoint is used to list all brands associated with your organization.
Create Brand: This endpoint is used to create a new brand. A brand is an entity created by The Campaign Registry (TCR) that represents an organization or a company. It is th…
Get Brand: Retrieve a brand by brandId.
Update Brand: Update a brand’s attributes by brandId.
Delete Brand: Delete Brand. This endpoint is used to delete a brand. Note the brand cannot be deleted if it contains one or more active campaigns, the campaigns need to be i…
Resend brand 2FA email
List External Vettings: Get list of valid external vetting record for a given brand
Order Brand External Vetting: Order new external vetting for a brand.
Import External Vetting Record: This operation can be used to import an external vetting record from a TCR-approved
Revet Brand: This operation allows you to revet the brand. However, revetting is allowed once after the successful brand registration and thereafter limited to once every 3…
Get Brand SMS OTP Status by Brand ID: Query the status of an SMS OTP (One-Time Password) for Sole Proprietor brand verification using the Brand ID.
Trigger Brand SMS OTP: Trigger or re-trigger an SMS OTP (One-Time Password) for Sole Proprietor brand verification.
Verify Brand SMS OTP: Verify the SMS OTP (One-Time Password) for Sole Proprietor brand verification.
Get Brand SMS OTP Status: Query the status of an SMS OTP (One-Time Password) for Sole Proprietor brand verification.
Get Brand Feedback By Id: Get feedback about a brand by ID. This endpoint can be used after creating or revetting

Enum

Get Enum

Shared Campaigns

List Shared Campaigns: Retrieve all partner campaigns you have shared to Telnyx in a paginated fashion.
Get Single Shared Campaign: Retrieve campaign details by campaignId.
Update Single Shared Campaign: Update campaign details by campaignId. Please note: Only webhook urls are editable.
Get Sharing Status
List shared partner campaigns: Get all partner campaigns you have shared to Telnyx in a paginated fashion

Phone Number Campaigns

List phone number campaigns
Create New Phone Number Campaign
Get Single Phone Number Campaign: Retrieve an individual phone number/campaign assignment by phoneNumber.
Delete Phone Number Campaign: This endpoint allows you to remove a campaign assignment from the supplied phoneNumber.

Bulk Phone Number Campaigns

Assign Messaging Profile To Campaign: This endpoint allows you to link all phone numbers associated with a Messaging Profile to a campaign. Please note: if you want to assign phone numbers to a…
Get Assignment Task Status: Check the status of the task associated with assigning all phone numbers on a messaging profile to a campaign by taskId.
Get Phone Number Status: Check the status of the individual phone number/campaign assignments associated with the supplied taskId.

RCS

Send an RCS message
List all RCS agents
Retrieve an RCS agent
Modify an RCS agent
Check RCS capabilities (batch)
Check RCS capabilities
Add RCS test number: Adds a test phone number to an RCS agent for testing purposes.
Generate RCS deeplink: Generate a deeplink URL that can be used to start an RCS conversation with a specific agent.

Whatsapp Business Accounts

Whatsapp Phone Numbers

Initialize Whatsapp phone number verification
List Whatsapp phone numbers
Delete a Whatsapp phone number
Get calling settings for a phone number
Enable or disable Whatsapp calling for a phone number
Get phone number business profile
Update phone number business profile
Get Whatsapp profile photo
Upload Whatsapp profile photo
Delete Whatsapp profile photo
Resend verification code
Submit verification code for a phone number
Get conversation window status for a phone number: Returns whether the 24-hour conversation window is currently open for a given source/destination pair. If window_active is false, only template messages may be…

Whatsapp Message Templates

Messaging llms.txt

SMS & MMS llms.txt

⌘I

​Telnyx Messaging — Full Documentation

​SMS & MMS

​Send Your First Message

​Prerequisites

​1. Get two phone numbers

​2. Create a Messaging Profile

​3. Get your API key

​4. Send a message

​Response

​Error handling

​Error response format

​SDK error handling examples

​HTTP error codes

​Messaging-specific error codes

​Rate limiting

​Troubleshooting checklist

​Webhooks and delivery tracking

​Message lifecycle events

​Webhook payload example

​Processing webhooks

​Retrieve message status via API

​Delivery failure error codes

​Webhook security

​Next steps

​Receive Messages

​Prerequisites

​Quick Start

​Auto-Reply to Incoming Messages

​Webhook Payload Reference

​Inbound SMS

​Inbound MMS

​Webhook Payload Schema

​Downloading MMS Media

​Verifying Webhook Signatures

​Handling Failed Webhooks

​Troubleshooting

​Webhook URL Hierarchy

​Related Webhook Events

​Next Steps

​Webhooks

​Prerequisites

​How webhook delivery works

​Webhook URL hierarchy

​Webhook event types

​Payload structure

​Event examples

​Inbound message (message.received)

​Message sent (message.sent)

​Delivery receipt (message.finalized)

​Delivery statuses

​Webhook signature verification

​Get your public key

​Verification examples

​Handling webhooks in your application

​Basic webhook handler

​Retry behavior and error handling

​Retry policy

​Best practices for reliability

​Webhook IP allowlist

​Troubleshooting

​Next steps

​Choosing a Sender Type

​Interactive Product Selector

​Use Case Decision Tree

​Sender Comparison

​Capabilities at a Glance

​Registration & Cost Comparison

​Check Coverage by Country

​Key Regional Considerations

​Quick Start: Send Your First Message

​Next Steps

​Message Encoding

​Segment calculator

​How segments work

​Segment calculation formula

​Cost impact example

​Encoding by sender type

​GSM 7-bit character set

​Detecting encoding in your application

​Common encoding issues

Telnyx Messaging — Full Documentation

SMS & MMS

Send Your First Message

Prerequisites

1. Get two phone numbers

2. Create a Messaging Profile

3. Get your API key

4. Send a message

Response

Error handling

Error response format

SDK error handling examples

HTTP error codes

Messaging-specific error codes

Rate limiting

Troubleshooting checklist

Webhooks and delivery tracking

Message lifecycle events

Webhook payload example

Processing webhooks

Retrieve message status via API

Delivery failure error codes

Webhook security

Next steps

Receive Messages

Prerequisites

Quick Start

Auto-Reply to Incoming Messages

Webhook Payload Reference

Inbound SMS

Inbound MMS

Webhook Payload Schema

Downloading MMS Media

Verifying Webhook Signatures

Handling Failed Webhooks

Troubleshooting

Webhook URL Hierarchy

Related Webhook Events

Next Steps

Webhooks

Prerequisites

How webhook delivery works

Webhook URL hierarchy

Webhook event types

Payload structure

Event examples

Inbound message (`message.received`)

Message sent (`message.sent`)

Delivery receipt (`message.finalized`)

Delivery statuses

Webhook signature verification

Get your public key

Verification examples

Handling webhooks in your application

Basic webhook handler

Retry behavior and error handling

Retry policy

Best practices for reliability

Webhook IP allowlist

Troubleshooting

Next steps

Choosing a Sender Type

Interactive Product Selector

Use Case Decision Tree

Sender Comparison

Capabilities at a Glance

Registration & Cost Comparison

Check Coverage by Country

Key Regional Considerations

Quick Start: Send Your First Message

Next Steps

Message Encoding

Segment calculator

How segments work

Segment calculation formula

Cost impact example

Encoding by sender type

GSM 7-bit character set

Detecting encoding in your application

Common encoding issues