Skip to main content

​
Phone Numbers

Phone numbers are the primary identifier for messaging recipients in Zavu. Understanding how phone numbers work will help you build reliable messaging applications.

​
E.164 Format

All phone numbers in Zavu must be in E.164 format. This is the international standard that ensures phone numbers are globally unique and unambiguous.

​
Format Rules

+[country code][subscriber number]
  • Starts with + sign
  • Country code (1-3 digits)
  • Subscriber number (up to 14 digits)
  • No spaces, dashes, or parentheses

​
Examples

CountryE.164 FormatNotes
United States+14155551234Country code: 1
United Kingdom+447700900123Country code: 44
Chile+56912345678Country code: 56
Germany+4915123456789Country code: 49
Always store and send phone numbers in E.164 format. Zavu will reject numbers that don’t match this format.

​
Phone Number Introspection

Before sending a message, you can validate and get information about a phone number using the introspection endpoint. 
const response = await zavu.introspect.phone({
  phoneNumber: "+14155551234"
});

​
Response

{
  "phoneNumber": "+14155551234",
  "validNumber": true,
  "countryCode": "US",
  "nationalFormat": "(415) 555-1234",
  "lineType": "mobile",
  "carrier": {
    "name": "Verizon Wireless",
    "type": "mobile"
  },
  "availableChannels": ["sms", "whatsapp"]
}

​
Response Fields

FieldDescription
phoneNumberThe E.164 formatted number
validNumberWhether the number is valid
countryCodeISO country code (e.g., “US”, “CL”)
nationalFormatNumber in local format
lineTypeType of line: mobile, landline, voip, toll_free, unknown
carrierCarrier information if available
availableChannelsChannels that can reach this number (based on line type)

​
Available Channels by Line Type

The availableChannels array is determined automatically based on the line type:
Line TypeSMSWhatsAppExplanation
mobileYesYesMobile numbers support all messaging channels
voipYesNoVoIP numbers (Google Voice, Skype) can receive SMS but not WhatsApp
toll_freeYesNoToll-free numbers support SMS only
landlineNoNoLandlines cannot receive text messages
unknownYesNoWhen line type is uncertain, we default to SMS only
If availableChannels is empty, the number cannot receive any messages. This typically happens with landline numbers.
Use introspection to validate numbers before adding them to your database, or to determine which channels are available for a contact.

​
Contacts

When you send a message to a phone number, Zavu automatically creates a Contact record. Contacts track:
  • Channel metrics: Success/failure rates per channel
  • Channel availability: Which channels can reach this contact
  • Last inbound: When the contact last messaged you (important for WhatsApp)
  • Preferences: Default channel preference

​
Contact Lifecycle

First message sent to +14155551234
         |
         v
Contact automatically created
         |
         v
Delivery callbacks update metrics
         |
         v
Future routing decisions use this data

​
Retrieving Contact Information

const contact = await zavu.contacts.getByPhone({
  phoneNumber: "+14155551234"
});

​
Contact Response

{
  "id": "contact_abc123",
  "phoneNumber": "+14155551234",
  "countryCode": "US",
  "availableChannels": ["sms", "whatsapp"],
  "defaultChannel": "whatsapp",
  "verified": true,
  "metadata": {
    "source": "checkout"
  },
  "createdAt": "2025-01-15T10:30:00Z"
}

​
Country Detection

Zavu automatically detects the country from the phone number’s dial code. This is used for:
  • Routing decisions: Some channels work better in certain regions
  • Cost optimization: Channel costs vary by country
  • Compliance: Ensuring messages comply with local regulations

​
Supported Regions

Zavu supports phone numbers from all countries. The country code is extracted from the E.164 number automatically.

​
Best Practices

Validate Early

Use the introspection API when collecting phone numbers to catch errors early.

Store E.164

Always store phone numbers in E.164 format in your database.

Handle Line Types

Some channels only work with mobile numbers. Check lineType if channel selection matters.

Respect Preferences

Let users set their preferred channel via the contact’s defaultChannel field.

​
Next Steps

Senders

Learn how senders work with phone numbers

Send a Message

Start sending messages to phone numbers