Phone Numbers

Pool-Based Numbers

Transactional uses a shared pool model for SMS phone numbers. This means:

• No number procurement - You don't need to buy or manage phone numbers
• Automatic routing - We select the best number for each recipient
• Carrier compliance - Numbers are pre-registered and approved

How Pool Numbers Work

When you send an SMS:

1. We detect the recipient's country from their phone number
2. We select an appropriate pool number for that country
3. The message is sent from our pool number
4. Replies go to our system and can be forwarded via webhooks

Your API Request → Pool Number Selection → Carrier Delivery
   +14155551234       +18005551234           Recipient
   (recipient)        (pool number)

Supported Countries

Number Types

Long Codes

Standard 10-digit phone numbers used for person-to-person style messaging.

• Good for low-volume transactional messages
• Required for 10DLC compliance in the US
• Available in all supported countries

Short Codes

5-6 digit numbers for high-volume messaging.

• Higher throughput limits
• Better for time-sensitive OTP messages
• Available for US and Canada

Toll-Free Numbers

Numbers that recipients can call/text for free.

• Good for customer support use cases
• Available in US and Canada

Country Detection

We automatically detect the recipient's country from their phone number:

// US number (area code 415)
await client.sms.send({
  to: '+14155551234',  // Detected as US
  templateAlias: 'otp-verification',
  templateModel: { code: '123456' },
});
 
// Canadian number (area code 416 - Toronto)
await client.sms.send({
  to: '+14165551234',  // Detected as CA
  templateAlias: 'otp-verification',
  templateModel: { code: '123456' },
});
 
// UK number
await client.sms.send({
  to: '+447911123456',  // Detected as GB
  templateAlias: 'otp-verification',
  templateModel: { code: '123456' },
});

E.164 Format

All phone numbers must be in E.164 format:

+[country code][subscriber number]

Examples:

• US: +14155551234
• UK: +447911123456
• India: +919876543210

Common Mistakes

// Wrong - missing country code
await client.sms.send({ to: '4155551234', ... });
 
// Wrong - missing + prefix
await client.sms.send({ to: '14155551234', ... });
 
// Correct
await client.sms.send({ to: '+14155551234', ... });

Message Routing

Use Case Matching

Pool numbers are tagged with supported use cases. When you send via a template, we match the template's use cases to find the best number:

Fallback Logic

If no perfect match is found:

1. Try numbers with overlapping use cases
2. Fall back to any available number for the country
3. Return an error if no number is available

Dedicated Numbers (Enterprise)

Enterprise customers can request dedicated phone numbers:

• Exclusive use - Number is only used by your organization
• Consistent sender - Recipients see the same number
• Two-way messaging - Better for conversational use cases

Contact sales to learn more about dedicated numbers.

Number Status

Pool numbers can have different statuses:

If a number becomes unavailable, we automatically route to another number in the pool.

Best Practices

1. Trust Automatic Routing

Don't try to select specific numbers. Our routing algorithm optimizes for:

• Delivery speed
• Carrier relationships
• Compliance requirements

2. Use Templates for Consistent Routing

The same template will use similar number types, providing a more consistent experience for your users.

3. Handle Number Changes Gracefully

Pool numbers may change. Don't store or display the sender number to users - focus on your brand name in the message content.

Next Steps

• Sending - Learn about sending SMS messages
• Compliance - Understand 10DLC and carrier requirements
• Receiving - Handle inbound messages