Sign in
Profiles

Create a messaging profile

Creates a messaging profile that controls outbound sender selection, webhook delivery, and inbound message handling for associated numbers and short codes.

post/messaging_profiles

Request body

namestring required

A user friendly name for the messaging profile.

whitelisted_destinationsstring[] 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.

enabledboolean

Specifies whether the messaging profile is enabled or not.

webhook_urlstring url nullable

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

webhook_failover_urlstring url nullable

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

webhook_api_version'1' | '2' | '2010-04-01'

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

alpha_senderstring nullable

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

daily_spend_limitstring

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

daily_spend_limit_enabledboolean

Whether to enforce the value configured by daily_spend_limit.

mms_fall_back_to_smsboolean

enables SMS fallback for MMS messages.

mms_transcodingboolean

enables automated resizing of MMS media.

mobile_onlyboolean

Send messages only to mobile phone numbers.

smart_encodingboolean

Enables automatic character encoding optimization for SMS messages. When enabled, the system automatically selects the most efficient encoding (GSM-7 or UCS-2) based on message content to maximize character limits and minimize costs.

resource_group_idstring nullable

The resource group ID to associate with this messaging profile.

health_webhook_urlstring url nullable

A URL to receive health check webhooks for numbers in this profile.

ai_assistant_idstring nullable

The AI assistant ID to associate with this messaging profile.

Example request

{
  "name": "My name",
  "enabled": true,
  "webhook_url": "https://www.example.com/hooks",
  "webhook_failover_url": "https://backup.example.com/hooks",
  "webhook_api_version": "2",
  "number_pool_settings": {
    "toll_free_weight": 10,
    "long_code_weight": 1,
    "skip_unhealthy": true,
    "sticky_sender": false,
    "geomatch": false
  },
  "url_shortener_settings": {
    "domain": "example.ex",
    "prefix": "",
    "replace_blacklist_only": true,
    "send_webhooks": false
  },
  "whitelisted_destinations": [
    "US"
  ]
}

Response

Successful response with details about a messaging profile.

Example response

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

Changes

Changed in 3 of the 99 revisions of this API.72

  • a6a61a29ecdd2See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 34 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 1571b0380bd73See the full diff
    • ▲

      the response's body type changed from object to no type for status

      response-body-type-changed

    • ▲

      the / response's property type changed from object to no type for status

      response-property-type-changed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to no format for status

      response-property-type-changed

    This revision also has 64 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 8f5f4e5379944See the full diff
    • ▲

      the response's body type changed from no type to object for status

      response-body-type-changed

    • ▲

      the / response's property type changed from no type to object for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from no format to int32 for status

      response-property-type-changed

    • ▲

      the /// response's property format changed from json-pointer to no format for status

      response-property-type-changed

    This revision also has 41 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 99 revisions, 1 has no diff computed.