Contacts

/v1/contacts

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.

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 user notifications.

Before You Start

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.

Limitations

• Use this endpoint to verify that a phone number within a business' database belongs to a valid WhatsApp account
• The number of calls must not exceed the number of messages the phone number is sending

Enforcement

If a business is misusing the endpoint, the following actions will be taken:

• All admins listed in the Business Manager will receive an initial warning via email if misuse is suspected
• A business will have seven days after receiving the warning to adjust their behavior
• If after seven days calls have not been adjusted, the phone number will be permanently disabled

Recommendations

We recommend checking contacts before sending messages, however you do not need to check contacts when responding to incoming customer messages as you can immediately respond using the provided wa_id. There is no additional cost as results are cached.

Creating

Before sending messages to users who have opted in, send a POST request to /v1/contacts endpoint to create a WhatsApp account user validation request. In your call, include a list of phone numbers you want to validate.

Example

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

You will receive a response with the current status of the requested numbers and their WhatsApp IDs (wa_id):

{
  "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"
  }
}

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.

Repeat these steps on a regular basis to manage your list of valid users. The results are cached in the WhatsApp Business On-Premises API client's database for 7 days.

Parameters

The following parameters are supported for POST calls to /v1/contacts:

Edges

The following edges are connected to this node:

Blocking

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).

Phone Number Formats

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

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

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:

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.