Open SidemenuAPI Reference
API Reference
Close Sidemenu

Messaging Profiles

List messaging profileslistMessagingProfiles

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

List 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

Successful response with a list 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 '{"name":"My name","enabled":true}' \
  https://api.telnyx.com/v2/messaging_profiles
Parameters
In body (application/json)
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`.

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

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

Successful response with details about a messaging profile.

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": "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": "40385f64-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": "4000eba1-a0c0-4563-9925-b25e842a7cb6",
      "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
      "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"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://www.example.com/hooks"
  }
}
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",
      "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
      "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

Successful response with details about a messaging profile.

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":"Updated 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 (application/json)
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`.

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

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

Successful response with details about a messaging profile.

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

Successful response with details about a messaging profile.

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 phone numbers associated with a messaging profilelistMessagingProfilePhoneNumbers

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

List 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

Successful response with a list of messaging profile phone numbers.

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": "1293384261075731499",
      "messaging_product": "A2P",
      "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "phone_number": "+18005550001",
      "record_type": "messaging_settings",
      "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 short codes associated with a messaging profilelistMessagingProfileShortCodes

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

List 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

Successful response with a list of messaging profile short codes.

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 messaging profile metricslistMessagingProfileMetrics

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

List 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

Successful response with a list of messaging profile metrics.

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
  }
}

Retrieve messaging profile metricsretrieveMessagingProfileDetailedMetrics

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

Retrieve 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_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

Successful response with details about a messaging profile's metrics.

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?