Skip to main content
A messaging profile is the central configuration object for your Telnyx messaging setup. It groups your phone numbers, defines webhook URLs, and controls features like number pooling, smart encoding, and spend limits. Every phone number you use for messaging must be assigned to a messaging profile.

​
What a messaging profile controls

SettingDescriptionDefault
Webhook URLWhere inbound messages and delivery status events are sentNone (required)
Number PoolDistribute messages across multiple numbers automaticallyDisabled
Sticky SenderKeep the same sender number for each recipientDisabled
GeomatchSelect sender numbers based on geographic proximityDisabled
Smart EncodingReplace Unicode characters with GSM-7 equivalentsDisabled
MMS TranscodingAutomatically resize media for carrier limitsDisabled
Spend LimitDaily spend cap to prevent unexpected costsDisabled
URL ShorteningShorten URLs in outbound messagesDisabled

​
Create a messaging profile

curl -X POST https://api.telnyx.com/v2/messaging_profiles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "My Messaging Profile",
    "webhook_url": "https://example.com/webhooks/messaging",
    "webhook_failover_url": "https://example.com/webhooks/messaging/failover"
  }'
You can also create messaging profiles in the Telnyx Portal under Messaging > Messaging Profiles.

​
Configure profile features

Update an existing profile to enable features: 
curl -X PATCH https://api.telnyx.com/v2/messaging_profiles/{profile_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "geomatch": true,
      "sticky_sender": true,
      "skip_unhealthy": true
    },
    "smart_encoding": true,
    "mms_transcoding": true,
    "daily_spend_limit_enabled": true,
    "daily_spend_limit": "50.00"
  }'

​
Profile features explained

Every messaging profile needs a webhook URL to receive:
  • Inbound messages — SMS/MMS received on your numbers
  • Delivery status updates — sent, delivered, failed, etc.
  • Spend limit notifications — when daily limits are reached
Configure a failover URL as a backup in case your primary webhook is unreachable.
SettingDescription
webhook_urlPrimary URL for all messaging events
webhook_failover_urlBackup URL if primary fails
webhook_api_versionAPI version for webhook payloads (1 or 2)
See Webhooks for implementation details.
When enabled, messages sent from the profile automatically distribute across all assigned numbers. This increases throughput and helps avoid carrier filtering.Settings:
SettingDescription
geomatchSelect sender number closest to recipient’s area code
sticky_senderReuse the same sender number for each recipient
skip_unhealthySkip numbers with delivery issues
long_code_weightWeight for long code selection (default: 1)
toll_free_weightWeight for toll-free selection (default: 1)
See Number Pool for details.
Automatically replaces Unicode characters (curly quotes, em dashes, etc.) with GSM-7 equivalents to keep messages in the more efficient encoding and reduce segment counts.A single curly quote can switch an entire message from GSM-7 (160 chars/segment) to UTF-16 (70 chars/segment), more than doubling costs.See Smart Encoding for the full character substitution reference.
Automatically resizes images and videos to meet carrier size limits before delivery. When enabled:
  • Images are converted to JPEG
  • Videos are converted to H.264 MP4
  • Animated GIFs are not resized
See MMS Media & Transcoding for carrier size limits.
Set a daily spending cap to prevent unexpected costs. When the limit is reached:
  • New messages are rejected with error 40333
  • A webhook notification is sent
  • An email alert is sent to your account
The limit resets at midnight UTC daily.See Spend Limits for configuration and webhook handling.
Automatically shorten URLs in outbound messages. Shortened URLs use your configured domain and track click-through rates.
SettingDescription
url_shortener_settings.domainCustom domain for shortened URLs
url_shortener_settings.prefixURL prefix
url_shortener_settings.replace_blacklist_onlyOnly replace blacklisted URLs
url_shortener_settings.send_webhooksSend click-tracking webhooks

​
Assign phone numbers

After creating a profile, assign phone numbers to it: 
curl -X POST https://api.telnyx.com/v2/messaging_profiles/{profile_id}/phone_numbers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"phone_number_id": "your_phone_number_id"}'
You can also assign numbers to profiles in the Telnyx Portal by editing a messaging profile and selecting numbers.

​
Common configurations

{
  "name": "Transactional Messages",
  "webhook_url": "https://api.example.com/webhooks/sms",
  "smart_encoding": true,
  "daily_spend_limit_enabled": true,
  "daily_spend_limit": "100.00"
}
Best for: OTP codes, account alerts, order confirmations. Low volume, high priority. Smart encoding reduces costs.

Number Pool

Distribute messages across multiple numbers for higher throughput.

Smart Encoding

Reduce SMS costs by replacing Unicode with GSM-7 characters.

Spend Limits

Set daily spend caps to prevent unexpected costs.

Webhooks

Receive inbound messages and delivery status updates.