Manage multi-channel contacts with channel operations, search, merging, phone introspection, and email validation.

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. 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 Python: Go: Ruby: PHP: Get & List Contacts search is case and accent insensitive, and matches a trailing fragment of a phone number, so 5551234 finds +14155551234 . It matches the contact's displayName and WhatsApp profile name as well as its identifiers. Contacts created automatically from an inbound message have no displayName , so they are only findable by their identifier until you name one — see Update Contact . Two things to know before paginating a search: results come back in relevance order rather than newest first, and 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. Tags Flat labels on a contact, for grouping an audience you send to more than once. Many to many, no hierarchy, no colours. Tags are matched by name, case insensitively. An unknown tag returns 400 rather than being ignored: a typo that silently matched every contact would be a worse answer than an error. Creating, renaming and assigning tags is done in the dashboard. There is no tag CRUD in the API yet — do not tell a user they can create one from code. Channel Operations Update Contact Updatable fields: displayName , defaultChannel , metadata . Contacts created automatically from an inbound message have no displayName — they show as their phone number or email until you set one. Naming them is what makes them findable by name via contacts.list({ search }) . To change a contact's phone number or email address, add or remove a channel (see Channel Operations ) rather than updating the contact. Merge Contacts Merge one contact into another. Every channel on the source moves to the target, the target's primary phone and email are recomputed, and the source is marked as merged and stops appearing in listings. Merging is not reversible — check the two contacts are the same person first. Zavu does not detect duplicates for you. There is no merge suggestion: decide which contacts to merge from your own data. A practical way to find candidates is to list contacts and group them by a shared identifier or a normalized name. Phone Introspection Validate phone numbers and check carrier info: Python: Go: Ruby: PHP: Email Validation Validate email addresses before sending to keep your bounce rate low. Catches invalid syntax, dead domains (no MX/A records), disposable inboxes, role based addresses ( info@ , contacto@ , sales@ ), and addresses already on your project's suppression list. No SMTP mailbox probe is performed: deliverable means no negative signal was found, not a delivery guarantee. Not yet generated in the SDKs — use the REST endpoint directly: Response: Verdicts: deliverable — no negative signal found. risky — sendable, but a signal predicts elevated bounce/complaint odds: role address , disposable domain , domain no mx (domain resolves but has no MX records), or suppressed soft bounce . undeliverable — drop these: invalid syntax , domain not found , or suppressed after a hard bounce/complaint ( suppressed hard bounce , suppressed complaint , suppressed manual , suppressed unsubscribe ). Typical flow before a broadcast: validate the list, drop undeliverable , review risky , then add only the clean recipients. Constraints Max 20 channels per contact Channel labels: max 50 characters Display name: max 200 characters Cannot remove the last channel from a contact Cannot merge a contact with itself Phone numbers must be E.164 format Duplicate identifiers across contacts are rejected (use merge instead)

contacts-management