Messages
Send a message' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
Send a message with a Phone Number, Alphanumeric Sender ID, Short Code or Number Pool.
This endpoint allows you to send a message with any messaging resource. Current messaging resources include: long-code, short-code, number-pool, and alphanumeric-sender-id.
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '{
"from": "+18665552368",
"to": "+18665552367",
"text": "Hello, World!"
}' \
https://api.telnyx.com/v2/messages
In body
Receiving address (+E.164 formatted phone number or short code).
Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.
Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code). **Required if sending with a phone number, short code, or alphanumeric sender ID.**
A list of media URLs. The total media size must be less than 1 MB. **Required for MMS**
Unique identifier for a messaging profile. **Required if sending via number pool or with an alphanumeric sender ID.**
Subject of multimedia message
Message body (i.e., content) as a non-empty string. **Required for SMS**
The protocol for sending the message, either SMS or MMS.
If the profile this number is associated with has webhooks, use them for delivery notifications. If webhooks are also specified on the message itself, they will be attempted first, then those on the profile.
The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
The URL where webhooks related to this message will be sent.
Successful response with details about a message.
Unexpected error
- JSON
- Schema
{
"data": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
}
}
- JSON
- Schema
{
"data": {
"event_type": "message.sent",
"id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
"occurred_at": "date-time",
"payload": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
},
"record_type": "event"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '{
"from": "+18665552368",
"to": "+18665552367",
"text": "Hello, World!"
}' \
https://api.telnyx.com/v2/messages/long_code
In body
Phone number, in +E.164 format, used to send the message.
Receiving address (+E.164 formatted phone number or short code).
Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.
A list of media URLs. The total media size must be less than 1 MB. **Required for MMS**
Subject of multimedia message
Message body (i.e., content) as a non-empty string. **Required for SMS**
The protocol for sending the message, either SMS or MMS.
If the profile this number is associated with has webhooks, use them for delivery notifications. If webhooks are also specified on the message itself, they will be attempted first, then those on the profile.
The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
The URL where webhooks related to this message will be sent.
Successful response with details about a message.
Unexpected error
- JSON
- Schema
{
"data": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
}
}
- JSON
- Schema
{
"data": {
"event_type": "message.sent",
"id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
"occurred_at": "date-time",
"payload": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
},
"record_type": "event"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '{
"messaging_profile_id": "uuid",
"to": "+18665552367",
"text": "Hello, World!"
}' \
https://api.telnyx.com/v2/messages/number_pool
In body
Unique identifier for a messaging profile.
Receiving address (+E.164 formatted phone number or short code).
Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.
A list of media URLs. The total media size must be less than 1 MB. **Required for MMS**
Subject of multimedia message
Message body (i.e., content) as a non-empty string. **Required for SMS**
The protocol for sending the message, either SMS or MMS.
If the profile this number is associated with has webhooks, use them for delivery notifications. If webhooks are also specified on the message itself, they will be attempted first, then those on the profile.
The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
The URL where webhooks related to this message will be sent.
Successful response with details about a message.
Unexpected error
- JSON
- Schema
{
"data": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
}
}
- JSON
- Schema
{
"data": {
"event_type": "message.sent",
"id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
"occurred_at": "date-time",
"payload": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
},
"record_type": "event"
}
}
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '{
"from": "34001",
"to": "+18665552367",
"text": "Hello, World!"
}' \
https://api.telnyx.com/v2/messages/short_code
In body
Phone number, in +E.164 format, used to send the message.
Receiving address (+E.164 formatted phone number or short code).
Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.
A list of media URLs. The total media size must be less than 1 MB. **Required for MMS**
Subject of multimedia message
Message body (i.e., content) as a non-empty string. **Required for SMS**
The protocol for sending the message, either SMS or MMS.
If the profile this number is associated with has webhooks, use them for delivery notifications. If webhooks are also specified on the message itself, they will be attempted first, then those on the profile.
The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
The URL where webhooks related to this message will be sent.
Successful response with details about a message.
Unexpected error
- JSON
- Schema
{
"data": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
}
}
- JSON
- Schema
{
"data": {
"event_type": "message.sent",
"id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
"occurred_at": "date-time",
"payload": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
},
"record_type": "event"
}
}
Retrieve a message' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
Note: This API endpoint can only retrieve messages that are no older than 10 days since their creation. If you require messages older than this, please generate an MDR report.
- cURL
- Python
- Ruby
- Node
- PHP
- Java
- .NET
curl -X GET \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--globoff "https://api.telnyx.com/v2/messages/{id}"
In path
The id of the message
Successful response with details about a message.
Unexpected error
- JSON
- Schema
{
"data": {
"completed_at": null,
"cost": null,
"direction": "outbound",
"encoding": "GSM-7",
"errors": [],
"from": {
"carrier": "TELNYX LLC",
"line_type": "VoIP",
"phone_number": "+18445550001"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"media": [
{
"content_type": null,
"sha256": null,
"size": null,
"url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png"
}
],
"messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6",
"parts": 1,
"received_at": "2019-01-23T18:10:02.574Z",
"record_type": "message",
"sent_at": null,
"subject": "From Telnyx!",
"tags": [
"Greetings"
],
"text": "Hello, World!",
"to": [
{
"carrier": "T-MOBILE USA, INC.",
"line_type": "Wireless",
"phone_number": "+18665550001",
"status": "queued"
}
],
"type": "MMS",
"valid_until": null,
"webhook_failover_url": "https://backup.example.com/hooks",
"webhook_url": "https://www.example.com/hooks"
}
}