# Phone Numbers

> Understanding phone number formats, validation and introspection in Zavu. E.164 normalization, carrier lookup, capability detection for SMS, WhatsApp

## 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 |

> **Warning:**
> 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.

```typescript
const response = await zavu.introspect.validatePhone({
  phoneNumber: "+14155551234"
});
```

```bash
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

```json
{
  "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 |

> **Info:**
> If `availableChannels` is empty, the number cannot receive any messages. This typically happens with landline numbers.

> **Tip:**
> 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

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

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

### Contact Response

```json
{
  "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](https://www.zavu.dev/docs/concepts/senders): Learn how senders work with phone numbers
  - [Send a Message](https://www.zavu.dev/docs/guides/sending-messages/easy-way): Start sending messages to phone numbers