Telnyx Messaging: RCS — Full Documentation

Complete page content for RCS (Messaging section) of the Telnyx developer docs (https://developers.telnyx.com). This file: https://developers.telnyx.com/docs/development/llms/messaging-rcs-llms-full-txt.md · Root index: https://developers.telnyx.com/llms.txt

Getting Started

Agent Registration Quickstart

Source: https://developers.telnyx.com/docs/messaging/rcs/agent-registration.md

Register an RCS agent

This quickstart takes an RCS agent from brand registration to carrier launch. The process has two stages, allowing the agent to be created and tested before all carrier launch information is available. The first stage registers the brand, creates the agent, submits its basic configuration, and adds test devices. The second stage provides the campaign and testing evidence needed for carrier review.

Prerequisites

Before starting, gather:

A Telnyx account with an API key
A Messaging Profile ID
Business registration details, including the legal name, EIN, address, website, and contact
Public HTTPS URLs for the agent logo, hero image, privacy policy, and terms and conditions

Set the API key as an environment variable:

export TELNYX_API_KEY="YOUR_API_KEY"

RCS registration is asynchronous. A successful submission means Telnyx accepted the work, not that external review is complete. Use the retrieve endpoints to follow each resource’s status.

Stage 1: Create and test the agent

Create a brand

A brand represents the legal business operating the RCS agent.

curl -X POST "https://api.telnyx.com/v2/rcs/brands" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Acme",
    "legal_name": "Acme LLC",
    "legal_entity_type": "LIMITED_LIABILITY_COMPANY",
    "organization_type": "PRIVATE_PROFIT",
    "website_url": "https://www.example.com",
    "profile_id": "40000000-0000-0000-0000-000000000001",
    "identifiers": {
      "ein": {
        "identifier_type": "EIN",
        "value": "12-3456789"
      }
    },
    "addresses": {
      "primary": {
        "line_1": "1 Main Street",
        "city": "Chicago",
        "administrative_area": "IL",
        "postal_code": "60601",
        "country_code": "US"
      }
    },
    "contacts": {
      "brand": {
        "contact_type": "BRAND",
        "first_name": "Jane",
        "last_name": "Doe",
        "title": "Messaging Operations Manager",
        "email": "jane@example.com",
        "phone_number": "+13125550100"
      }
    }
  }'

Save the returned brand_id. A brand can be updated while its status is CREATED. After submission, its registration fields are locked.

Submit the brand

curl -X POST "https://api.telnyx.com/v2/rcs/brands/BRAND_ID/submit" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

The endpoint returns 202 Accepted. Poll the brand until its status becomes VERIFIED:

curl "https://api.telnyx.com/v2/rcs/brands/BRAND_ID" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

Do not submit an agent until the brand is VERIFIED. REJECTED and FAILED are terminal states that require investigation before creating another registration.

Create the agent basics

Create the agent with only the information needed for the first stage. The Idempotency-Key is required. Reuse the same key and request body when retrying an uncertain response.

curl -X POST "https://api.telnyx.com/v2/rcs/agents" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-order-updates-v1" \
  -d '{
    "brand_id": "BRAND_ID",
    "display_name": "Acme Order Updates",
    "use_case": "TRANSACTIONAL",
    "configuration": {
      "basics": {
        "description": "Order confirmations and delivery updates",
        "logo_url": "https://www.example.com/rcs/logo.png",
        "hero_url": "https://www.example.com/rcs/hero.png",
        "brand_color": "#123456",
        "privacy_policy_url": "https://www.example.com/privacy",
        "terms_and_conditions_url": "https://www.example.com/terms",
        "email": {
          "address": "support@example.com",
          "label": "Support"
        }
      }
    }
  }'

Save the returned agent_id. Agent fields can be updated while the status is CREATED. Using an existing idempotency key with a different request returns a conflict. Do not generate a new key for a retry of the same logical agent creation.

Submit the agent basics

curl -X POST "https://api.telnyx.com/v2/rcs/agents/AGENT_ID/submit" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

This starts provider provisioning and basic agent review. Follow progress with:

curl "https://api.telnyx.com/v2/rcs/agents/AGENT_ID" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

When basics_status is SUBMITTED or APPROVED, the agent can remain in this stage during testing and while carrier launch information is gathered. There is no requirement to begin the second stage immediately.

Add a test device

After the basic submission completes, add an RCS-capable phone number in E.164 format:

curl -X POST "https://api.telnyx.com/v2/rcs/agents/AGENT_ID/test_devices" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+13125550123"
  }'

List the agent’s test devices:

curl "https://api.telnyx.com/v2/rcs/agents/AGENT_ID/test_devices" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

Stage 2: Submit the agent for launch

Start this stage after gathering the campaign, consent, and testing information needed for carrier review. The testing.test_url must point to a publicly accessible video that demonstrates START, STOP, and HELP behavior and an example interaction with the agent.

