Create a new messaging profile

POST 
/messaging/profiles

Creates a new messaging profile. In order to use the Telnyx Messaging Services, at least one of your Telnyx SMS-enabled phone numbers needs to be assigned to an existing messaging profile.

Request

application/json

Body

required

name stringrequired

Name/description of messaging profile

incoming_webhook_url string

The URL where webhooks for inbound messages to numbers on this messaging profile will be sent. (Previously called "url".)

incoming_failover_url string

The failover URL where webhooks for inbound messages to numbers on this messaging profile will be sent, if sending to the primary URL fails. (Previously called "failover_url".)

webhook_api_version string

Possible values: [1, 2, 2010-04-01]

Default value: 1

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

whitelisted_destinations string[]

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

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.

alpha_sender string

Possible values: Value must match regular expression ^[A-Za-z0-9 ]{1,11}$

DEPRECATED: Alphanumeric Sender IDs can be set dynamically in the /messages request.

number_pool_settings

object

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.

toll_free_weight numberrequired

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.

long_code_weight numberrequired

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.

skip_unhealthy booleanrequired

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.

sticky_sender boolean

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.

geomatch boolean

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.

url_shortener_settings

object

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.

domain stringrequired

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

prefix string

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

replace_blacklist_only boolean

Default value: true

Only replace URLs with domains that are blocked by Telnyx.

send_webhooks string

Send webhooks when your replaced links are clicked. Webhooks are sent to the URLs configured on the messaging profile.

Responses

201: Newly created messaging profile

application/json

• Schema
• Example (from schema)

Schema

user_id uuid

ID of user who owns the messaging profile

profile_id uuid

ID of messaging profile

name string

A user friendly name for the messaging profile.

enabled boolean

Default value: true

Specifies whether the messaging profile is enabled or not.

secret string

Messaging profile's current secret, which is used to authenticate requests to 'sms.telnyx.com' and validate the signature on webhooks (if using API v1 webhooks).

incoming_webhook_url string

The URL where webhooks for inbound messages to numbers on this messaging profile will be sent. (Previously called "url".)

incoming_failover_url string

The failover URL where webhooks for inbound messages to numbers on this messaging profile will be sent, if sending to the primary URL fails. (Previously called "failover_url".)

webhook_api_version string

Possible values: [1, 2, 2010-04-01]

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

whitelisted_destinations string[]

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

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.

alpha_sender string

Possible values: Value must match regular expression ^[A-Za-z0-9 ]{1,11}$

DEPRECATED: Alphanumeric Sender IDs can be set dynamically in the /messages request.

number_pool_settings

object

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.

toll_free_weight numberrequired

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.

long_code_weight numberrequired

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.

skip_unhealthy booleanrequired

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.

sticky_sender boolean

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.

geomatch boolean

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.

url_shortener_settings

object

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.

domain stringrequired

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

prefix string

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

replace_blacklist_only boolean

Default value: true

Only replace URLs with domains that are blocked by Telnyx.

send_webhooks string

Send webhooks when your replaced links are clicked. Webhooks are sent to the URLs configured on the messaging profile.

{
  "user_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "profile_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "name": "string",
  "enabled": true,
  "secret": "rq789onm321yxzkjihfEdcBAmmijjoik",
  "incoming_webhook_url": "https://www.example.com/hooks",
  "incoming_failover_url": "https://www.example.com/callbacks",
  "webhook_api_version": "1",
  "whitelisted_destinations": [
    "AR",
    "BR",
    "IE",
    "US"
  ],
  "alpha_sender": "Telnyx",
  "number_pool_settings": {
    "toll_free_weight": 10,
    "long_code_weight": 1,
    "skip_unhealthy": true,
    "sticky_sender": false,
    "geomatch": false
  },
  "url_shortener_settings": {
    "domain": "acct.fyi",
    "prefix": "",
    "replace_blacklist_only": "",
    "send_webhooks": ""
  }
}

Loading...