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

Open SidemenuAPI Reference
API Reference
Close Sidemenu

Messaging Profiles

List all messaging profileslistMessagingProfiles

get https://api.telnyx.com/v2/messaging_profiles

List all messaging profiles

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/messaging_profiles?page[number]=1&page[size]=20"
Parameters
In query
page[number]
integer (1)
optional

The page number to load

Default: 1
page[size]
integer (1 - 250)
optional

The size of the page

Default: 20
Responses
200

A paginated array of Messaging Profiles

default

Unexpected error

Success Response
{
  "data": [
    {
      "created_at": "2019-01-23T18:10:02.574Z",
      "enabled": true,
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Profile for Messages",
      "number_pool_settings": {
        "geomatch": false,
        "long_code_weight": 2,
        "skip_unhealthy": false,
        "sticky_sender": true,
        "toll_free_weight": 10
      },
      "record_type": "messaging_profile",
      "updated_at": "2019-01-23T18:10:02.574Z",
      "url_shortener_settings": {
        "domain": "example.ex",
        "prefix": "cmpny",
        "replace_blacklist_only": true,
        "send_webhooks": false
      },
      "v1_secret": "rP1VamejkU2v0qIUxntqLW2c",
      "webhook_api_version": "2",
      "webhook_failover_url": "https://backup.example.com/hooks",
      "webhook_url": "https://www.example.com/hooks",
      "whitelisted_destinations": [
        "US"
      ]
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Create a messaging profilecreateMessagingProfile

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

Create a messaging profile

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"enabled":true,"name":"My name"}' \
  https://api.telnyx.com/v2/messaging_profiles
Parameters
In body
name
string
required

A user friendly name for the messaging profile.

enabled
boolean
optional

Specifies whether the messaging profile is enabled or not.

Default: true
number_pool_settings
object
optional

Number Pool allows you to send messages from a pool of numbers of different types, assigning weights to each type. The pool consists of all the long code and toll free numbers assigned to the messaging profile. To disable this feature, set the object field to `null`.

Default: null
Example: { "geomatch": false, "long_code_weight": 1, "skip_unhealthy": true, "sticky_sender": false, "toll_free_weight": 10 }
url_shortener_settings
object
optional

The URL shortener feature allows automatic replacement of URLs that were generated using a public URL shortener service. Some examples include bit.do, bit.ly, goo.gl, ht.ly, is.gd, ow.ly, rebrand.ly, t.co, tiny.cc, and tinyurl.com. Such URLs are replaced with with links generated by Telnyx. The use of custom links can improve branding and message deliverability. To disable this feature, set the object field to `null`.

Default: null
Example: { "domain": "example.ex", "prefix": "", "replace_blacklist_only": true, "send_webhooks": false }
webhook_api_version
string
optional

Determines which webhook format will be used, Telnyx API v1, v2, or a legacy 2010-04-01 format.

Default: "2"
Options: [ "1", "2", "2010-04-01" ]
webhook_failover_url
string (url)
optional

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

Default: ""
webhook_url
string (url)
optional

The URL where webhooks related to this messaging profile will be sent.

Default: ""
Responses
200

Expected messaging profile response to a valid request

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2019-01-23T18:10:02.574Z",
    "enabled": true,
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Profile for Messages",
    "number_pool_settings": {
      "geomatch": false,
      "long_code_weight": 2,
      "skip_unhealthy": false,
      "sticky_sender": true,
      "toll_free_weight": 10
    },
    "record_type": "messaging_profile",
    "updated_at": "2019-01-23T18:10:02.574Z",
    "url_shortener_settings": {
      "domain": "example.ex",
      "prefix": "cmpny",
      "replace_blacklist_only": true,
      "send_webhooks": false
    },
    "v1_secret": "rP1VamejkU2v0qIUxntqLW2c",
    "webhook_api_version": "2",
    "webhook_failover_url": "https://backup.example.com/hooks",
    "webhook_url": "https://www.example.com/hooks",
    "whitelisted_destinations": [
      "US"
    ]
  }
}
Expected Webhooks
delivery Update
{
  "data": {
    "event_type": "message.sent",
    "id": "string",
    "occurred_at": "string",
    "payload": {
      "completed_at": "string",
      "cost": {
        "amount": "string",
        "currency": "string"
      },
      "direction": "outbound",
      "encoding": "string",
      "errors": [
        {
          "code": "string",
          "detail": "string",
          "meta": "object",
          "source": {
            "parameter": "string",
            "pointer": "string"
          },
          "title": "string"
        }
      ],
      "from": {
        "carrier": "string",
        "line_type": "Wireline",
        "phone_number": "string"
      },
      "id": "string",
      "media": [
        {
          "content_type": "string",
          "sha256": "string",
          "size": "integer",
          "url": "string"
        }
      ],
      "messaging_profile_id": "string",
      "parts": "integer",
      "received_at": "string",
      "record_type": "message",
      "sent_at": "string",
      "subject": "string",
      "tags": [
        "string"
      ],
      "text": "string",
      "to": [
        {
          "carrier": "string",
          "line_type": "Wireline",
          "phone_number": "string",
          "status": "queued"
        }
      ],
      "type": "SMS",
      "valid_until": "string",
      "webhook_failover_url": "string",
      "webhook_url": "string"
    },
    "record_type": "event"
  }
}
inbound Message
{
  "data": {
    "event_type": "message.received",
    "id": "string",
    "occurred_at": "string",
    "payload": {
      "completed_at": null,
      "cost": null,
      "direction": "inbound",
      "encoding": "GSM-7",
      "errors": [],
      "from": {
        "carrier": "T-MOBILE USA, INC.",
        "line_type": "Wireless",
        "phone_number": "+18665550001",
        "status": "delivered"
      },
      "id": "7ee4241c-f127-47e5-9c34-3aac291f8058",
      "media": [],
      "messaging_profile_id": "0f512bda-ae1e-4597-8e11-e5f5686b97d3",
      "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": "TELNYX LLC",
          "line_type": "VoIP",
          "phone_number": "+18445550001",
          "status": "delivered"
        }
      ],
      "type": "SMS",
      "valid_until": null,
      "webhook_failover_url": "https://backup.example.com/hooks",
      "webhook_url": "https://www.example.com/hooks"
    },
    "record_type": "event"
  }
}
replaced Link Click
{
  "data": {
    "message_id": "string",
    "record_type": "link_clicked",
    "time_clicked": "string",
    "to": "string",
    "url": "link_clicked"
  }
}

