Contacts

/v1/contacts

Use the contacts node for the following purposes:

  • To verify that a phone number in your database belongs to a valid WhatsApp account. You must ensure that status is valid before you can message a user.
  • To get the WhatsApp ID for a phone number. WhatsApp IDs are needed to send messages, use notifications, and work with groups.

As a business owner, you will present an option to opt-in to WhatsApp communications to your customers. The opt-in flow is managed 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.

  1. Send a request containing an array of registered phone numbers to /v1/contacts. 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 as well as to add or remove users to and from groups.
  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 each message send, however you do not need to check contacts to respond to an incoming customer message, you can immediately respond using the wa_id. There is no additional cost as results are cached. If you check too many phone numbers without sending to them, you will be banned. Take care to check only phone numbers critical to your business that you have already received opt-in for.

Request

You send a call to /v1/contacts to verify that customers are valid WhatsApp users. 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",
   "contacts": [
      "16315551003",
      "1-631-555-1002",
      "+54 9 11 5612-1008",
      "+1 (516) 283-7151"
   ] 
}

Parameters

Name Required Description

blocking

No

Default: no_wait
Other Options: wait
For more information, read the Blocking section.

contacts

Yes

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

Blocking

There are two options for the blocking parameter: no_wait and wait. By default, if the blocking parameter is not specified in a call, blocking is no_wait.

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

  • When blocking is not specified or is specified as no_wait, the processing of the phone numbers is asynchronous. This means that the status in the response will indicate processing and you will have to make another API call for those contacts to get the results.
  • When blocking is specified as wait, the processing of the numbers is synchronous, meaning that 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, returning results. This might take some time.

Phone Number Formats

The phone number in the 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 has registered, 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 (+91):

Phone NumberTranslated Phone Number

"+1-631-555-1002"

"+16315551002"

"6315551002"

"+916315551002" (invalid)

"1-631-555-1002"

"+9116315551002" (invalid)

"+1 (516) 283-7151"

"+15162837151"

"+54 9 11 5612-1008"

"+5491156121008"

Response

After you send the request to check contacts you will receive a response with the current status of the requested numbers. Contacts that are new will typically have a status of processing as the application asynchronously determines if the numbers belong to a valid WhatsApp account.

The following example code demonstrates this behavior, where the phone number +1 (516) 283-7151 has been checked before and so the final status is returned.

{
   "contacts": [
      {
         "input": "1-631-555-1002",
         "status": "processing"
      },
      {
         "input": "6315551003",
         "status": "processing"
      },
      {
         "input": "+54 9 11 5612-1008",
         "status": "processing"
      },
      {
         "input": "+1 (516) 283-7151",
         "status": "valid"
         "wa_id": "15162837151"
      }
   ]
}

If you use the "blocking": "wait" option in the request, the response is now synchronous, so the response is generated only once the status of all of the numbers has been determined. This implies that the request will take a longer time to return if there are new contacts, but you will not see the "processing" value returned. The example code below demonstrates this behavior.

{
   "contacts": [
      {
         "input": "1-631-555-1002",
         "status": "invalid"
      },
      {
         "input": "6315551003",
         "status": "valid"
         "wa_id": "16315551003"
      },
      {
         "input": "+54 9 11 5612-1008",
         "status": "invalid"
      },
      {
         "input": "+1 (516) 283-7151",
         "status": "valid"
         "wa_id": "15162837151"
      }
   ]
}

Parameters

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

input

The value you sent in the contacts field of the JSON request.

status

Status of the user. Options include:

  • processing — Input is still being processed.
  • valid — Input determined to be a valid WhatsApp user.
  • invalid — Input determined to not be a valid WhatsApp user or the phone number is in a bad format.

wa_id

WhatsApp user identifier 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.