contacts-management

Contacts Management

When to Use

Use this skill when building code to create, update, or manage contacts and their communication channels. Covers the multi-channel contact model, search, merge operations, phone number introspection, and email address validation.

Contact Model

Contacts are multi-channel: one contact can have multiple channels (SMS, WhatsApp, Email, Telegram, Instagram, Messenger, Voice), each with its own identifier and delivery metrics. Top-level fields expose primary identifiers for quick access.

Contact (John Doe)
├── primaryPhone: +14155551234           (E.164)
├── primaryEmail: [email protected]
├── profileName: "John D."               (WhatsApp profile name, if available)
├── verified: true
├── countryCode: "US"
└── Channels:
    ├── SMS: +14155551234 (primary)
    ├── WhatsApp: +14155551234 (primary)
    ├── Email: [email protected] (primary)
    ├── Email: [email protected] (label: "work")
    ├── Telegram: @johndoe
    └── Voice: +14155551234

Note: The legacy phoneNumber field on Contact is deprecated — use primaryPhone instead.

Valid contact channel types: sms, whatsapp, email, telegram, instagram, messenger, voice (note: auto and sms_oneway are message-send routing options, not contact channel types).

Auto-Creation

Contacts are automatically created when you send a message to a new recipient. No explicit creation needed for basic messaging.

Create Contact

const contact = await zavu.contacts.create({
  displayName: "John Doe",
  channels: [
    { channel: "sms", identifier: "+14155551234", isPrimary: true },
    { channel: "whatsapp", identifier: "+14155551234", isPrimary: true },
    { channel: "email", identifier: "[email protected]", isPrimary: true },
  ],
  metadata: { source: "import", plan: "enterprise" },
});
console.log(contact.id);

Python:

contact = zavu.contacts.create(
    display_name="John Doe",
    channels=[
        {"channel": "sms", "identifier": "+14155551234", "isPrimary": True},
        {"channel": "email", "identifier": "[email protected]", "isPrimary": True},
    ],
)