This is the API V2 documentation. To switch out of beta revert back to our API V1.

Telnyx DevelopersAPI v2
Sign inTelnyx Developers
Open Menu
DocsAPI ReferenceJoin Slack Community
Create an AccountSign in
Questions on setup? Talk to our experts
Open SidemenuAPI Reference
API Reference
Close Sidemenu

Messages

Send a messagecreateMessage

post https://api.telnyx.com/v2/messages

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 -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
Parameters
In body
to
string (address)
required

Receiving address (+E.164 formatted phone number or short code).

Example: "+E.164"
auto_detect
boolean
optional

Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.

Default: false
from
string (address)
optional

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.**

media_urls
array of string
optional

A list of media URLs. The total media size must be less than 1 MB. **Required for MMS**

messaging_profile_id
string
optional

Unique identifier for a messaging profile. **Required if sending via number pool or with an alphanumeric sender ID.**

subject
string
optional

Subject of multimedia message

text
string
optional

Message body (i.e., content) as a non-empty string. **Required for SMS**

type
string
optional

The protocol for sending the message, either SMS or MMS.

Options: [ "SMS", "MMS" ]
use_profile_webhooks
boolean
optional

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.

Default: true
webhook_failover_url
string (url)
optional

The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.

webhook_url
string (url)
optional

The URL where webhooks related to this message will be sent.

Responses
200

Successful response with details about a message.

default

Unexpected error

Success Response
{
  "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"
  }
}
Expected Webhooks
delivery Update
{
  "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"
  }
}

Send a long code messagecreateLongCodeMessage

post https://api.telnyx.com/v2/messages/long_code

Send a long code message

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
Parameters
In body
from
string (address)
required

Phone number, in +E.164 format, used to send the message.

to
string (address)
required

Receiving address (+E.164 formatted phone number or short code).

Example: "+E.164"
auto_detect
boolean
optional

Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.

Default: false
media_urls
array of string
optional

A list of media URLs. The total media size must be less than 1 MB. **Required for MMS**

subject
string
optional

Subject of multimedia message

text
string
optional

Message body (i.e., content) as a non-empty string. **Required for SMS**

type
string
optional

The protocol for sending the message, either SMS or MMS.

Options: [ "SMS", "MMS" ]
use_profile_webhooks
boolean
optional

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.

Default: true
webhook_failover_url
string (url)
optional

The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.

webhook_url
string (url)
optional

The URL where webhooks related to this message will be sent.

Responses
200

Successful response with details about a message.

default

Unexpected error

Success Response
{
  "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"
  }
}
Expected Webhooks
delivery Update
{
  "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"
  }
}

Send a message using number poolcreateNumberPoolMessage

post https://api.telnyx.com/v2/messages/number_pool

Send a message using number pool

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
Parameters
In body
messaging_profile_id
string
required

Unique identifier for a messaging profile.

to
string (address)
required

Receiving address (+E.164 formatted phone number or short code).

Example: "+E.164"
auto_detect
boolean
optional

Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.

Default: false
media_urls
array of string
optional

A list of media URLs. The total media size must be less than 1 MB. **Required for MMS**

subject
string
optional

Subject of multimedia message

text
string
optional

Message body (i.e., content) as a non-empty string. **Required for SMS**

type
string
optional

The protocol for sending the message, either SMS or MMS.

Options: [ "SMS", "MMS" ]
use_profile_webhooks
boolean
optional

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.

Default: true
webhook_failover_url
string (url)
optional

The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.

webhook_url
string (url)
optional

The URL where webhooks related to this message will be sent.

Responses
200

Successful response with details about a message.

default

Unexpected error

Success Response
{
  "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"
  }
}
Expected Webhooks
delivery Update
{
  "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"
  }
}

Send a short code messagecreateShortCodeMessage

post https://api.telnyx.com/v2/messages/short_code

Send a short code message

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
Parameters
In body
from
string (address)
required

Phone number, in +E.164 format, used to send the message.

to
string (address)
required

Receiving address (+E.164 formatted phone number or short code).

Example: "+E.164"
auto_detect
boolean
optional

Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.

Default: false
media_urls
array of string
optional

A list of media URLs. The total media size must be less than 1 MB. **Required for MMS**

subject
string
optional

Subject of multimedia message

text
string
optional

Message body (i.e., content) as a non-empty string. **Required for SMS**

type
string
optional

The protocol for sending the message, either SMS or MMS.

Options: [ "SMS", "MMS" ]
use_profile_webhooks
boolean
optional

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.

Default: true
webhook_failover_url
string (url)
optional

The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.

webhook_url
string (url)
optional

The URL where webhooks related to this message will be sent.

Responses
200

Successful response with details about a message.

default

Unexpected error

Success Response
{
  "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"
  }
}
Expected Webhooks
delivery Update
{
  "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 messageretrieveMessage

get https://api.telnyx.com/v2/messages/{id}

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.Telnyx Developers

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}"
Parameters
In path
id
string (uuid)
required

The id of the message

Responses
200

Successful response with details about a message.

default

Unexpected error

Success Response
{
  "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"
  }
}
Previous: Overview

Was this section helpful?was-this-page-helpful