Contacts

Contacts are automatically created when you send messages. Each contact represents a unique recipient (phone number or email) and stores metadata about their messaging preferences and history.

How Contacts Work

When you send a message to a new recipient, Zavu automatically:

Creates a contact record
Detects the country from the phone number
Determines available messaging channels
Captures the WhatsApp profile name (if available)

// Sending to a new recipient creates a contact
const message = await zavu.messages.send({
  to: "+14155551234",
  text: "Welcome!",
});

// Contact is now available
const contact = await zavu.contacts.retrieveByPhone("+14155551234");
console.log(contact.id); // "con_abc123"

Contact Properties

Property	Description
`id`	Unique contact identifier
`phoneNumber`	E.164 formatted phone number
`countryCode`	Two-letter country code (e.g., “US”)
`profileName`	WhatsApp display name (if available)
`availableChannels`	Channels this contact can receive (sms, whatsapp, etc.)
`defaultChannel`	Preferred channel for auto-routing
`verified`	Whether the contact has been verified
`metadata`	Custom key-value data

Get Contact by ID

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev();

const contact = await zavu.contacts.retrieve("con_abc123");

console.log(`Phone: ${contact.phoneNumber}`);
console.log(`Country: ${contact.countryCode}`);
console.log(`Channels: ${contact.availableChannels.join(", ")}`);
console.log(`Profile: ${contact.profileName || "Unknown"}`);

from zavudev import Zavudev

zavu = Zavudev()

contact = zavu.contacts.retrieve("con_abc123")

print(f"Phone: {contact.phone_number}")
print(f"Country: {contact.country_code}")
print(f"Channels: {', '.join(contact.available_channels)}")
print(f"Profile: {contact.profile_name or 'Unknown'}")

require "zavudev"

client = Zavudev::Client.new(api_key: ENV["ZAVUDEV_API_KEY"])

contact = client.contacts.retrieve("con_abc123")

puts "Phone: #{contact.phone_number}"
puts "Country: #{contact.country_code}"
puts "Channels: #{contact.available_channels.join(', ')}"
puts "Profile: #{contact.profile_name || 'Unknown'}"

contact, _ := client.Contacts.Get(context.TODO(), "con_abc123")

fmt.Println("Phone:", contact.PhoneNumber)
fmt.Println("Country:", contact.CountryCode)
fmt.Println("Channels:", contact.AvailableChannels)
fmt.Println("Profile:", contact.ProfileName)

<?php
$contact = $client->contacts->retrieve('con_abc123');

echo "Phone: " . $contact->phoneNumber . "\n";
echo "Country: " . $contact->countryCode . "\n";
echo "Channels: " . implode(', ', $contact->availableChannels) . "\n";
echo "Profile: " . ($contact->profileName ?? 'Unknown') . "\n";

curl https://api.zavu.dev/v1/contacts/{contactId} \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Response

{
  "id": "con_abc123",
  "phoneNumber": "+14155551234",
  "countryCode": "US",
  "profileName": "John Doe",
  "availableChannels": ["sms", "whatsapp"],
  "defaultChannel": "whatsapp",
  "verified": true,
  "metadata": {
    "tier": "premium",
    "source": "website"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T12:00:00.000Z"
}

Get Contact by Phone Number

Look up a contact using their phone number:

const contact = await zavu.contacts.retrieveByPhone("+14155551234");

if (contact) {
  console.log(`Found contact: ${contact.id}`);
  console.log(`Available channels: ${contact.availableChannels}`);
} else {
  console.log("Contact not found");
}

contact = zavu.contacts.retrieve_by_phone("+14155551234")

if contact:
    print(f"Found contact: {contact.id}")
    print(f"Available channels: {contact.available_channels}")
else:
    print("Contact not found")

contact = client.contacts.retrieve_by_phone("+14155551234")

if contact
  puts "Found contact: #{contact.id}"
  puts "Available channels: #{contact.available_channels}"
else
  puts "Contact not found"
end

contact, err := client.Contacts.GetByPhone(context.TODO(), "+14155551234")
if err != nil {
	fmt.Println("Contact not found")
} else {
	fmt.Println("Found contact:", contact.ID)
	fmt.Println("Available channels:", contact.AvailableChannels)
}

<?php
$contact = $client->contacts->retrieveByPhone('+14155551234');

if ($contact) {
    echo "Found contact: " . $contact->id . "\n";
    echo "Available channels: " . implode(', ', $contact->availableChannels) . "\n";
} else {
    echo "Contact not found\n";
}

# URL-encode the phone number (+14155551234 becomes %2B14155551234)
curl https://api.zavu.dev/v1/contacts/phone/%2B14155551234 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Use this endpoint to check if a recipient already exists before sending messages, or to retrieve their metadata for personalization.

List Contacts

Retrieve all contacts with pagination:

// List all contacts
const { items, nextCursor } = await zavu.contacts.list({
  limit: 50,
});

for (const contact of items) {
  console.log(`${contact.id}: ${contact.phoneNumber}`);
}

// Paginate through all contacts
let cursor: string | undefined;
const allContacts = [];

do {
  const result = await zavu.contacts.list({ cursor, limit: 100 });
  allContacts.push(...result.items);
  cursor = result.nextCursor ?? undefined;
} while (cursor);

console.log(`Total contacts: ${allContacts.length}`);

# List all contacts
result = zavu.contacts.list(limit=50)

for contact in result.items:
    print(f"{contact.id}: {contact.phone_number}")

# Paginate through all contacts
cursor = None
all_contacts = []

while True:
    result = zavu.contacts.list(cursor=cursor, limit=100)
    all_contacts.extend(result.items)
    cursor = result.next_cursor
    if not cursor:
        break

print(f"Total contacts: {len(all_contacts)}")

# List all contacts
result = client.contacts.list(limit: 50)

result.items.each do |contact|
  puts "#{contact.id}: #{contact.phone_number}"
end

# Paginate through all contacts
cursor = nil
all_contacts = []

loop do
  result = client.contacts.list(cursor: cursor, limit: 100)
  all_contacts.concat(result.items)
  cursor = result.next_cursor
  break unless cursor
end

puts "Total contacts: #{all_contacts.length}"

// List all contacts
result, _ := client.Contacts.List(context.TODO(), zavudev.ContactListParams{
	Limit: zavudev.Int(50),
})

for _, contact := range result.Items {
	fmt.Printf("%s: %s\n", contact.ID, contact.PhoneNumber)
}

<?php
// List all contacts
$result = $client->contacts->list(['limit' => 50]);

foreach ($result->items as $contact) {
    echo "{$contact->id}: {$contact->phoneNumber}\n";
}

// Paginate through all contacts
$cursor = null;
$allContacts = [];

do {
    $result = $client->contacts->list(['cursor' => $cursor, 'limit' => 100]);
    $allContacts = array_merge($allContacts, $result->items);
    $cursor = $result->nextCursor;
} while ($cursor);

echo "Total contacts: " . count($allContacts) . "\n";

curl "https://api.zavu.dev/v1/contacts?limit=50" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Filter by Phone Number

phoneNumber is an exact match on the contact’s primary phone number, in E.164. It is not a prefix filter — use search for partial matches.

const { items } = await zavu.contacts.list({
  phoneNumber: "+14155551234",
});

Search

search matches the contact’s name — both displayName and the WhatsApp profile name — as well as its phone numbers and email addresses. It is case- and accent-insensitive, so jose finds “José”.

const { items } = await zavu.contacts.list({ search: "marta", limit: 25 });

A phone number also matches on a trailing fragment, which is how people usually remember them:

// finds +14155551234
const { items } = await zavu.contacts.list({ search: "5551234" });

Contacts created automatically from an inbound message have no displayName, so they only match on their identifier until you name one with Update Contact.

Search results come back in relevance order, not newest-first. cursor is opaque in both modes — pass back exactly what the previous response returned, and start a fresh pagination run whenever the search term changes.

Filter by Tag

Tags group contacts into an audience you send to more than once. Filter by name:

const { items } = await zavu.contacts.list({ tag: "vip" });

Repeat the parameter to require every tag, not any of them:

curl "https://api.zavu.dev/v1/contacts?tag=vip&tag=chile" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

An unknown tag returns 400. A typo that silently matched every contact would be a worse answer than an error.

Tags are created, renamed and assigned from the dashboard. There is no tag CRUD in the API yet.

Update Contact

Update a contact’s default channel or metadata:

const contact = await zavu.contacts.update("con_abc123", {
  defaultChannel: "whatsapp",
  metadata: {
    name: "John Doe",
    tier: "premium",
    source: "mobile_app",
  },
});

console.log(`Updated default channel: ${contact.defaultChannel}`);

contact = zavu.contacts.update(
    "con_abc123",
    default_channel="whatsapp",
    metadata={
        "name": "John Doe",
        "tier": "premium",
        "source": "mobile_app"
    }
)

print(f"Updated default channel: {contact.default_channel}")

contact = client.contacts.update(
  "con_abc123",
  default_channel: "whatsapp",
  metadata: {
    "name" => "John Doe",
    "tier" => "premium",
    "source" => "mobile_app"
  }
)

puts "Updated default channel: #{contact.default_channel}"

contact, _ := client.Contacts.Update(context.TODO(), "con_abc123", zavudev.ContactUpdateParams{
	DefaultChannel: zavudev.String("whatsapp"),
	Metadata: map[string]string{
		"name":   "John Doe",
		"tier":   "premium",
		"source": "mobile_app",
	},
})

fmt.Println("Updated default channel:", contact.DefaultChannel)

<?php
$contact = $client->contacts->update('con_abc123', [
    'defaultChannel' => 'whatsapp',
    'metadata' => [
        'name' => 'John Doe',
        'tier' => 'premium',
        'source' => 'mobile_app',
    ],
]);

echo "Updated default channel: " . $contact->defaultChannel . "\n";

curl -X PATCH https://api.zavu.dev/v1/contacts/{contactId} \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultChannel": "whatsapp",
    "metadata": {
      "name": "John Doe",
      "tier": "premium"
    }
  }'

Updateable Fields

Field	Description
`displayName`	The contact’s name. Pass `null` to clear it and fall back to the identifier.
`defaultChannel`	Preferred channel for smart routing (sms, whatsapp, telegram, email)
`metadata`	Custom key-value pairs (merged with existing metadata)

To change a contact’s phone number or email address, add or remove a channel — identifiers are not updated through this endpoint.

Setting defaultChannel affects smart routing. When you send a message with channel: "auto", Zavu will prefer the contact’s default channel.

Contact Metadata

Store custom data on contacts for personalization and segmentation:

// Add customer data
await zavu.contacts.update("con_abc123", {
  metadata: {
    customerId: "cust_12345",
    plan: "enterprise",
    signupDate: "2024-01-15",
    preferredLanguage: "es",
  },
});

// Use in messages
const contact = await zavu.contacts.retrieve("con_abc123");
const message = await zavu.messages.send({
  to: contact.phoneNumber,
  text: `Hola ${contact.metadata?.customerId}! Your ${contact.metadata?.plan} plan is active.`,
});

Metadata values must be strings. Store complex data as JSON strings if needed.

Available Channels

The availableChannels array indicates which channels can reach this contact:

Channel	When Available
`sms`	Valid mobile or landline number
`whatsapp`	Contact has WhatsApp (detected on first message or reply)
`telegram`	Contact has connected via Telegram bot
`email`	Contact has email address on file

const contact = await zavu.contacts.retrieve("con_abc123");

if (contact.availableChannels.includes("whatsapp")) {
  // Send via WhatsApp for richer experience
  await zavu.messages.send({
    to: contact.phoneNumber,
    channel: "whatsapp",
    text: "Hello via WhatsApp!",
  });
} else {
  // Fall back to SMS
  await zavu.messages.send({
    to: contact.phoneNumber,
    channel: "sms",
    text: "Hello via SMS!",
  });
}

Phone Number Introspection

Validate a phone number and check available channels without creating a contact:

const result = await zavu.introspect.validatePhone({
  phoneNumber: "+14155551234",
});

console.log(`Valid: ${result.validNumber}`);
console.log(`Country: ${result.countryCode}`);
console.log(`Format: ${result.nationalFormat}`);
console.log(`Type: ${result.lineType}`);
console.log(`Carrier: ${result.carrier?.name}`);
console.log(`Channels: ${result.availableChannels}`);

result = client.introspect.validate_phone(phone_number: "+14155551234")

puts "Valid: #{result.valid_number}"
puts "Country: #{result.country_code}"
puts "Format: #{result.national_format}"
puts "Type: #{result.line_type}"
puts "Carrier: #{result.carrier&.name}"
puts "Channels: #{result.available_channels}"

result, _ := client.Introspect.Phone(context.TODO(), zavudev.PhoneIntrospectionParams{
	PhoneNumber: zavudev.String("+14155551234"),
})

fmt.Println("Valid:", result.ValidNumber)
fmt.Println("Country:", result.CountryCode)
fmt.Println("Format:", result.NationalFormat)
fmt.Println("Type:", result.LineType)
fmt.Println("Channels:", result.AvailableChannels)

<?php
$result = $client->introspect->phone([
    'phoneNumber' => '+14155551234',
]);

echo "Valid: " . ($result->validNumber ? 'true' : 'false') . "\n";
echo "Country: " . $result->countryCode . "\n";
echo "Format: " . $result->nationalFormat . "\n";
echo "Type: " . $result->lineType . "\n";
echo "Carrier: " . ($result->carrier->name ?? 'Unknown') . "\n";
echo "Channels: " . implode(', ', $result->availableChannels) . "\n";

curl -X POST https://api.zavu.dev/v1/introspect/phone \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155551234"
  }'

Response

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

Use introspection to validate phone numbers before adding them to broadcasts or CRM systems.

Complete Example

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev();

async function processNewCustomer(phone: string, customerData: {
  name: string;
  email: string;
  plan: string;
}) {
  // 1. Validate the phone number
  const introspection = await zavu.introspect.validatePhone({ phoneNumber: phone });

  if (!introspection.validNumber) {
    throw new Error("Invalid phone number");
  }

  console.log(`Valid ${introspection.lineType} number from ${introspection.countryCode}`);

  // 2. Send welcome message (creates contact automatically)
  const message = await zavu.messages.send({
    to: phone,
    channel: "auto", // Smart routing based on available channels
    text: `Welcome ${customerData.name}! Your ${customerData.plan} account is ready.`,
  });

  console.log(`Welcome message sent: ${message.id}`);

  // 3. Update contact with customer data
  const contact = await zavu.contacts.retrieveByPhone(phone);

  await zavu.contacts.update(contact.id, {
    defaultChannel: introspection.availableChannels.includes("whatsapp")
      ? "whatsapp"
      : "sms",
    metadata: {
      name: customerData.name,
      email: customerData.email,
      plan: customerData.plan,
      signupDate: new Date().toISOString(),
    },
  });

  console.log(`Contact updated: ${contact.id}`);

  return contact;
}

// Usage
processNewCustomer("+14155551234", {
  name: "John Doe",
  email: "john@example.com",
  plan: "premium",
});

Next Steps

Smart Routing

Learn how defaultChannel affects message routing

Broadcasts

Send messages to many contacts at once

Phone Lookup

Validate and lookup phone numbers

Webhooks

Receive updates when contacts reply

API Reference

Manage contacts programmatically:

List contacts — paginated list, with search over name, phone and email
Get a contact — retrieve a contact by ID
Get contact by phone — lookup a contact by phone number
Update a contact — set the name, default channel, or metadata
Delete a contact — permanently remove a contact

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

How Contacts Work

Contact Properties

Get Contact by ID

Response

Get Contact by Phone Number

List Contacts

Filter by Phone Number

Search

Filter by Tag

Update Contact

Updateable Fields

Contact Metadata

Available Channels

Phone Number Introspection

Response

Complete Example

Next Steps

Smart Routing

Broadcasts

Phone Lookup

Webhooks

API Reference

​How Contacts Work

​Contact Properties

​Get Contact by ID

​Response

​Get Contact by Phone Number

​List Contacts

​Filter by Phone Number

​Search

​Filter by Tag

​Update Contact

​Updateable Fields

​Contact Metadata

​Available Channels

​Phone Number Introspection

​Response

​Complete Example

​Next Steps

Smart Routing

Broadcasts

Phone Lookup

Webhooks

​API Reference

How Contacts Work

Contact Properties

Get Contact by ID

Response

Get Contact by Phone Number

List Contacts

Filter by Phone Number

Search

Filter by Tag

Update Contact

Updateable Fields

Contact Metadata

Available Channels

Phone Number Introspection

Response

Complete Example

Next Steps

API Reference