Skip to main content

Retrieve all 'TN's

GET 
/messaging/numbers

Retrieve messaging settings for all phone numbers. In terminology specific to Telnyx Messaging: this endpoint returns a list of TNs.

When a request to https://api.telnyx.com/messaging/numbers is successful, the response payload will contain one TN (represented as a JSON object) per phone number – as shown in the example below.

[
  ...
  {
    "num": "+13129457420",
    "user_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
    "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "last_updated": 1521566241103171,
    "country_code": null,
    "campaign_id": null,
    "num_country": "USA"
  },
  ...
]

For fuller details on a TN, request the resource directly. For example, https://api.telnyx.com/messaging/numbers/%2B13129457420 would return the following:

{
  "num": "+13129457420",
  "user_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  "last_updated": 1521566241103171,
  "country_code": null,
  "campaign_id": null,
  "num_country": "USA",
  "traffic_type": "A2P",
  "num_type": "long-code",
  "sms": {
    "enabled": true,
    "domestic_two_way": true,
    "international_inbound": true,
    "international_outbound": true
  },
  "mms": null
}
TN ​

In the Telnyx Messaging API, the TN resource tracks the messaging settings that can be configured on your phone numbers.

To enable messaging on a phone number, update its messaging TN to associate it with one of your existing messaging profiles.

Note that not all phone numbers are messaging-capable. In such cases, when you attempt to enable messaging on the TN, you will receive a 40323 error.

Configuration & usage overview:

  • profile_id is the only TN field that you need to configure.
  • Configuring a profile-level webhook is like setting a default callback URL for phone numbers assigned to that profile.

Field-specific information:

Field(s)Notes

user_id
profile_id

[format]

Default: ""

UUID returned as a string.

e.g., "c51c89d9-68ad-4db2-a471-cf622d21c40d"

profile_id

[usage]

ID of the messaging profile to which the phone number is current assigned.

In order to use the Telnyx Messaging Services, you need to create at least one messaging profile.

An SMS-capable phone number is SMS-enabled only when it is assigned to an existing messaging profile.

last_updated

Updated at time in Unix time in microseconds,
returned as a 16-digit integer
(1 μs = 10-6 sec).

When unknown, last_updated = 0.

e.g., 1521566241103171 is Tue, 20 Mar 2018 17:17:21 UTC

country_code

DEPRECATED

campaign_id

The messaging campaign ID associated with the shortcode.

Only used for shortcodes.

num_country

The ISO 3166-1 alpha-3 country code of the country of origin for the number.

traffic_type

The messaging product type the number is registered with.

Possible values, "A2P" and "P2P"

num_type

The type of number.

Possible values include: "long-code", "toll-free", "short-code", etc.

sms

A nullable object that lists the possible SMS features of the number.

If present and enabled is true, SMS is enabled on the number.

If present and enabled is false, SMS is capable, but not enabled on the number.

If not present, the number is not SMS capable.

mms

A nullable object that lists the possible MMS features of the number.

If present and enabled is true, MMS is enabled on the number.

If present and enabled is false, MMS is capable, but not enabled on the number.

If not present, the number is not MMS capable.

Messaging Products

There are different use cases for needing to send SMS and MMS messages. To more closely match with your needs, Telnyx offers 2 messaging product types: A2P (application to person) and P2P (person to person).

A2P traffic is geared mainly for high volume one way traffic. Appointment reminders, temporary password tokens, promotional offers, etc.

P2P traffic is more conversational traffic with high levels of engagement from the end device. Customer support, chatbots, etc.

When you first enable messaging on a number, Telnyx will automatically default to a specific messaging product based on the type of number you are messaging enabling. After a certain threshold of usage, Telnyx will offer users the ability to request a messaging product change on a number. Telnyx will verify the number exhibits the behavior of the requested messaging product type. If it does not, the request will be rejected.

Requesting a Messaging Product Change

For a detailed guide on requesting a messaging product see our guide: Requesting a Messaging Product Change


Retrieve all 'TN's: request-response scheme ​

Request ​

Query Parameters

    has_messaging_profile boolean

    Filter results to include only phone numbers with an assigned messaging profile

Responses ​

200: List of 'TN's

Schema

  • Array [

    • num stringrequired

    +E.164 formatted phone number

    user_id uuidrequired

    ID of user who owns the phone number

    profile_id uuid

    ID of messaging profile, or '' if unassigned

    last_updated integer

    Possible values: Value must match regular expression ^(([0-9]{16})|0)$

    Default value: 0

    Updated at time (Unix time in microseconds), or '0' if unknown

    country_code string

    Number's Country Code

    campaign_id string

    The messaging campaign ID associated with the short-code

    num_country string

    Possible values: Value must match regular expression ^(([A-Z]{3}))$

    The ISO 3166-1 alpha-3 country code of the country of origin for the number

  • ]

Request samples

curl -L 'https://sms.telnyx.com/messaging/numbers' \
-H 'Accept: application/json'

Response samples

[
  {
    "num": "+13129457420",
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "last_updated": 1521566241103171,
    "country_code": "string",
    "campaign_id": "string",
    "num_country": "USA"
  }
]