Use the contacts node to manage WhatsApp users in your database by validating them before sending messages and verify a user's identity with identity hashes.

Validate WhatsApp Account Users

With the contacts node you can:

  • Verify that a phone number in your database belongs to a valid WhatsApp account. You must ensure that the status is valid before you can message a user.
  • Get the WhatsApp ID for a phone number. WhatsApp IDs are needed to send messages and use notifications.

You must present an option to your customers to opt-in to WhatsApp communications with your business. This opt-in flow is maintained by your business. After a customer opts-in, use the contacts node to validate the registered number. See Understanding How to Get Opt-in for WhatsApp for more information.

Before sending messages to users who have opted in:

  1. Send an API call to /v1/contacts containing an array of registered phone numbers. You will receive a response containing user statuses (status) and their WhatsApp IDs (wa_id).
  2. Save the WhatsApp IDs for those numbers that returned a status of valid. Valid users are those with a WhatsApp account. Use the WhatsApp IDs to send messages and notifications.
  3. Repeat these steps on a regular basis to manage your list of valid users. The results are cached in the WhatsApp Business API client's database for 7 days.

At this time, there is no callback to inform you when a WhatsApp user joins or leaves the network, so you must check contacts frequently.

Best practice is to check contacts before sending messages, however you do not need to check contacts when responding to incoming customer messages asyou can immediately respond using the provided wa_id. There is no additional cost as results are cached. If you check too many phone numbers without sending messages to them, you will be banned. Take care to check only phone numbers critical to your business for which you have already received customer opt-in.


The contacts field in the API call contains the list of customer phone numbers that you are validating. The phone numbers can be in any standard telephone number format.

POST /v1/contacts
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"+1 631 555 1001",
  	"+1 (631) 555-1004",
  "force_check": false | true


Name Required Description



Whether the API request should be wait for processing to complete or not before returning a response
Values: no_wait (default), wait
For more information, read the Blocking section below.



Array of phone numbers that you are validating
The numbers can be in any standard telephone number format. The recommended format for contact phone numbers is with a plus sign (+) and the country code.
For more information, see the Phone Number Formats section below.



Whether to check the contacts cache or not
Values: false (default), true
Contact information is normally cached for 7 days. By setting the force_check parameter to true the cache will be bypassed ensuring a check is performed.


There are two options for the blocking parameter: no_wait and wait. If the blocking parameter is not specified in a call it is no_wait by default.

The blocking parameter determines whether the request should wait for the processing to complete (synchronous) or not (asynchronous).



The processing of the phone numbers is asynchronous
Any contacts that cannot be returned immediately will be marked as “processing” and returned in a subsequent callback request when they have been processed. This callback request will have the same format as the synchronous response, but only include the pending contacts.


The processing of the numbers is synchronous
You will see the final status for all of the contacts after syncing with server. This setting makes the query block wait until the numbers have all been checked before returning results. Note: This might take some time.

Phone Number Formats

The phone numbers in the contacts API request can be in any dialable format.

When there is no plus sign (+) at the beginning of the phone number, the country code is determined using the phone number that your WhatsApp Business API client is registered under, so phone numbers associated with a different country code will fail.

The recommended best practice is to always specify the country code with the phone number and explicitly prefix it with a plus sign (+).

Here are some examples that demonstrate this behavior, assuming the WhatsApp Business API client is registered with an Indian phone number (i.e., country code is +91):

Phone NumberTranslated Phone NumberValid?










"+1 (516) 283-7151"



"+54 9 11 5612-1008"




After you send the contacts API call, you will receive a response with the current status of the requested numbers.

  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
    "input": "6315551002",
    "status": "invalid"
    "input": "+163155588",
    "status": "failed"

Returned Fields

The contacts response payload contains the same array of phone numbers sent in the request with the input, status, and wa_id properties.

Name Description


The value you sent in the contacts field of the API call


Status of the user

  • processing — Input is still being processed
  • valid — A valid WhatsApp user
  • invalid — Not a valid WhatsApp user
  • failed — There was an error processing this check


WhatsApp user ID that can be used in other API calls
Only returned if the status is valid

Along with the processing status, you should see an HTTP status of 200 OK. If there are any errors in the response, see Error and Status Messages for more information.

Manage Users' Identities

It is possible to receive notifications from WhatsApp when a user you are communicating with has potentially changed.

See Understanding Identity Change for WhatsApp Business for more information.

For more information about the system notification sent from WhatsApp see Inbound System Messsages — Example: A User Potentially Changed. The response to the system notification is managed by your business.

Retrieve the latest identity hash for a user


GET /v1/contacts/users-whatsapp-id/identity


If successful, your request returns 200 OK and a message body containing an contacts object. For example, the complete response, including the contacts object, might look like this:

        "hash": "UKD6Y/5SqDU=",
        "created_timestamp": 1600132094000,
        "acknowledged": true 
Returned Fields

The contacts response object contains the following information about the user’s identity.



State of acknowledgment for latest user_identity_changed system notification



Timestamp of when the WhatsApp Business API client detected the user potentially changed



Identifier for the latest user_identity_changed system notification


Acknowledge the latest user_identity_changed system notification

Until you make a successful identity API call after receiving a user_identity_changed notification, all outgoing messages to this user will be blocked if the show_security_notifications settings is enabled in the application settings.


PUT /v1/contacts/users-whatsapp-id/identity
    “hash”: “Rc/eg9RQ0JA=”




Identifier of the latest user_identity_change system notification received for this contact


A successful response is 200 OK with a null or {} message body.