API reference

whatsapp.contacts

Verify WhatsApp registration status for phone numbers before sending outreach, and manage blocked user lists.

check

whatsapp.contacts.check(phoneNumbers: string[], opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<ContactCheckResult[]>>

Verifies whether one or more phone numbers are registered WhatsApp accounts, returning the associated WhatsApp ID (waId) for valid contacts:

check-contacts.ts

const { data: results, error } = await whatsapp.contacts.check([
  "15551234567",
  "15559876543",
  "447123456789",
]);

if (results) {
  results.forEach((c) => {
    if (c.status === "valid") {
      console.log("✅ Valid contact: " + c.input + " → WA ID: " + c.waId);
    } else {
      console.log("❌ Not on WhatsApp: " + c.input);
    }
  });
}

block

whatsapp.contacts.block(waIds: string[], opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<{ success: boolean }>>

Blocks one or more WhatsApp users by their WhatsApp ID, preventing incoming messages from reaching your webhook:

await whatsapp.contacts.block(["15551234567"]);

unblock

whatsapp.contacts.unblock(waIds: string[], opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<{ success: boolean }>>

await whatsapp.contacts.unblock(["15551234567"]);

listBlocked

whatsapp.contacts.listBlocked(opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<{ waId: string }[]>>

Retrieves the list of all currently blocked WhatsApp IDs for the phone number:

const { data: blockedList } = await whatsapp.contacts.listBlocked();
console.log("Blocked users:", blockedList);

ContactCheckResult shape

Parameter	Type	Description
input	string	The phone number string exactly as supplied in your input array.
waId	string \| undefined	The official WhatsApp ID (digits only) to target when sending messages.
status	"valid" \| "invalid"	Whether the user account is active and registered on WhatsApp.