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

Country	E.164 Format	Notes
United States	`+14155551234`	Country code: 1
United Kingdom	`+447700900123`	Country code: 44
Chile	`+56912345678`	Country code: 56
Germany	`+4915123456789`	Country 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 = zavu.introspect.phone(
    phone_number="+14155551234"
)

response = zavu.introspect.phone(
  phone_number: "+14155551234"
)

response, err := client.Introspect.Phone(context.TODO(), zavudev.IntrospectPhoneParams{
    PhoneNumber: zavudev.String("+14155551234"),
})

$response = $client->introspect->phone([
    'phoneNumber' => '+14155551234',
]);

curl -X POST https://api.zavu.dev/v1/introspect/phone \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "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

Field	Description
`phoneNumber`	The E.164 formatted number
`validNumber`	Whether the number is valid
`countryCode`	ISO country code (e.g., “US”, “CL”)
`nationalFormat`	Number in local format
`lineType`	Type of line: `mobile`, `landline`, `voip`, `toll_free`, `unknown`
`carrier`	Carrier information if available
`availableChannels`	Channels 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 Type	SMS	WhatsApp	Explanation
`mobile`	Yes	Yes	Mobile numbers support all messaging channels
`voip`	Yes	No	VoIP numbers (Google Voice, Skype) can receive SMS but not WhatsApp
`toll_free`	Yes	No	Toll-free numbers support SMS only
`landline`	No	No	Landlines cannot receive text messages
`unknown`	Yes	No	When 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 = zavu.contacts.get_by_phone(
    phone_number="+14155551234"
)

contact = zavu.contacts.get_by_phone(
  phone_number: "+14155551234"
)

contact, err := client.Contacts.GetByPhone(context.TODO(), "+14155551234")

$contact = $client->contacts->getByPhone('+14155551234');

curl https://api.zavu.dev/v1/contacts/phone/+14155551234 \
  -H "Authorization: Bearer zv_live_xxx"

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.

Getting Started

Concepts

Guides

Phone Numbers

Phone Numbers

E.164 Format

Format Rules

Examples

Phone Number Introspection

Response

Response Fields

Available Channels by Line Type

Contacts

Contact Lifecycle

Retrieving Contact Information

Contact Response

Country Detection

Supported Regions

Best Practices

Validate Early

Store E.164

Handle Line Types

Respect Preferences

Next Steps

Senders

Send a Message

​Phone Numbers

​E.164 Format

​Format Rules

​Examples

​Phone Number Introspection

​Response

​Response Fields

​Available Channels by Line Type

​Contacts

​Contact Lifecycle

​Retrieving Contact Information

​Contact Response

​Country Detection

​Supported Regions

​Best Practices

Validate Early

Store E.164

Handle Line Types

Respect Preferences

​Next Steps

Senders

Send a Message

Phone Numbers

E.164 Format

Format Rules

Examples

Phone Number Introspection

Response

Response Fields

Available Channels by Line Type

Contacts

Contact Lifecycle

Retrieving Contact Information

Contact Response

Country Detection

Supported Regions

Best Practices

Next Steps