Create a messaging profile

curl --location --request POST '/messaging_profiles' \ --header 'Content-Type: application/json' \ --data-raw '{ "enabled": true, "name": "My name", "number_pool_settings": { "geomatch": false, "long_code_weight": 1, "skip_unhealthy": true, "sticky_sender": false, "toll_free_weight": 10 }, "url_shortener_settings": { "domain": "example.ex", "prefix": "", "replace_blacklist_only": true, "send_webhooks": false }, "webhook_api_version": "2", "webhook_failover_url": "https://backup.example.com/hooks", "webhook_url": "https://www.example.com/hooks", "whitelisted_destinations": [ "US" ] }'

{ "data": { "created_at": "2019-01-23T18:10:02.574Z", "daily_spend_limit": "100.00", "daily_spend_limit_enabled": false, "enabled": true, "health_webhook_url": null, "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "mms_fall_back_to_sms": false, "mms_transcoding": false, "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", "redaction_enabled": false, "redaction_level": 2, "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" ] } }

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

alpha_sender

string | null

optional

The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.

Match pattern:

^[A-Za-z0-9 ]{1,11}$

daily_spend_limit

string

optional

The maximum amount of money (in USD) that can be spent by this profile before midnight UTC.

Match pattern:

^[0-9]+(?:\.[0-9]+)?$

daily_spend_limit_enabled

boolean

optional

Whether to enforce the value configured by daily_spend_limit.

enabled

boolean

optional

Specifies whether the messaging profile is enabled or not.

Default:

true

mms_fall_back_to_sms

boolean

optional

enables SMS fallback for MMS messages.

Default:

false

mms_transcoding

boolean

optional

enables automated resizing of MMS media.

Default:

false

name

string

required

A user friendly name for the messaging profile.

number_pool_settings

object (NumberPoolSettings) | null

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}

geomatch

boolean

optional

If set to true, Number Pool will try to choose a sending number with the same area code as the destination
number. If there are no such numbers available, a nunber with a different area code will be chosen. Currently
only NANP numbers are supported.

Default:

false

long_code_weight

number

required

Defines the probability weight for a Long Code number to be selected when sending a message.
The higher the weight the higher the probability. The sum of the weights for all number types
does not necessarily need to add to 100. Weight must be a non-negative number, and when equal
to zero it will remove the number type from the pool.

Example:

skip_unhealthy

boolean

required

If set to true all unhealthy numbers will be automatically excluded from the pool.
Health metrics per number are calculated on a regular basis, taking into account the deliverability
rate and the amount of messages marked as spam by upstream carriers.
Numbers with a deliverability rate below 25% or spam ratio over 75% will be considered unhealthy.

Example:

true

sticky_sender

boolean

optional

If set to true, Number Pool will try to choose the same sending number for all messages to a particular
recipient. If the sending number becomes unhealthy and skip_unhealthy is set to true, a new
number will be chosen.

Default:

false

toll_free_weight

number

required

Defines the probability weight for a Toll Free number to be selected when sending a message.
The higher the weight the higher the probability. The sum of the weights for all number types
does not necessarily need to add to 100. Weight must be a non-negative number, and when equal
to zero it will remove the number type from the pool.

Example:

url_shortener_settings

object (UrlShortenerSettings) | null

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}

domain

string

required

One of the domains provided by the Telnyx URL shortener service.

Example:

acct.fyi

prefix

string

optional

Optional prefix that can be used to identify your brand, and will appear in the Telnyx generated URLs after the domain name.

Example:

replace_blacklist_only

boolean

optional

Use the link replacement tool only for links that are specifically blacklisted by Telnyx.

Example:

true

send_webhooks

boolean

optional

Receive webhooks for when your replaced links are clicked. Webhooks are sent to the webhooks on the messaging profile.

Example:

false

webhook_api_version

enum<string>

optional

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

Allowed values:

122010-04-01

Default:

webhook_failover_url

string <url> | null

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

optional

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

Default:

whitelisted_destinations

array[string]

required

Destinations to which the messaging profile is allowed to send. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to ["*"] all destinations will be allowed.

Examples

Responses

🟢200OK

application/json

Successful response with details about a messaging profile.

Body

data

object (MessagingProfile)

optional

Example:

{"created_at":"2019-01-23T18:10:02.574Z","daily_spend_limit":"100.00","daily_spend_limit_enabled":false,"enabled":true,"health_webhook_url":null,"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","mms_fall_back_to_sms":false,"mms_transcoding":false,"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","redaction_enabled":false,"redaction_level":2,"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"]}

alpha_sender

string | null

optional

The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.

Match pattern:

^[A-Za-z0-9 ]{1,11}$

created_at

string <date-time>

read-onlyoptional

ISO 8601 formatted date indicating when the resource was created.

daily_spend_limit

string

optional

The maximum amount of money (in USD) that can be spent by this profile before midnight UTC.

Match pattern:

^[0-9]+(?:\.[0-9]+)?$

daily_spend_limit_enabled

boolean

optional

Whether to enforce the value configured by daily_spend_limit.

enabled

boolean

optional

Specifies whether the messaging profile is enabled or not.

string <uuid>

read-onlyoptional

Identifies the type of resource.

mms_fall_back_to_sms

boolean

optional

enables SMS fallback for MMS messages.

Default:

false

mms_transcoding

boolean

optional

enables automated resizing of MMS media.

Default:

false

name

string

optional

A user friendly name for the messaging profile.

number_pool_settings

object (NumberPoolSettings) | null

optional

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}

record_type

enum<string>

read-onlyoptional

Identifies the type of the resource.

Allowed value:

messaging_profile

updated_at

string <date-time>

read-onlyoptional

ISO 8601 formatted date indicating when the resource was updated.

url_shortener_settings

object (UrlShortenerSettings) | null

optional

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

enum<string>

optional

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

Allowed values:

122010-04-01

webhook_failover_url

string <url> | null

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

optional

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

whitelisted_destinations

array[string]

optional

Destinations to which the messaging profile is allowed to send. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to ["*"], all destinations will be allowed.

🔴500Server Error