API reference

Account management

Configure phone numbers, business profile information, two-step verification PINs, and number registration on the WhatsApp Cloud API.

whatsapp.phoneNumbers

Manage the business phone numbers associated with your WhatsApp Business Account (WABA).

list

whatsapp.phoneNumbers.list(): Promise<WhatsappResponse<{ data: WhatsappPhoneNumber[] }>>

Lists all phone numbers attached to the configured businessAccountId:

phone-numbers.ts

const { data, error } = await whatsapp.phoneNumbers.list();

if (data) {
  data.data.forEach((p) => {
    console.log(p.id, p.display_phone_number, p.verified_name, p.quality_rating);
  });
}

get

whatsapp.phoneNumbers.get(phoneNumberId?: string): Promise<WhatsappResponse<WhatsappPhoneNumber>>

const { data: phone } = await whatsapp.phoneNumbers.get();
console.log("Quality rating:", phone?.quality_rating);
console.log("Verification status:", phone?.code_verification_status);

register & deregister

whatsapp.phoneNumbers.register(input: { pin: string }, opts?): Promise<WhatsappResponse<{ success: boolean }>>

Registers the phone number for messaging on Cloud API by providing the 6-digit two-step verification PIN:

// 1. Register with a 6-digit 2FA PIN
await whatsapp.phoneNumbers.register({ pin: "123456" });

// 2. Deregister a phone number
await whatsapp.phoneNumbers.deregister();

requestVerificationCode & verifyCode

Used during phone number onboarding to request and submit SMS or Voice OTP codes:

verify-number.ts

// 1. Request an SMS code to the business phone number
await whatsapp.phoneNumbers.requestVerificationCode({
  codeMethod: "SMS", // "SMS" | "VOICE"
  language: "en",
});

// 2. Submit the 6-digit OTP code received by SMS
await whatsapp.phoneNumbers.verifyCode({
  code: "582910",
});

updateSettings

whatsapp.phoneNumbers.updateSettings(settings: Record<string, unknown>, opts?): Promise<WhatsappResponse<{ success: boolean }>>

await whatsapp.phoneNumbers.updateSettings({
  // Custom number-level settings
});

whatsapp.businessProfile

Inspect and update your public WhatsApp Business profile that customers see when viewing your contact card:

get

whatsapp.businessProfile.get(opts?): Promise<WhatsappResponse<BusinessProfile>>

const { data: profile } = await whatsapp.businessProfile.get();

if (profile) {
  console.log(profile.about, profile.address, profile.email, profile.websites);
}

update

whatsapp.businessProfile.update(input: UpdateBusinessProfileInput, opts?): Promise<WhatsappResponse<{ success: boolean }>>

update-profile.ts

await whatsapp.businessProfile.update({
  about: "High-performance messaging for modern businesses.",
  description: "Official support and notifications channel.",
  address: "100 Market St, Suite 400, San Francisco, CA 94105",
  email: "support@example.com",
  websites: ["https://example.com", "https://help.example.com"],
  vertical: "PROFESSIONAL_SERVICES",
  profilePictureHandle: "4::...", // media handle from upload if changing profile picture
});

whatsapp.twoStepVerification

Sets or updates the 6-digit PIN required to register and secure the phone number:

whatsapp.twoStepVerification.set(input: { pin: string }, opts?): Promise<WhatsappResponse<{ success: boolean }>>

await whatsapp.twoStepVerification.set({ pin: "987654" });

Store two-step verification PINs securely like any other master password. They are required whenever a phone number is registered or migrated across Cloud API providers.