curl -X POST "https://api.telnyx.com/v2/rcs/agents/AGENT_ID/launch" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": {
      "company_overview": "Acme provides online retail services.",
      "agent_overview": "The agent sends order confirmations and delivery updates.",
      "interactions": [
        {
          "interaction_type": "TRANSACTIONAL_UPDATES"
        },
        {
          "interaction_type": "CUSTOMER_SUPPORT"
        }
      ],
      "message_examples": [
        "Your Acme order is confirmed.",
        "Your Acme order has shipped.",
        "Your Acme order was delivered."
      ],
      "consent_settings": {
        "opt_in_methods": [
          {
            "method_type": "WEBSITE"
          }
        ],
        "call_to_action": "Select RCS updates during checkout.",
        "call_to_action_url": "https://www.example.com/checkout",
        "call_to_action_media_url": "https://www.example.com/rcs/opt-in.png",
        "double_opt_in": false,
        "opt_in_message": "You are subscribed to Acme order updates.",
        "help_response": "Contact support@example.com for help.",
        "opt_out_response": "You will receive no more messages."
      }
    },
    "testing": {
      "test_url": "https://www.example.com/rcs/test-video",
      "additional_information": "The video demonstrates START, STOP, HELP, and an order-status interaction."
    }
  }'

The endpoint returns 202 Accepted. Telnyx submits the campaign and testing sections in the order required by the provider, then tracks external review and launch.

Monitor launch status

Retrieve the agent until status becomes LIVE:

curl "https://api.telnyx.com/v2/rcs/agents/AGENT_ID" \
  -H "Authorization: Bearer ${TELNYX_API_KEY}"

The agent response includes section statuses, test devices, carrier approvals, and provider capabilities. Carrier approval may be reported as an aggregate hub status when the provider does not expose individual carrier results.

Agent status	Meaning
`CREATED`	The agent is an editable draft.
`SUBMITTED`	Telnyx has started the provider submission.
`VERIFYING`	External verification is in progress.
`VERIFIED`	Verification completed and launch can proceed.
`LAUNCHING`	Carrier launch is in progress.
`LAUNCHED`	Launch completed and activation is being finalized.
`LIVE`	The agent is active for RCS messaging.
`REJECTED`	External review rejected the agent.
`FAILED`	Processing stopped after a terminal failure.

Once the agent is LIVE, continue with Send an RCS message.

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 availability depends on the device, operating system, and carrier.

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: Create and submit the legal business behind the agent. Telnyx tracks the external brand review until verification completes. Create the agent with its basic configuration, submit it, and add test devices. The agent can remain in this stage while campaign and carrier launch information is collected. When ready, provide the campaign, consent, message examples, and testing evidence. Telnyx submits each section in the provider’s required order. Telnyx tracks external verification and carrier launch until the agent is live. Review duration depends on the brand, use case, and carriers. Once approved, your RCS Agent can send messages to any RCS-capable device. Follow the RCS agent registration quickstart for the complete API workflow. Testing during approval: Testing can begin before full carrier approval. Once the agent reaches the testing stage, add test devices and send test messages through 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 the RCS agent reaches the testing stage or is fully approved, send messages to its test devices 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+) 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 <TOKEN>'

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

Sending Messages

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 <a> tag or button click:

<a href="sms:+18445550001?service_id=agent_id%40rbm.goog&body=Hi!"
   class="rcs-button">
  💬 Chat with us on RCS
</a>

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.

Receiving Messages

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.

API Reference (RCS)

RCS Brands

Create an RCS brand: Creates an editable RCS brand draft. Creating the draft does not begin external review.
List RCS brands: Lists RCS brands owned by the authenticated organization.
Retrieve an RCS brand: Retrieves an RCS brand and its current lifecycle status.
Update an RCS brand: Updates one or more fields on a brand while its status is CREATED. Submitted brands cannot be changed.
Submit an RCS brand: Starts asynchronous provider provisioning and external review for a brand. Repeating this request for an in-progress brand returns its current state without cr…

RCS Agents

Create an RCS agent: Creates an editable RCS agent draft under a brand. The Idempotency-Key is scoped to the authenticated organization. Reusing the key with the same request ret…
List RCS agents: Lists RCS agents owned by the authenticated organization, optionally filtered by brand.
Retrieve an RCS agent: Retrieves an RCS agent, section statuses, test devices, carrier approvals, and provider capabilities.
Update an RCS agent: Updates one or more fields on an agent while its status is CREATED. Submitted agents cannot be changed through this endpoint.
Submit RCS agent basics: Starts asynchronous provider provisioning and submits the agent’s basic configuration. The brand must be VERIFIED. Repeating this request for an in-progress…
Submit an RCS agent for launch: Adds the campaign and testing configuration, then starts asynchronous carrier launch. Agent basics must already be submitted. Repeating a launch that is alread…
Add an RCS agent test device: Adds an RCS-capable test number after provider agent creation. Repeating the request for a number already attached to the agent returns the existing test devic…
List RCS agent test devices: Lists test devices attached to an RCS agent.
Remove an RCS agent test device: Removes a test device from an RCS agent and its provider registration.
List RCS agent carrier approvals: Lists carrier approval records for an RCS agent. The provider may expose per-carrier, hub-level, or bot-level approval status.

RCS

Send an RCS message: Queues an outbound RCS message through the selected RCS agent. Check recipient capabilities before sending features that require RCS support.
List all RCS agents: Returns RCS agents available to the authenticated account.
Retrieve an RCS agent: Returns the configuration and current state of the specified RCS agent.
Modify an RCS agent: Updates the supplied configuration fields on the specified RCS agent.
Check RCS capabilities (batch): Returns RCS capability information for multiple recipients in one request.
Check RCS capabilities: Returns the RCS features supported by the specified recipient for the selected agent.
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.

⌘I

​Telnyx Messaging: RCS — Full Documentation

​Getting Started

​Agent Registration Quickstart

​Register an RCS agent

​Prerequisites

​Stage 1: Create and test the agent

​Create a brand

​Submit the brand

​Create the agent basics

​Submit the agent basics

​Add a test device

​Stage 2: Submit the agent for launch

​Monitor launch status

​RCS Getting Started

​What is RCS?

​Prerequisites

​Approval process

​1. Create a Messaging Profile

​2. Get your API key

​3. Send an RCS message

​Response

​4. Handle incoming messages

​RCS vs SMS comparison

​Next steps

​RCS with AI Assistant

​Why RCS + AI Assistant?

​How it works

​Prerequisites

​1. Create an AI Assistant

​2. Create a Messaging Profile with AI

​3. Link your RCS Agent to the AI-enabled profile

​4. Test your AI-powered RCS agent

​Best practices

​Monitoring and analytics

​Pricing

​Try it yourself

​Next steps

​Sending Messages

​Send RCS Messages

​Prerequisites

​Send a text message

​Send a rich card

​Card options

​Send a carousel

​Add suggested actions

​SMS fallback

​RCS vs. SMS/MMS comparison

​Related resources

​Capabilities & Deeplinks

​Query single number

​Response examples

​Feature reference

​Bulk capability query

​Send with automatic fallback

​RCS Deeplinks

​Generate a deeplink

​Response

​Use deeplinks

​Requirements

​Related resources

​RCS Deeplinks

​Quick reference

​Receiving Messages

​RCS Webhooks

​Prerequisites

​RCS vs SMS/MMS webhooks

​Webhook URL configuration

​URL priority for outbound status

​Webhook event types

​Delivery status webhooks

​Delivery status flow

​Status reference

​Example: Delivery receipt payload

​Read receipts

​Example: Read receipt payload

​Handling read receipts

​Inbound message webhooks

​Inbound message types

​SDK webhook handling examples

​Building a unified SMS + RCS webhook handler

Telnyx Messaging: RCS — Full Documentation

Getting Started

Agent Registration Quickstart

Register an RCS agent

Prerequisites

Stage 1: Create and test the agent

Create a brand

Submit the brand

Create the agent basics

Submit the agent basics

Add a test device

Stage 2: Submit the agent for launch

Monitor launch status

RCS Getting Started

What is RCS?

Prerequisites

Approval process

1. Create a Messaging Profile

2. Get your API key

3. Send an RCS message

Response

4. Handle incoming messages

RCS vs SMS comparison

Next steps

RCS with AI Assistant

Why RCS + AI Assistant?

How it works

Prerequisites

1. Create an AI Assistant

2. Create a Messaging Profile with AI

3. Link your RCS Agent to the AI-enabled profile

4. Test your AI-powered RCS agent

Best practices

Monitoring and analytics

Pricing

Try it yourself

Next steps

Sending Messages

Send RCS Messages

Prerequisites

Send a text message

Send a rich card

Card options

Send a carousel

Add suggested actions

SMS fallback

RCS vs. SMS/MMS comparison

Related resources

Capabilities & Deeplinks

Query single number

Response examples

Feature reference

Bulk capability query

Send with automatic fallback

RCS Deeplinks

Generate a deeplink

Response

Use deeplinks

Requirements

Related resources

RCS Deeplinks

Quick reference

Receiving Messages

RCS Webhooks

Prerequisites

RCS vs SMS/MMS webhooks

Webhook URL configuration

URL priority for outbound status

Webhook event types

Delivery status webhooks

Delivery status flow

Status reference

Example: Delivery receipt payload

Read receipts

Example: Read receipt payload

Handling read receipts

Inbound message webhooks

Inbound message types

SDK webhook handling examples

Building a unified SMS + RCS webhook handler