Skip to main content
Before a phone number can send or receive messages through Telnyx, it must be assigned to a messaging profile and have messaging enabled. This guide covers the complete workflow — from purchasing a number to configuring it for messaging, assigning it to profiles, and troubleshooting common issues.

​
Prerequisites

​
Overview

Every phone number used for messaging needs:
  1. A messaging profile — Controls webhook URLs, inbound settings, and features like number pool or sticky sender
  2. Messaging enabled — The number must have messaging capabilities activated
  3. Regulatory compliance — Depending on the number type, you may need 10DLC registration or toll-free verification

​
Step 1: List messaging-capable numbers

Find numbers on your account that support messaging: 
curl -X GET "https://api.telnyx.com/v2/messaging_phone_numbers?page[size]=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Step 2: Assign a number to a messaging profile

Link a phone number to a messaging profile to configure its webhook URLs and messaging behavior. 
curl -X PATCH "https://api.telnyx.com/v2/messaging_phone_numbers/+15551234567" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": "400174af-0a13-4e28-b4f5-example12345"
  }'

​
Step 3: Retrieve number configuration

Check the current messaging configuration for a specific number: 
curl -X GET "https://api.telnyx.com/v2/messaging_phone_numbers/+15551234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response fields

FieldDescription
phone_numberThe E.164 formatted phone number
messaging_profile_idID of the assigned messaging profile
typeNumber type: long_code, toll_free, short_code
country_codeTwo-letter country code
featuresEnabled features (SMS, MMS, etc.)
healthNumber health indicators (message success rate, etc.)
eligible_messaging_productsProducts the number can be used for

​
Step 4: Bulk assignment

Assign multiple numbers to a messaging profile at once using the messaging profile’s phone number assignment endpoint: 
# Assign multiple numbers to a profile
for number in "+15551234567" "+15559876543" "+15551112222"; do
  curl -X PATCH "https://api.telnyx.com/v2/messaging_phone_numbers/$number" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{"messaging_profile_id": "400174af-0a13-4e28-b4f5-example12345"}'
done

​
Messaging enablement by number type

Different number types have different requirements before they can send messages:
Number TypeMessaging Ready?Additional Steps Required
Long code (US)After 10DLC registrationRegister brand + campaign
Toll-free (US/CA)After verificationSubmit toll-free verification
Short codeAfter provisioningShort code setup
Long code (non-US)Typically immediateCheck country-specific requirements
Alphanumeric sender IDAfter registrationAlphanumeric ID setup
US long codes without 10DLC registration will experience carrier filtering and potential message blocking. Always complete 10DLC registration before sending A2P messages on US long codes.

​
Unassign a number from a profile

Remove a number’s messaging profile assignment: 
curl -X PATCH "https://api.telnyx.com/v2/messaging_phone_numbers/+15551234567" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": null
  }'
Unassigning a number from a messaging profile means it will no longer receive inbound message webhooks or be available for outbound messaging through that profile.

​
Troubleshooting

Possible causes:
  • The number doesn’t have messaging capabilities. Check your number order — not all numbers support SMS/MMS.
  • The number hasn’t finished provisioning yet. Wait a few minutes after purchase.
  • The number is on a different Telnyx account.
Fix: Verify the number’s capabilities via GET /v2/phone_numbers/{id} and check for messaging in the features.
Cause: The from number in your send request isn’t assigned to a messaging profile.Fix: Assign the number to a profile using the assignment API, or use the messaging profile’s number pool to automatically select a number.
Possible causes:
  • The number isn’t assigned to a messaging profile
  • The messaging profile doesn’t have a webhook URL configured
  • Your webhook endpoint is returning errors (check MDR logs)
Fix: Verify the number → profile → webhook URL chain. Test with ngrok for local development.
Cause: For US long codes, messages may be filtered by carriers if 10DLC registration isn’t complete.Fix: Complete 10DLC brand and campaign registration. For toll-free, complete verification.
Possible causes:
  • The number is already assigned to a different product (voice connection, etc.) that conflicts
  • The messaging profile ID is invalid
  • The number belongs to a different organization
Fix: Check the profile ID, verify number ownership, and ensure no conflicting product assignments.

​
Next steps

Messaging Profiles

Create and configure messaging profiles with webhooks and features.

Send a Message

Send your first SMS/MMS using a configured number.

Number Pool

Use multiple numbers in a pool for automatic sender selection.

10DLC Registration

Register your brand and campaign for US long code messaging.