Messaging Profiles Overview

Understand Telnyx messaging profiles — the central configuration for your messaging numbers, webhooks, features, and spend limits.

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

Setting	Description	Default
Webhook URL	Where inbound messages and delivery status events are sent	None (required)
Number Pool	Distribute messages across multiple numbers automatically	Disabled
Sticky Sender	Keep the same sender number for each recipient	Disabled
Geomatch	Select sender numbers based on geographic proximity	Disabled
Smart Encoding	Replace Unicode characters with GSM-7 equivalents	Disabled
MMS Transcoding	Automatically resize media for carrier limits	Disabled
Spend Limit	Daily spend cap to prevent unexpected costs	Disabled
URL Shortening	Shorten URLs in outbound messages	Disabled

---

Create a messaging profile

curl

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

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

Webhook configuration

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.

Setting	Description
webhook_url	Primary URL for all messaging events
webhook_failover_url	Backup URL if primary fails
webhook_api_version	API version for webhook payloads (1 or 2)

See Webhooks for implementation details.

Number Pool

When enabled, messages sent from the profile automatically distribute across all assigned numbers. This increases throughput and helps avoid carrier filtering.

Settings:

Setting	Description
geomatch	Select sender number closest to recipient’s area code
sticky_sender	Reuse the same sender number for each recipient
skip_unhealthy	Skip numbers with delivery issues
long_code_weight	Weight for long code selection (default: 1)
toll_free_weight	Weight for toll-free selection (default: 1)

See Number Pool for details.

Smart Encoding

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.

MMS Transcoding

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.

Spend 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.

URL Shortening

Automatically shorten URLs in outbound messages. Shortened URLs use your configured domain and track click-through rates.

Setting	Description
url_shortener_settings.domain	Custom domain for shortened URLs
url_shortener_settings.prefix	URL prefix
url_shortener_settings.replace_blacklist_only	Only replace blacklisted URLs
url_shortener_settings.send_webhooks	Send click-tracking webhooks

---

Assign phone numbers

After creating a profile, assign phone numbers to it:

curl

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

Transactional (OTP, alerts)

{
  "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.

Marketing campaigns

{
  "name": "Marketing Campaigns",
  "webhook_url": "https://api.example.com/webhooks/marketing",
  "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": "500.00"
}

Best for: Promotional messages, newsletters. Number pool for throughput. Higher spend limit for volume.

Support / Conversational

{
  "name": "Customer Support",
  "webhook_url": "https://api.example.com/webhooks/support",
  "number_pool_settings": {
    "sticky_sender": true
  },
  "smart_encoding": true
}

Best for: Two-way conversations. Sticky sender ensures customers always see the same number.

---

Related resources

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.