Phone Numbers

This guide specifies how you can verify your phone number and its required formatting for the Cloud API.

There is a criteria for what kind of phone numbers you can add to your WhatsApp Business Account (WABA). Please see Phone Numbers for further information.

Some API calls listed require you to know your phone number’s ID. Refer to Get All Phone Numbers on how to get the phone numbers associated with your WABA. The API call response includes IDs for each of the phone numbers connected to your WhatsApp Business Account. Save the ID for the phone you want to use with any /PHONE_NUMBER_ID calls.

Verify Phone Numbers

You need to verify the phone number you want to use to send messages to your customers. Phone numbers must be verified using a code sent via an SMS/voice call. The verification process can be done via Graph API calls specified below.

To verify a phone number using Graph API, make a POST request to PHONE_NUMBER_ID/request_code. In your call, include your chosen verification method and language.

Parameters

Example

Sample request:

curl -X POST \
  'https://graph.facebook.com/v21.0/FROM_PHONE_NUMBER_ID/request_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' \
  -F 'language=en'

After the API call, you will receive your verification code via the method you selected. To finish the verification process, include your code in a POST request to PHONE_NUMBER_ID/verify_code.

Parameters

Example

Sample request:

curl -X POST \
  'https://graph.facebook.com/v21.0/FROM_PHONE_NUMBER_ID/verify_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

A successful response looks like this:

{
  "success": true
}

Identity Change Check

You may want us to verify a customer's identity before we deliver your message to them. You can have us do this by enabling the identity change check setting on your business phone number.

If a customer performs an action in WhatsApp that we consider to be an identity change, we generate a new identity hash for the user. You can get this hash anytime you message the customer by enabling the identity change check setting on your business phone number. Once enabled, anytime the customer messages you, or you message the customer without an identity hash, we will include their hash in any incoming message webhooks or delivery status webhooks. You can then capture and store this hash for future use.

To use the hash, include it in a send message request. We will compare the hash in the request to the customer's current hash. If the hashes match, the message will be delivered. If there is a mismatch, it means the customer has changed their identity since you last messaged them and we will not deliver the message. Instead, we will send you a message status webhook containing error code 137000, notifying you of the failure and mismatch.

When you receive a mismatched hash webhook, assume the customer's phone number can no longer be trusted. To reestablish trust, verify the customer's identity again using other, non-WhatsApp channels. Once you have reestablished trust, resend the failed message to the new identity (if any), without a hash. Then store the customer's new hash included in the message status delivery webhook.

Request Syntax

Send a POST request to the WhatsApp Business Phone Number > Settings endpoint to enable or disable the identity change check setting.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Post Body

{
  "user_identity_change" : {
    "enable_identity_key_check": <ENABLE_IDENTITY_KEY_CHECK>
}

Set <ENABLE_IDENTITY_KEY_CHECK> to true to enable identity check, or false to disable it.

Example Enable Request

curl 'https://graph.facebook.com/v21.0/106850078877666/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "user_identity_change": {
    "enable_identity_key_check": true
  }
}'

Example Enable Response

{
  "success": true
}

Example Send Message With Check

This example message would only be delivered if the recipient_identity_key_hash hash value matches the customer's current hash.

curl 'https://graph.facebook.com/v21.0/106850078877666/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+16505551234",
    "recipient_identity_key_hash": "DF2lS5v2W6x=",
    "type": "text",
    "text": {
        "preview_url": false,
        "body": "Your latest statement is attached. See... "
    }
}'

Example Incoming Message Webhook

In incoming message webhooks, the customer's hash is assigned to the identity_key_hash property.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo Morales"
                },
                "wa_id": "16505551234",
                "identity_key_hash": "DF2lS5v2W6x="
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUMyNTA4M0VGN0Q4RjdDNDVCMAA=",
                "timestamp": "1686591695",
                "text": {
                  "body": "Your latest statement is attached. See... "
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Example Delivery Status Webhook

In delivery status webhooks, the customer's hash is assigned to the recipient_identity_key_hash property.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJGODlDQjZBNjUxMUQ5NEU0MEUA",
                "status": "delivered",
                "timestamp": "1686591922",
                "recipient_id": "16505551234",
                "recipient_identity_key_hash": "DF2lS5v2W6x=",
                "conversation": {
                  "id": "6c84493f3de086c7c68d5a39248f72c0",
                  "origin": {
                    "type": "service"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Example Failed Delivery Status Webhook

In delivery status webhooks, the customer's hash is assigned to the recipient_identity_key_hash property.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQzA0OEU4OTdEQUE5REVCQTgA",
                "status": "failed",
                "timestamp": "1686594665",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 137000,
                    "title": "Confirm the correct Recipient Identity Key Hash or send without any identity key hash"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Getting Throughput Level

Use the WhatsApp Business Phone Number endpoint to get a phone number's current throughput level:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput