Search Contacts
wa_search_contactsRead-only
Find contacts in one of your WhatsApp accounts by name or number. Matching is case-insensitive and looks at saved names, the name the contact publishes for themselves, business names, and the number — so "+44 7700 900111" finds a contact stored as 447700900111. Returns an empty list if nothing matches. Set include_pictures to also get profile picture URLs, at most 10 matches per page.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | how many to return (default 500, max 2000; max 10 with include_pictures) | |
| query | Yes | a name or number fragment; matching is case-insensitive and ignores punctuation in numbers | |
| account_id | Yes | which of your accounts to search, from wa_list_accounts | |
| after_cursor | No | return matches after this cursor; omit to start from the beginning | |
| include_pictures | No | also return each match's profile picture URL. This looks every match on the page up on WhatsApp, so the page is capped at 10 and can take half a minute |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| total | Yes | how many contacts matched in total, before the limit was applied | |
| refusal | No | present only when the request was declined | |
| contacts | Yes | ||
| has_more | No | true when more contacts remain after this page | |
| truncated | No | true when more contacts exist than were returned | |
| next_cursor | No | pass this as after_cursor to continue; page until has_more is false to read the whole address book |