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 a template message is sent to a phone number without a WhatsApp account, you will receive an error message denoting “User is not valid" with error code 1013.

For any other errors in the response, refer to Error and Status Messages.

Blocking Contacts

Blocking may be considered as a defensive feature to stop bad actors from continuing harmful actions. To block a contact they had to have sent you a message in the last 24 hours.

Example

Send an API call to /v1/contacts/{phone_number}/block with a reason to block another WhatsApp account.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

A successful response has HTTP status 200 and no "errors" object.

A failure response looks like this:

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Parameters

The following parameters are supported for POST calls to /v1/contacts/{phone_number}/block:

Unblocking Contacts

Make this call to unblock a contact

Example

Send an API call to /v1/contacts/{phone_number}/unblock

POST /v1/contacts/+16315551000/unblock

A successful response has HTTP status 200 and no "errors" object.

A failure response looks like this:

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

Parameters

The following parameters are supported for POST calls to /v1/contacts/{phone_number}/unblock:

Blocklist

This is how you obtain a list of your blocked contacts.

Example

Send an API call to /v1/contacts/blocklist to receive a paged list of your blocked contacts

GET /v1/contacts/blocklist?limit=10&offset=0

You will receive a response with a page of your block list along with pagination info

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

Parameters

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

Reporting

Reporting provides crucial signals to build a preventive solution agains bad actors. Before reporting a contact, they had to have sent you a message in the last 24 hours.

Example

Send an API call to /v1/contacts/{phone_number}/report containing a reason if you are blocking another WhatsApp account.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

A successful response has HTTP status 200 and no "errors" object.

A failure response looks like this:

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Parameters

The following parameters are supported for POST calls to /v1/contacts/{phone_number}/report: