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 Send a text message The simplest RCS message — plain text with optional suggested replies:
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?" } } }'
Send a rich card Rich cards display media, text, and action buttons in an interactive format:
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" } } ] } } } } } }'
Card options Property Values Description card_orientationVERTICAL, HORIZONTALCard layout direction thumbnail_image_alignmentLEFT, RIGHTImage position (horizontal cards only) media.heightSHORT, MEDIUM, TALLImage display height
Send a carousel Display multiple cards in a swipeable carousel — ideal for product listings:
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:
Suggested replies
URL actions
Dial actions
Location actions
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 -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" } }'
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
RCS Getting Started Set up your RCS agent and get approved by Google.
RCS Capabilities Check device RCS capability before sending.
RCS Webhooks Handle inbound RCS messages and delivery events.
RCS API Reference Full API reference for RCS messaging.
