openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens Profiles API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Messaging profiles
name: Profiles
paths:
/messaging_profiles:
get:
operationId: ListMessagingProfiles
parameters:
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[name]'
explode: true
in: query
name: filter
schema:
properties:
name:
description: Filter by name
type: string
type: object
style: deepObject
- $ref: '#/components/parameters/PageConsolidated'
- description: Filter profiles by exact name match.
in: query
name: filter[name][eq]
required: false
schema:
type: string
- description: Filter profiles by name containing the given string.
in: query
name: filter[name][contains]
required: false
schema:
type: string
responses:
'200':
$ref: '#/components/responses/ListMessagingProfilesResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: List messaging profiles
tags:
- Profiles
x-endpoint-cost: medium
x-group-parameters: 'true'
x-latency-category: responsive
post:
operationId: CreateMessagingProfile
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessagingProfileRequest'
description: New Messaging Profile object
required: true
responses:
'200':
$ref: '#/components/responses/MessagingProfileResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Create a messaging profile
tags:
- Profiles
x-endpoint-cost: medium
x-latency-category: responsive
/messaging_profiles/{id}:
delete:
operationId: DeleteMessagingProfile
parameters:
- $ref: '#/components/parameters/MessagingProfileId'
responses:
'200':
$ref: '#/components/responses/MessagingProfileResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Delete a messaging profile
tags:
- Profiles
x-latency-category: responsive
get:
operationId: RetrieveMessagingProfile
parameters:
- $ref: '#/components/parameters/MessagingProfileId'
responses:
'200':
$ref: '#/components/responses/MessagingProfileResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Retrieve a messaging profile
tags:
- Profiles
x-latency-category: responsive
patch:
operationId: UpdateMessagingProfile
parameters:
- $ref: '#/components/parameters/MessagingProfileId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMessagingProfileRequest'
description: New Messaging Profile object
required: true
responses:
'200':
$ref: '#/components/responses/MessagingProfileResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Update a messaging profile
tags:
- Profiles
x-latency-category: responsive
/messaging_profiles/{id}/phone_numbers:
get:
operationId: ListProfilePhoneNumbers
parameters:
- $ref: '#/components/parameters/MessagingProfileId'
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
$ref: '#/components/responses/ListMessagingProfilePhoneNumbersResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: List phone numbers associated with a messaging profile
tags:
- Profiles
x-group-parameters: 'true'
x-latency-category: responsive
/messaging_profiles/{id}/short_codes:
get:
operationId: ListProfileShortCodes
parameters:
- $ref: '#/components/parameters/MessagingProfileId'
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
$ref: '#/components/responses/ListMessagingProfileShortCodesResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: List short codes associated with a messaging profile
tags:
- Profiles
x-group-parameters: 'true'
x-latency-category: responsive
components:
responses:
messaging_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors'
description: Unexpected error
ListMessagingProfileShortCodesResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/ShortCode'
type: array
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
title: List Messaging Profile Short Codes Response
type: object
description: Successful response with a list of messaging profile short codes.
ListMessagingProfilesResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/MessagingProfile'
type: array
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
title: List Messaging Profiles Response
type: object
description: Successful response with a list of messaging profiles.
ListMessagingProfilePhoneNumbersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/PhoneNumberWithMessagingSettings'
type: array
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
title: List Messaging Profile Phone Numbers Response
type: object
description: Successful response with a list of messaging profile phone numbers.
MessagingProfileResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/MessagingProfile'
title: Messaging Profile Response
type: object
description: Successful response with details about a messaging profile.
schemas:
MessagingFeatureSet:
description: 'The set of features available for a specific messaging use case (SMS or MMS). Features
can vary depending on the characteristics the phone number, as well as its current
product configuration.
'
example:
domestic_two_way: true
international_inbound: false
international_outbound: true
properties:
domestic_two_way:
description: Send messages to and receive messages from numbers in the same country.
type: boolean
international_inbound:
description: Receive messages from numbers in other countries.
type: boolean
international_outbound:
description: Send messages to numbers in other countries.
type: boolean
required:
- domestic_two_way
- international_inbound
- international_outbound
type:
- object
- 'null'
NumberPoolSettings:
description: '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
properties:
geomatch:
default: false
description: '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.
'
type: boolean
long_code_weight:
description: '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: 1
type: number
skip_unhealthy:
description: '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
type: boolean
sticky_sender:
default: false
description: '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.
'
type: boolean
toll_free_weight:
description: '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: 10
type: number
required:
- toll_free_weight
- long_code_weight
- skip_unhealthy
type:
- object
- 'null'
MessagingProfile:
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
mobile_only: 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
properties:
ai_assistant_id:
description: The AI assistant ID associated with this messaging profile.
type:
- string
- 'null'
alpha_sender:
description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
pattern: ^[A-Za-z0-9 ]{1,11}$
type:
- string
- 'null'
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
format: date-time
readOnly: true
type: string
daily_spend_limit:
description: The maximum amount of money (in USD) that can be spent by this profile before midnight UTC.
pattern: ^[0-9]+(?:\.[0-9]+)?$
type: string
daily_spend_limit_enabled:
description: Whether to enforce the value configured by `daily_spend_limit`.
type: boolean
enabled:
description: Specifies whether the messaging profile is enabled or not.
type: boolean
health_webhook_url:
description: 'DEPRECATED: health check url service checking'
format: url
type:
- string
- 'null'
id:
description: Identifies the type of resource.
format: uuid
readOnly: true
type: string
mms_fall_back_to_sms:
default: false
description: enables SMS fallback for MMS messages.
type: boolean
mms_transcoding:
default: false
description: enables automated resizing of MMS media.
type: boolean
mobile_only:
default: false
description: Send messages only to mobile phone numbers.
type: boolean
name:
description: A user friendly name for the messaging profile.
type: string
number_pool_settings:
$ref: '#/components/schemas/NumberPoolSettings'
organization_id:
description: The organization that owns this messaging profile.
type: string
record_type:
description: Identifies the type of the resource.
enum:
- messaging_profile
readOnly: true
type: string
redaction_enabled:
default: false
description: Indicates whether message content redaction is enabled for this profile.
type: boolean
redaction_level:
default: 2
description: Determines how much information is redacted in messages for privacy or compliance purposes.
type: integer
resource_group_id:
description: The resource group ID associated with this messaging profile.
type:
- string
- 'null'
smart_encoding:
default: false
description: 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.
type: boolean
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
format: date-time
readOnly: true
type: string
url_shortener_settings:
$ref: '#/components/schemas/UrlShortenerSettings'
v1_secret:
description: Secret used to authenticate with v1 endpoints.
type: string
webhook_api_version:
description: Determines which webhook format will be used, Telnyx API v1, v2, or a legacy 2010-04-01 format.
enum:
- '1'
- '2'
- '2010-04-01'
type: string
webhook_failover_url:
description: The failover URL where webhooks related to this messaging profile will be sent if sending to the primary URL fails.
format: url
type:
- string
- 'null'
webhook_url:
description: The URL where webhooks related to this messaging profile will be sent.
format: url
type:
- string
- 'null'
whitelisted_destinations:
description: 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.
items:
description: ISO 3166-1 alpha-2 country code.
pattern: ^[A-Z]{2}$
type: string
type: array
type: object
UpdateMessagingProfileRequest:
example:
enabled: true
name: Updated Profile for Messages
number_pool_settings:
geomatch: false
long_code_weight: 2
skip_unhealthy: false
sticky_sender: true
toll_free_weight: 10
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
properties:
alpha_sender:
description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
pattern: ^[A-Za-z0-9 ]{1,11}$
type:
- string
- 'null'
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
format: date-time
readOnly: true
type: string
daily_spend_limit:
description: The maximum amount of money (in USD) that can be spent by this profile before midnight UTC.
pattern: ^[0-9]+(?:\.[0-9]+)?$
type: string
daily_spend_limit_enabled:
description: Whether to enforce the value configured by `daily_spend_limit`.
type: boolean
enabled:
description: Specifies whether the messaging profile is enabled or not.
type: boolean
id:
description: Identifies the type of resource.
format: uuid
readOnly: true
type: string
mms_fall_back_to_sms:
default: false
description: enables SMS fallback for MMS messages.
type: boolean
mms_transcoding:
default: false
description: enables automated resizing of MMS media.
type: boolean
mobile_only:
default: false
description: Send messages only to mobile phone numbers.
type: boolean
name:
description: A user friendly name for the messaging profile.
type: string
number_pool_settings:
$ref: '#/components/schemas/NumberPoolSettings'
record_type:
description: Identifies the type of the resource.
enum:
- messaging_profile
readOnly: true
type: string
smart_encoding:
default: false
description: 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.
type: boolean
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
format: date-time
readOnly: true
type: string
url_shortener_settings:
$ref: '#/components/schemas/UrlShortenerSettings'
v1_secret:
description: Secret used to authenticate with v1 endpoints.
type: string
webhook_api_version:
description: Determines which webhook format will be used, Telnyx API v1, v2, or a legacy 2010-04-01 format.
enum:
- '1'
- '2'
- '2010-04-01'
type: string
webhook_failover_url:
description: The failover URL where webhooks related to this messaging profile will be sent if sending to the primary URL fails.
format: url
type:
- string
- 'null'
webhook_url:
description: The URL where webhooks related to this messaging profile will be sent.
format: url
type:
- string
- 'null'
whitelisted_destinations:
description: '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.
This field is required if the messaging profile doesn''t have it defined yet.'
items:
description: ISO 3166-1 alpha-2 country code.
pattern: ^[A-Z]{2}$
type: string
type: array
type: object
CreateMessagingProfileRequest:
example:
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
properties:
ai_assistant_id:
description: The AI assistant ID to associate with this messaging profile.
maxLength: 64
type:
- string
- 'null'
alpha_sender:
description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
pattern: ^[A-Za-z0-9 ]{1,11}$
type:
- string
- 'null'
daily_spend_limit:
description: The maximum amount of money (in USD) that can be spent by this profile before midnight UTC.
pattern: ^[0-9]+(?:\.[0-9]+)?$
type: string
daily_spend_limit_enabled:
description: Whether to enforce the value configured by `daily_spend_limit`.
type: boolean
enabled:
default: true
description: Specifies whether the messaging profile is enabled or not.
type: boolean
health_webhook_url:
description: A URL to receive health check webhooks for numbers in this profile.
format: url
type:
- string
- 'null'
mms_fall_back_to_sms:
default: false
description: enables SMS fallback for MMS messages.
type: boolean
mms_transcoding:
default: false
description: enables automated resizing of MMS media.
type: boolean
mobile_only:
default: false
description: Send messages only to mobile phone numbers.
type: boolean
name:
description: A user friendly name for the messaging profile.
type: string
number_pool_settings:
$ref: '#/components/schemas/NumberPoolSettings'
resource_group_id:
description: The resource group ID to associate with this messaging profile.
maxLength: 64
type:
- string
- 'null'
smart_encoding:
default: false
description: 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.
type: boolean
url_shortener_settings:
$ref: '#/components/schemas/UrlShortenerSettings'
webhook_api_version:
default: '2'
description: Determines which webhook format will be used, Telnyx API v1, v2, or a legacy 2010-04-01 format.
enum:
- '1'
- '2'
- '2010-04-01'
type: string
webhook_failover_url:
default: ''
description: The failover URL where webhooks related to this messaging profile will be sent if sending to the primary URL fails.
format: url
type:
- string
- 'null'
webhook_url:
default: ''
description: The URL where webhooks related to this messaging profile will be sent.
format: url
type:
- string
- 'null'
whitelisted_destinations:
description: 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.
items:
description: ISO 3166-1 alpha-2 country code.
pattern: ^[A-Z]{2}$
type: string
type: array
required:
- name
- whitelisted_destinations
type: object
UrlShortenerSettings:
description: '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
properties:
domain:
description: 'One of the domains provided by the Telnyx URL shortener service.
'
example: acct.fyi
type: string
prefix:
description: 'Optional prefix that can be used to identify your brand, and will appear in the Telnyx generated URLs after the domain name.
'
example: ''
type: string
replace_blacklist_only:
description: 'Use the link replacement tool only for links that are specifically blacklisted by Telnyx.
'
example: true
type: boolean
send_webhooks:
description: 'Receive webhooks for when your replaced links are clicked. Webhooks are sent to the webhooks on the messaging profile.
'
example: false
type: boolean
required:
- domain
type:
- object
- 'null'
ShortCode:
example:
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'
tags:
- test_customer
updated_at: '2019-01-23T18:10:02.574Z'
properties:
country_code:
description: ISO 3166-1 alpha-2 country code.
example: US
pattern: ^[A-Z]{2}$
readOnly: true
type: string
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
format: date-time
readOnly: true
type: string
id:
description: Identifies the type of resource.
format: uuid
readOnly: true
type: string
messaging_profile_id:
description: Unique identifier for a messaging profile.
type:
- string
- 'null'
record_type:
description: Identifies the type of the resource.
enum:
- short_code
example: short_code
readOnly: true
type: string
short_code:
description: Short digit sequence used to address messages.
readOnly: true
type: string
tags:
items:
type: string
type:
- array
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
format: date-time
readOnly: true
type: string
required:
- messaging_profile_id
type: object
messaging_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/messaging_Error'
type: array
messaging_PaginationMeta:
properties:
page_number:
example: 2
type: integer
page_size:
example: 25
type: integer
total_pages:
example: 3
type: integer
total_results:
example: 55
type: integer
required:
- total_pages
- total_results
- page_size
- page_number
type: object
messaging_Error:
properties:
code:
type: string
x-format: integer
detail:
type: string
meta:
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
format: json-pointer
type: string
type: object
title:
type: string
required:
- code
- title
PhoneNumberWithMessagingSettings:
example:
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: tollfree
updated_at: '2019-01-23T18:10:02.574Z'
properties:
country_code:
description: ISO 3166-1 alpha-2 country code.
example: US
pattern: ^[A-Z]{2}$
readOnly: true
type: string
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
format: date-time
readOnly: true
type: string
eligible_messaging_products:
description: The messaging products that this number can be registered to use
items:
type: string
readOnly: true
type: array
features:
properties:
mms:
$ref: '#/components/schemas/MessagingFeatureSet'
sms:
$ref: '#/components/schemas/MessagingFeatureSet'
readOnly: true
type: object
health:
$ref: '#/components/schemas/NumberHealthMetrics'
id:
description: Identifies the type of resource.
readOnly: true
type: string
messaging_product:
description: The messaging product that the number is registered to use
example: P2P
type: string
messaging_profile_id:
description: Unique identifier for a messaging profile.
type:
- string
- 'null'
organization_id:
description: The organization that owns this phone number.
type: string
phone_number:
description: +E.164 formatted phone number.
readOnly: true
type: string
x-format: e164
record_type:
description: Identifies the type of the resource.
enum:
- messaging_phone_number
- messaging_settings
example: messaging_settings
readOnly:
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-profiles-api-openapi.yml