Receiving RCS Webhooks for Telnyx Messaging
You can choose to be notified about events on your RCS Agent by configuring webhooks.
Telnyx supports notifications for the following event types:
Requirements For enabling RCS notifications
For this mechanism to work, you’ll need a publicly accessible HTTP server that can receive our webhook requests at one or more specified URLs. We highly recommend using HTTPS (instead of HTTP). This tutorial walks through setting up a basic application for receiving webhooks.
Hierarchy of URLs
If webhooks are provided in the request body, we will use those, otherwise if the profile has webhooks, we’ll use those. If neither has webhooks, we won’t attempt a webhook delivery.
Important Differences with SMS and MMS
- RCS sends the message as JSON
- RCS uses a snake-case JSON schema based on Google's RCS API
- RCS sends media as links in the message body
- SMS and MMS send the message as a string under the
"text": "Hello there!" - MMS sends media as a list under the
mediakey in the webhook using Telnyx's messaging media schema.
See this tutorial for further details on SMS and MMS webhooks.
RCS delivery status updates
The Telnyx Messaging Services will attempt to notify you about each status update based on the hierarchy of URLs above.
Delivery status Payload
Here is an example of a webhook event where a delivery receipt is returned to the sender after sending a message through to a T-Mobile long code:
{
"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"
}
}
Delivery statuses
| Delivery Status | Description |
| queued | The message is queued up on Telnyx's side. |
| sending | The message is currently being sent to an upstream provider. |
| sent | The message has been sent to the upstream provider. |
| delivered | The upstream provider has confirmed delivery of the message. |
| sending_failed | Telnyx has failed to send the message to the upstream provider. Please reach out to our support if you have received this status. |
| delivery_failed | The upstream provider has failed to send the message to the receiver. Please reach out to our support if you have received this status. |
| delivery_unconfirmed | There is no indication whether or not the message has reached the receiver. Please reach out to our support if you have received this status |
Incoming messages to your numbers
Telnyx gives you the option of using webhooks to notify you of new inbound messages to your RCS Agent. This feature is enabled by configuring the incoming webhooks on the associated RCS Agent.
Incoming message Payload
Here is an example of a webhook event where a RCS Agent receives a text message from a T-Mobile long code:
{
"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!"
},
"completed_at": null,
"cost": null,
"direction": "inbound",
"errors": [],
"from": {
"carrier": "T-Mobile USA",
"line_type": "long_code",
"phone_number": "+1312500000",
"status": "webhook_delivered"
},
"id": "84cca175-9755-4859-b67f-4730d7f58aa3",
"messaging_profile_id": "740572b6-099c-44a1-89b9-6c92163bc68d",
"organization_id": "47a530f8-4362-4526-829b-bcee17fd9f7a",
"received_at": "2024-12-09T20:16:07.503+00:00",
"record_type": "message",
"sent_at": null,
"tags": [],
"to": [
{
"agent_id": "e4448a5c0670c2a9",
"agent_name": "My RCS Agent"
}
],
"type": "RCS",
"valid_until": null,
"webhook_failover_url": null,
"webhook_url": "http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
},
"record_type": "event"
},
"meta": {
"attempt": 1,
"delivered_to": "http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
}
}
Incoming messages types
Telnyx supports the following inbound message types:
Text
{
"data": {
...
"payload": {
"body": {
"text": "Hello from Telnyx!"
},
...
}
}
File
{
"data": {
...
"payload": {
"body": {
"user_file": {
"payload": {
"file_name": "d387f5f4fa07c989855d1308eb026bd73ad0b9c4b2af5102672b9cb4e5a89579.jfif",
"file_size_bytes": 179099,
"file_uri": "https://rcs-inbound.us-central-1.telnyxcloudstorage.com/rcs/9be89cbfecc6aea796ab8e8f276a1efe/d387f5f4fa07c989855d1308eb026bd73ad0b9c4b2af5102672b9cb4e5a89579.jfif",
"mime_type": "image/jpeg"
},
"thumbnail": {
"file_name": "695f01a428ab1dbd1555bbb719d736f4a4c9f695cd9338b00408047184097600.jfif",
"file_size_bytes": 12074,
"file_uri": "https://rcs-inbound.us-central-1.telnyxcloudstorage.com/rcs/9be89cbfecc6aea796ab8e8f276a1efe/695f01a428ab1dbd1555bbb719d736f4a4c9f695cd9338b00408047184097600.jfif",
"mime_type": "image/jpeg"
}
}
},
...
}
}
Location
{
"data": {
...
"payload": {
"body": {
"location": {
"latitude": 38.24961321640261,
"longitude": -85.78378468751907
}
},
...
}
}
Suggestion Response
{
"data": {
...
"payload": {
"body": {
"suggestion_response": {
"postback_data": "https://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675",
"text": "Explore the online store"
}
},
...
}
}
Telnyx Webhook IPs
If you use an ACL or Firewall on your network, make sure you whitelist the following subnet(s):
| 192.76.120.192/27 |