Skip to main content
Sticky Sender ensures the same phone number is used every time your application messages a particular recipient. This consistency builds familiarity—your customers see the same number each time, making your messages more recognizable and trustworthy.
Sticky Sender is part of Number Pool settings. You must have Number Pool enabled to use Sticky Sender.

​
When to Use Sticky Sender

Customer Conversations

Maintain consistent sender identity throughout multi-message conversations.

Recurring Notifications

Appointment reminders, delivery updates, and alerts from a familiar number.

Support Interactions

Customers can save your number knowing future messages will come from the same sender.

Brand Recognition

Build trust by ensuring customers recognize your number over time.

​
How It Works

  1. First message: Telnyx selects a number from your pool (using weights, geomatch, or availability)
  2. Mapping created: The recipient-to-sender pairing is stored
  3. Future messages: The same sender is automatically used for that recipient
  4. Mapping expires: After 8 days of no messages, the mapping resets

​
Mapping Behavior

ScenarioBehavior
Message sent within 8 daysSame sender reused, timer resets
No messages for 8+ daysMapping expires, new sender assigned
Sticky Sender disabledAll mappings cleared immediately
Number removed from profileMappings to that number cleared
Sticky number unavailableNew number selected, new mapping created
Compare with Twilio: Sticky Sender works similarly to Twilio’s Messaging Services sticky sender feature. If you’re migrating, the concept is the same—just configure it on your Messaging Profile instead.

​
Prerequisites

​
Configure Sticky Sender

Enable Sticky Sender by updating your Messaging Profile’s number_pool_settings.
The PATCH endpoint merges with your existing configuration—only the fields you include are updated. Your current weights and other Number Pool settings are preserved.
curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "sticky_sender": true
    }
  }'
The response confirms your settings:
{
  "data": {
    "id": "YOUR_PROFILE_ID",
    "record_type": "messaging_profile",
    "name": "My Profile",
    "number_pool_settings": {
      "sticky_sender": true,
      "geomatch": false,
      "long_code_weight": 1,
      "toll_free_weight": 0,
      "skip_unhealthy": false
    }
  }
}

​
Disable Sticky Sender

To disable Sticky Sender, set the sticky_sender field to false. This immediately clears all existing mappings. 
curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "sticky_sender": false
    }
  }'
Disabling Sticky Sender clears all recipient-to-sender mappings. Re-enabling it starts fresh—previous mappings are not restored.

​
Combining with Other Features

Sticky Sender works alongside other Number Pool settings. The priority order for number selection is:
  1. Sticky Sender (if enabled and mapping exists)
  2. Geomatch (if enabled and matching area code available)
  3. Weight distribution (long code vs. toll-free preference)
  4. Skip unhealthy (exclude poor-performing numbers)
When both are enabled:
  • First message: Geomatch selects a number matching the recipient’s area code
  • Future messages: Sticky Sender reuses that same geomatched number
This combination provides both local presence and consistency.
{
  "number_pool_settings": {
    "sticky_sender": true,
    "geomatch": true
  }
}
If a sticky sender mapping points to a number that becomes unhealthy:
  • The mapping is preserved
  • Messages still route through that number (skip_unhealthy doesn’t override sticky mappings)
To force re-selection, temporarily disable and re-enable Sticky Sender to clear mappings.

​
Troubleshooting

Possible causes:
  • Sticky Sender not enabled on the Messaging Profile
  • Previous mapping expired (8+ days since last message)
  • A phone number was removed from the profile
Solutions:
  1. Verify Sticky Sender is enabled in your profile settings
  2. Send messages more frequently to prevent mapping expiration
  3. Check that all expected numbers are still assigned to the profile
Cause: Sticky Sender preserves existing mappings—adding new numbers doesn’t affect recipients who already have mappings.Solution: If you want recipients to potentially use new numbers, temporarily disable Sticky Sender to clear mappings, then re-enable it. New messages will be distributed across all available numbers.
Retrieve your Messaging Profile to see current settings:
curl "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data.number_pool_settings'
Response:
{
  "sticky_sender": true,
  "geomatch": false,
  "long_code_weight": 1,
  "toll_free_weight": 0,
  "skip_unhealthy": false
}

​
Next Steps

Number Pool

Learn about number pool configuration and weights

Geomatch

Match sender to recipient geography

Send Messages

Send your first message with Number Pool

API Reference

View full Messaging Profile API details