Retrieve a messaging profileretrieveMessagingProfile

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

Retrieve a messaging profile

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/messaging_profiles/{id}"
Parameters
In path
id
string (uuid)
required

The id of the messaging profile to retrieve

Responses
200

Expected messaging profile response to a valid request

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2019-01-23T18:10:02.574Z",
    "enabled": true,
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Profile for Messages",
    "number_pool_settings": {
      "geomatch": false,
      "long_code_weight": 2,
      "skip_unhealthy": false,
      "sticky_sender": true,
      "toll_free_weight": 10
    },
    "record_type": "messaging_profile",
    "updated_at": "2019-01-23T18:10:02.574Z",
    "url_shortener_settings": {
      "domain": "example.ex",
      "prefix": "cmpny",
      "replace_blacklist_only": true,
      "send_webhooks": false
    },
    "v1_secret": "rP1VamejkU2v0qIUxntqLW2c",
    "webhook_api_version": "2",
    "webhook_failover_url": "https://backup.example.com/hooks",
    "webhook_url": "https://www.example.com/hooks",
    "whitelisted_destinations": [
      "US"
    ]
  }
}

Update a messaging profileupdateMessagingProfile

patch https://api.telnyx.com/v2/messaging_profiles/{id}

Update a messaging profile

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"enabled":true,"name":"Profile for Messages"}' \
  https://api.telnyx.com/v2/messaging_profiles/{id}
Parameters
In path
id
string (uuid)
required

The id of the messaging profile to retrieve

In body
enabled
boolean
optional

Specifies whether the messaging profile is enabled or not.

name
string
optional

A user friendly name for the messaging profile.

number_pool_settings
object
optional

Number Pool allows you to send messages from a pool of numbers of different types, assigning weights to each type. The pool consists of all the long code and toll free numbers assigned to the messaging profile. To disable this feature, set the object field to `null`.

Default: null
Example: { "geomatch": false, "long_code_weight": 1, "skip_unhealthy": true, "sticky_sender": false, "toll_free_weight": 10 }
url_shortener_settings
object
optional

The URL shortener feature allows automatic replacement of URLs that were generated using a public URL shortener service. Some examples include bit.do, bit.ly, goo.gl, ht.ly, is.gd, ow.ly, rebrand.ly, t.co, tiny.cc, and tinyurl.com. Such URLs are replaced with with links generated by Telnyx. The use of custom links can improve branding and message deliverability. To disable this feature, set the object field to `null`.

Default: null
Example: { "domain": "example.ex", "prefix": "", "replace_blacklist_only": true, "send_webhooks": false }
v1_secret
string
optional

Secret used to authenticate with v1 endpoints.

webhook_api_version
string
optional

Determines which webhook format will be used, Telnyx API v1, v2, or a legacy 2010-04-01 format.

Options: [ "1", "2", "2010-04-01" ]
webhook_failover_url
string (url)
optional

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

webhook_url
string (url)
optional

The URL where webhooks related to this messaging profile will be sent.

whitelisted_destinations
array of string
optional

Destinations to which the messaging profile is allowed to send. If set to `null`, all destinations will be allowed. Setting a value of `["*"]` has the equivalent effect. The elements in the list must be valid ISO 3166-1 alpha-2 country codes.

Responses
200

Expected messaging profile response to a valid request

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2019-01-23T18:10:02.574Z",
    "enabled": true,
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Profile for Messages",
    "number_pool_settings": {
      "geomatch": false,
      "long_code_weight": 2,
      "skip_unhealthy": false,
      "sticky_sender": true,
      "toll_free_weight": 10
    },
    "record_type": "messaging_profile",
    "updated_at": "2019-01-23T18:10:02.574Z",
    "url_shortener_settings": {
      "domain": "example.ex",
      "prefix": "cmpny",
      "replace_blacklist_only": true,
      "send_webhooks": false
    },
    "v1_secret": "rP1VamejkU2v0qIUxntqLW2c",
    "webhook_api_version": "2",
    "webhook_failover_url": "https://backup.example.com/hooks",
    "webhook_url": "https://www.example.com/hooks",
    "whitelisted_destinations": [
      "US"
    ]
  }
}

Delete a messaging profiledeleteMessagingProfile

delete https://api.telnyx.com/v2/messaging_profiles/{id}

Delete a messaging profile

curl -X DELETE \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/messaging_profiles/{id}"
Parameters
In path
id
string (uuid)
required

The id of the messaging profile to retrieve

Responses
200

Expected messaging profile response to a valid request

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2019-01-23T18:10:02.574Z",
    "enabled": true,
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Profile for Messages",
    "number_pool_settings": {
      "geomatch": false,
      "long_code_weight": 2,
      "skip_unhealthy": false,
      "sticky_sender": true,
      "toll_free_weight": 10
    },
    "record_type": "messaging_profile",
    "updated_at": "2019-01-23T18:10:02.574Z",
    "url_shortener_settings": {
      "domain": "example.ex",
      "prefix": "cmpny",
      "replace_blacklist_only": true,
      "send_webhooks": false
    },
    "v1_secret": "rP1VamejkU2v0qIUxntqLW2c",
    "webhook_api_version": "2",
    "webhook_failover_url": "https://backup.example.com/hooks",
    "webhook_url": "https://www.example.com/hooks",
    "whitelisted_destinations": [
      "US"
    ]
  }
}

List all phone numbers associated with a messaging profilelistMessagingProfilePhoneNumbers

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

List all phone numbers associated with a messaging profile

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/messaging_profiles/{id}/phone_numbers?page[number]=1&page[size]=20"
Parameters
In query
page[number]
integer (1)
optional

The page number to load

Default: 1
page[size]
integer (1 - 250)
optional

The size of the page

Default: 20
In path
id
string (uuid)
required

The id of the messaging profile to retrieve

Responses
200

Paginated array of phone numbers associated with the messaging profile

default

Unexpected error

Success Response
{
  "data": [
    {
      "country_code": "US",
      "created_at": "2019-01-23T18:10:02.574Z",
      "eligible_messaging_products": [
        "A2P"
      ],
      "features": {
        "mms": null,
        "sms": {
          "domestic_two_way": true,
          "international_inbound": true,
          "international_outbound": true
        }
      },
      "health": {
        "inbound_outbound_ratio": 0.43,
        "message_count": 122,
        "spam_ratio": 0.06,
        "success_ratio": 0.94
      },
      "id": "+18665550001",
      "messaging_product": "A2P",
      "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "phone_number": "+18005550001",
      "record_type": "messaging_phone_number",
      "traffic_type": "A2P",
      "type": "toll-free",
      "updated_at": "2019-01-23T18:10:02.574Z"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

List all short codes associated with a messaging profilelistMessagingProfileShortCodes

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

List all short codes associated with a messaging profile

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/messaging_profiles/{id}/short_codes?page[number]=1&page[size]=20"
Parameters
In query
page[number]
integer (1)
optional

The page number to load

Default: 1
page[size]
integer (1 - 250)
optional

The size of the page

Default: 20
In path
id
string (uuid)
required

The id of the messaging profile to retrieve

Responses
200

Paginated array of short codes associated with the messaging profile

default

Unexpected error

Success Response
{
  "data": [
    {
      "country_code": "US",
      "created_at": "2019-01-23T18:10:02.574Z",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "record_type": "short_code",
      "short_code": "12345",
      "updated_at": "2019-01-23T18:10:02.574Z"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

List high-level messaging profile metricslistMessagingProfileMetrics

get https://api.telnyx.com/v2/messaging_profile_metrics

List high-level messaging profile metrics

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/messaging_profile_metrics?page[number]=1&page[size]=20"
Parameters
In query
page[number]
integer (1)
optional

The page number to load

Default: 1
page[size]
integer (1 - 250)
optional

The size of the page

Default: 20
id
string (uuid)
optional

The id of the messaging profile(s) to retrieve

time_frame
string
optional

The timeframe for which you'd like to retrieve metrics.

Default: "24h"
Options: [ "1h", "3h", "24h", "3d", "7d", "30d" ]
Responses
200

Paginated array of high-level metrics for messaging profiles

default

Unexpected error

Success Response
{
  "data": [
    {
      "inbound": {
        "received": 850
      },
      "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "outbound": {
        "delivered": 990,
        "errors": 0.01,
        "sent": 1000
      },
      "phone_numbers": 250,
      "record_type": "messaging_profile_metrics"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Get detailed messaging metrics for a messaging profilegetMessagingProfileDetailedMetrics

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

Get detailed messaging metrics for a messaging profile

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/messaging_profiles/{id}/metrics?time_frame=24h"
Parameters
In path
id
string (uuid)
required

The id of the messaging profile to retrieve

In query
time_frame
string
optional

The timeframe for which you'd like to retrieve metrics.

Default: "24h"
Options: [ "1h", "3h", "24h", "3d", "7d", "30d" ]
Responses
200

Detailed messaging metrics for the messaging profile

default

Unexpected error

Success Response
{
  "data": {
    "detailed": [
      {
        "metrics": [
          {
            "delivered": 990,
            "errors": 0.01,
            "label": "longcode",
            "received": 750,
            "sent": 1000
          }
        ],
        "timestamp": "2019-01-23T18:10:02.574Z"
      }
    ],
    "overview": {
      "inbound": {
        "received": 850
      },
      "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "outbound": {
        "delivered": 990,
        "errors": 0.01,
        "sent": 1000
      },
      "phone_numbers": 250,
      "record_type": "messaging_profile_metrics"
    }
  }
}

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