Номера телефонов

В этом руководстве описано, как подтвердить номер телефона, и перечислены необходимые форматы номеров для облачного API.

В аккаунт WhatsApp Business можно добавлять только определенные номера телефонов. Подробнее см. в статье о номерах телефонов.

Для некоторых вызовов API, перечисленных ниже, необходимо знать ID номера. Информацию о том, как получить все номера телефонов, связанные с вашим аккаунтом WhatsApp Business, см. в этом разделе. Ответ на вызов к API будет содержать ID каждого номера телефона, связанного с аккаунтом WhatsApp Business. Сохраните ID номера, который нужно использовать для вызовов /PHONE_NUMBER_ID.

Подтверждение номера телефона

Чтобы начать переписку с клиентами, вам нужно подтвердить номер телефона. Для этого используется код, отправляемый в SMS или голосовом вызове. Подтвердить номер можно через вызовы API Graph, указанные ниже.

Чтобы подтвердить номер телефона с помощью API Graph, выполните запрос POST к конечной точке PHONE_NUMBER_ID/request_code. В вызове нужно указать способ подтверждения и язык.

Параметры

Пример

Пример запроса:

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

После отправки вызова API вы получите код подтверждения выбранным способом. Чтобы завершить подтверждение, отправьте полученный код в запросе POST к конечной точке PHONE_NUMBER_ID/verify_code.

Параметры

Пример

Пример запроса:

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

В случае успеха ответ выглядит следующим образом:

{
  "success": true
}

Проверка изменения идентификационных данных

Перед доставкой вашего сообщения мы можем проверять идентификационные данные клиента. Для этого вы должны включить проверку изменения идентификационных данных для номера телефона компании.

Если клиент совершит в WhatsApp действие, которое считается изменением идентификационных данных, мы сгенерируем для этого пользователя новый хэш этих данных. Вы можете получать этот хэш каждый раз, когда отправляете сообщение клиенту. Для этого включите проверку изменения идентификационных данных для номера телефона компании. Если эта функция включена, каждый раз, когда клиент или вы будете отправлять друг другу сообщение без хэша идентификационных данных, мы будем добавлять его хэш во все уведомления Webhooks о входящем сообщении и статусе доставки. Вы сможете записать и сохранить этот хэш для дальнейшего использования.

Чтобы использовать хэш, добавьте его в запрос на отправку сообщения. Мы сравним хэш в запросе с текущим хэшем клиента. Если хэши совпадут, сообщение будет доставлено. Если обнаружится несоответствие, это будет означать, что клиент изменил свои идентификационные данные с того момента, когда вы последний раз отправили ему сообщение, и текущее сообщение не будет доставлено. Вместо этого мы отправим вам уведомление Webhooks о статусе сообщения, содержащее код ошибки 137000, который свидетельствует о сбое и несоответствии.

При получении уведомления Webhooks о несовпадении хэша вы можете считать, что номеру телефона клиента больше нельзя доверять. Чтобы восстановить доверие, проверьте личность клиента ещё раз, используя другие каналы, отличные от WhatsApp. Когда доверие будет восстановлено, повторно отправьте сообщение, используя новые идентификационные данные (если таковые имеются), без хэша. Затем сохраните новый хэш клиента, содержащийся в уведомлении Webhooks о статусе доставки сообщения.

Синтаксис запроса

Чтобы включить или отключить проверку изменения идентификационных данных, отправьте запрос POST к конечной точке Номер телефона WhatsApp Business > Настройки.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Тело

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

Установите для <ENABLE_IDENTITY_KEY_CHECK> значение true, чтобы включить проверку изменения идентификационных данных, или false, чтобы отключить ее.

Пример запроса для включения

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

Пример ответа для включения

{
  "success": true
}

Пример отправки сообщения с проверкой

Это сообщение будет доставлено, только если значение хэша recipient_identity_key_hash совпадет с текущим хэшем клиента.

curl 'https://graph.facebook.com/v19.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... "
    }
}'

Пример уведомления Webhooks о входящем сообщении

В уведомлениях Webhooks о входящем сообщении хэш клиента назначен свойству identity_key_hash.

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

Пример уведомления Webhooks о статусе доставки

В уведомлениях Webhooks о статусе доставки хэш клиента назначен свойству recipient_identity_key_hash.

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

Пример уведомления Webhooks о статусе доставки при сбое

В уведомлениях Webhooks о статусе доставки хэш клиента назначен свойству recipient_identity_key_hash.

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

Получение текущей пропускной способности

Чтобы получить текущий уровень пропускной способности для номера телефона, воспользуйтесь конечной точкой Номер телефона WhatsApp Business:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput