Send an RCS message
POST/messsages/rcs
Send an RCS message
Request
- application/json
Body
required
RCS message body
Array [
]
Array [
Array [
]
]
Array [
]
RCS Agent ID
Phone number in +E.164 format
A valid messaging profile ID
Possible values: [RCS]
Message type - must be set to "RCS"
The URL where webhooks related to this message will be sent.
agent_message
object
required
content_message
object
suggestions
object[]
List of suggested actions and replies
reply
object
Text that is shown in the suggested reply (maximum 25 characters)
Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
action
object
When tapped, initiates the corresponding native action on the device.
Text that is shown in the suggested action. Maximum 25 characters.
Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
Fallback URL to use if a client doesn't support a suggested action. Fallback URLs open in new browser windows. Maximum 2048 characters.
dial_action
object
Opens the user's default dialer app with the agent-specified phone number filled in.
Phone number in +E.164 format
Opens the user's default dialer app with the agent-specified phone number filled in.
view_location_action
object
Opens the user's default map app and selects the agent-specified location.
lat_long
object
The latitude in degrees. It must be in the range [-90.0, +90.0].
The longitude in degrees. It must be in the range [-180.0, +180.0].
The label of the pin dropped
query string (Android only)
Opens the user's default map app and selects the agent-specified location.
create_calendar_event_action
object
Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.
Event title. Maximum 100 characters.
Event description. Maximum 500 characters.
Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.
open_url_action
object
Opens the user's default web browser app to the specified URL.
Possible values: [OPEN_URL_APPLICATION_UNSPECIFIED, BROWSER, WEBVIEW]
URL open application, browser or webview.
Possible values: [WEBVIEW_VIEW_MODE_UNSPECIFIED, FULL, HALF, TALL]
Accessbility description for webview.
Opens the user's default web browser app to the specified URL.
Opens the RCS app's location chooser so the user can pick a location to send back to the agent.
When tapped, initiates the corresponding native action on the device.
List of suggested actions and replies
Text (maximum 3072 characters)
rich_card
object
carousel_card
object
Carousel of cards.
Possible values: [CARD_WIDTH_UNSPECIFIED, SMALL, MEDIUM]
The width of the cards in the carousel.
card_contents
object[]
required
The list of contents for each card in the carousel. A carousel can have a minimum of 2 cards and a maximum 10 cards.
Title of the card (at most 200 characters)
Description of the card (at most 2000 characters)
media
object
A media file within a rich card.
Possible values: [HEIGHT_UNSPECIFIED, SHORT, MEDIUM, TALL]
The height of the media within a rich card with a vertical layout. For a standalone card with horizontal layout, height is not customizable, and this field is ignored.
content_info
object
Publicly reachable URL of the file.
Publicly reachable URL of the thumbnail. Maximum size of 100 kB.
If set the URL content will not be cached.
A media file within a rich card.
suggestions
object[]
List of suggestions to include in the card. Maximum 10 suggestions.
reply
object
Text that is shown in the suggested reply (maximum 25 characters)
Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
action
object
When tapped, initiates the corresponding native action on the device.
Text that is shown in the suggested action. Maximum 25 characters.
Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
Fallback URL to use if a client doesn't support a suggested action. Fallback URLs open in new browser windows. Maximum 2048 characters.
dial_action
object
Opens the user's default dialer app with the agent-specified phone number filled in.
Phone number in +E.164 format
Opens the user's default dialer app with the agent-specified phone number filled in.
view_location_action
object
Opens the user's default map app and selects the agent-specified location.
lat_long
object
The latitude in degrees. It must be in the range [-90.0, +90.0].
The longitude in degrees. It must be in the range [-180.0, +180.0].
The label of the pin dropped
query string (Android only)
Opens the user's default map app and selects the agent-specified location.
create_calendar_event_action
object
Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.
Event title. Maximum 100 characters.
Event description. Maximum 500 characters.
Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.
open_url_action
object
Opens the user's default web browser app to the specified URL.
Possible values: [OPEN_URL_APPLICATION_UNSPECIFIED, BROWSER, WEBVIEW]
URL open application, browser or webview.
Possible values: [WEBVIEW_VIEW_MODE_UNSPECIFIED, FULL, HALF, TALL]
Accessbility description for webview.
Opens the user's default web browser app to the specified URL.
Opens the RCS app's location chooser so the user can pick a location to send back to the agent.
When tapped, initiates the corresponding native action on the device.
List of suggestions to include in the card. Maximum 10 suggestions.
The list of contents for each card in the carousel. A carousel can have a minimum of 2 cards and a maximum 10 cards.
Carousel of cards.
standalone_card
object
Standalone card
Possible values: [CARD_ORIENTATION_UNSPECIFIED, HORIZONTAL, VERTICAL]
Orientation of the card.
Possible values: [THUMBNAIL_IMAGE_ALIGNMENT_UNSPECIFIED, LEFT, RIGHT]
Image preview alignment for standalone cards with horizontal layout.
card_content
object
required
Title of the card (at most 200 characters)
Description of the card (at most 2000 characters)
media
object
A media file within a rich card.
Possible values: [HEIGHT_UNSPECIFIED, SHORT, MEDIUM, TALL]
The height of the media within a rich card with a vertical layout. For a standalone card with horizontal layout, height is not customizable, and this field is ignored.
content_info
object
Publicly reachable URL of the file.
Publicly reachable URL of the thumbnail. Maximum size of 100 kB.
If set the URL content will not be cached.
A media file within a rich card.
suggestions
object[]
List of suggestions to include in the card. Maximum 10 suggestions.
reply
object
Text that is shown in the suggested reply (maximum 25 characters)
Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
action
object
When tapped, initiates the corresponding native action on the device.
Text that is shown in the suggested action. Maximum 25 characters.
Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
Fallback URL to use if a client doesn't support a suggested action. Fallback URLs open in new browser windows. Maximum 2048 characters.
dial_action
object
Opens the user's default dialer app with the agent-specified phone number filled in.
Phone number in +E.164 format
Opens the user's default dialer app with the agent-specified phone number filled in.
view_location_action
object
Opens the user's default map app and selects the agent-specified location.
lat_long
object
The latitude in degrees. It must be in the range [-90.0, +90.0].
The longitude in degrees. It must be in the range [-180.0, +180.0].
The label of the pin dropped
query string (Android only)
Opens the user's default map app and selects the agent-specified location.
create_calendar_event_action
object
Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.
Event title. Maximum 100 characters.
Event description. Maximum 500 characters.
Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.
open_url_action
object
Opens the user's default web browser app to the specified URL.
Possible values: [OPEN_URL_APPLICATION_UNSPECIFIED, BROWSER, WEBVIEW]
URL open application, browser or webview.
Possible values: [WEBVIEW_VIEW_MODE_UNSPECIFIED, FULL, HALF, TALL]
Accessbility description for webview.
Opens the user's default web browser app to the specified URL.
Opens the RCS app's location chooser so the user can pick a location to send back to the agent.
When tapped, initiates the corresponding native action on the device.
List of suggestions to include in the card. Maximum 10 suggestions.
Standalone card
content_info
object
Publicly reachable URL of the file.
Publicly reachable URL of the thumbnail. Maximum size of 100 kB.
If set the URL content will not be cached.
event
object
RCS Event to send to the recipient
Possible values: [TYPE_UNSPECIFIED, IS_TYPING, READ]
RCS Event to send to the recipient
Timestamp in UTC of when this message is considered expired
Duration in seconds ending with 's'
sms_fallback
object
Phone number in +E.164 format
Text (maximum 3072 characters)
mms_fallback
object
Phone number in +E.164 format
Subject of the message
List of media URLs
Text
Responses
200: Successful operation
- application/json
default: Unexpected error
- application/json
Request samples
curl -L 'https://api.telnyx.com/v2/messsages/rcs' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"agent_id": "Agent007",
"to": "+13125551234",
"messaging_profile_id": "string",
"type": "RCS",
"webhook_url": "string",
"agent_message": {
"content_message": {
"suggestions": [
{
"reply": {
"text": "string",
"postback_data": "string"
},
"action": {
"text": "Hello world",
"postback_data": "string",
"fallback_url": "string",
"dial_action": {
"phone_number": "+13125551234"
},
"view_location_action": {
"lat_long": {
"latitude": 41.8,
"longitude": -87.6
},
"label": "string",
"query": "string"
},
"create_calendar_event_action": {
"start_time": "2024-10-02T15:01:23Z",
"end_time": "2024-10-02T15:02:31Z",
"title": "string",
"description": "string"
},
"open_url_action": {
"url": "http://example.com",
"application": "BROWSER",
"webview_view_mode": "HALF",
"description": "string"
},
"share_location_action": {}
}
}
],
"text": "Hello world!",
"rich_card": {
"carousel_card": {
"card_width": "SMALL",
"card_contents": [
{
"title": "Elephant",
"description": "string",
"media": {
"height": "MEDIUM",
"content_info": {
"file_url": "https://example.com/elephant.jpg",
"thumbnail_url": "string",
"force_refresh": true
}
},
"suggestions": [
{
"reply": {
"text": "string",
"postback_data": "string"
},
"action": {
"text": "Hello world",
"postback_data": "string",
"fallback_url": "string",
"dial_action": {
"phone_number": "+13125551234"
},
"view_location_action": {
"lat_long": {
"latitude": 41.8,
"longitude": -87.6
},
"label": "string",
"query": "string"
},
"create_calendar_event_action": {
"start_time": "2024-10-02T15:01:23Z",
"end_time": "2024-10-02T15:02:31Z",
"title": "string",
"description": "string"
},
"open_url_action": {
"url": "http://example.com",
"application": "BROWSER",
"webview_view_mode": "HALF",
"description": "string"
},
"share_location_action": {}
}
}
]
}
]
},
"standalone_card": {
"card_orientation": "HORIZONTAL",
"thumbnail_image_alignment": "LEFT",
"card_content": {
"title": "Elephant",
"description": "string",
"media": {
"height": "MEDIUM",
"content_info": {
"file_url": "https://example.com/elephant.jpg",
"thumbnail_url": "string",
"force_refresh": true
}
},
"suggestions": [
{
"reply": {
"text": "string",
"postback_data": "string"
},
"action": {
"text": "Hello world",
"postback_data": "string",
"fallback_url": "string",
"dial_action": {
"phone_number": "+13125551234"
},
"view_location_action": {
"lat_long": {
"latitude": 41.8,
"longitude": -87.6
},
"label": "string",
"query": "string"
},
"create_calendar_event_action": {
"start_time": "2024-10-02T15:01:23Z",
"end_time": "2024-10-02T15:02:31Z",
"title": "string",
"description": "string"
},
"open_url_action": {
"url": "http://example.com",
"application": "BROWSER",
"webview_view_mode": "HALF",
"description": "string"
},
"share_location_action": {}
}
}
]
}
}
},
"content_info": {
"file_url": "https://example.com/elephant.jpg",
"thumbnail_url": "string",
"force_refresh": true
}
},
"event": {
"event_type": "IS_TYPING"
},
"expire_time": "2024-10-02T15:01:23Z",
"ttl": "10.5s"
},
"sms_fallback": {
"from": "+13125551234",
"text": "Hello world!"
},
"mms_fallback": {
"from": "+13125551234",
"subject": "Test Message",
"media_urls": [
"string"
],
"text": "Hello world!"
}
}'
Response samples
{
"data": {
"record_type": "message",
"direction": "outbound",
"id": "4031938e-60e4-4235-a8dd-0b1c55a23e7a",
"type": "RCS",
"organization_id": "9f61d8e1-7687-4d6d-9cae-9ff682985983",
"messaging_profile_id": "4001781e-626f-4a41-a914-b1b682150f94",
"from": {
"agent_id": "Agent007",
"carrier": "Telnyx",
"agent_name": "Test Agent"
},
"to": [
{
"phone_number": "+13125551234",
"status": "queued",
"carrier": "Verizon Wireless",
"line_type": "Wireless"
}
],
"body": {
"content_message": {
"suggestions": [
{
"reply": {
"text": "string",
"postback_data": "string"
},
"action": {
"text": "Hello world",
"postback_data": "string",
"fallback_url": "string",
"dial_action": {
"phone_number": "+13125551234"
},
"view_location_action": {
"lat_long": {
"latitude": 41.8,
"longitude": -87.6
},
"label": "string",
"query": "string"
},
"create_calendar_event_action": {
"start_time": "2024-10-02T15:01:23Z",
"end_time": "2024-10-02T15:02:31Z",
"title": "string",
"description": "string"
},
"open_url_action": {
"url": "http://example.com",
"application": "BROWSER",
"webview_view_mode": "HALF",
"description": "string"
},
"share_location_action": {}
}
}
],
"text": "Hello world!",
"rich_card": {
"carousel_card": {
"card_width": "SMALL",
"card_contents": [
{
"title": "Elephant",
"description": "string",
"media": {
"height": "MEDIUM",
"content_info": {
"file_url": "https://example.com/elephant.jpg",
"thumbnail_url": "string",
"force_refresh": true
}
},
"suggestions": [
{
"reply": {
"text": "string",
"postback_data": "string"
},
"action": {
"text": "Hello world",
"postback_data": "string",
"fallback_url": "string",
"dial_action": {
"phone_number": "+13125551234"
},
"view_location_action": {
"lat_long": {
"latitude": 41.8,
"longitude": -87.6
},
"label": "string",
"query": "string"
},
"create_calendar_event_action": {
"start_time": "2024-10-02T15:01:23Z",
"end_time": "2024-10-02T15:02:31Z",
"title": "string",
"description": "string"
},
"open_url_action": {
"url": "http://example.com",
"application": "BROWSER",
"webview_view_mode": "HALF",
"description": "string"
},
"share_location_action": {}
}
}
]
}
]
},
"standalone_card": {
"card_orientation": "HORIZONTAL",
"thumbnail_image_alignment": "LEFT",
"card_content": {
"title": "Elephant",
"description": "string",
"media": {
"height": "MEDIUM",
"content_info": {
"file_url": "https://example.com/elephant.jpg",
"thumbnail_url": "string",
"force_refresh": true
}
},
"suggestions": [
{
"reply": {
"text": "string",
"postback_data": "string"
},
"action": {
"text": "Hello world",
"postback_data": "string",
"fallback_url": "string",
"dial_action": {
"phone_number": "+13125551234"
},
"view_location_action": {
"lat_long": {
"latitude": 41.8,
"longitude": -87.6
},
"label": "string",
"query": "string"
},
"create_calendar_event_action": {
"start_time": "2024-10-02T15:01:23Z",
"end_time": "2024-10-02T15:02:31Z",
"title": "string",
"description": "string"
},
"open_url_action": {
"url": "http://example.com",
"application": "BROWSER",
"webview_view_mode": "HALF",
"description": "string"
},
"share_location_action": {}
}
}
]
}
}
},
"content_info": {
"file_url": "https://example.com/elephant.jpg",
"thumbnail_url": "string",
"force_refresh": true
}
},
"event": {
"event_type": "IS_TYPING"
},
"expire_time": "2024-10-02T15:01:23Z",
"ttl": "10.5s"
},
"encoding": "utf-8",
"received_at": "2024-07-29T15:51:28.071Z"
}
}
{
"errors": [
{
"code": "string",
"title": "string",
"detail": "string",
"source": {
"pointer": "string",
"parameter": "string"
},
"meta": {}
}
]
}