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

В этом документе рассказывается, как предлагать клиентам предварительно подтвержденные номера телефонов в новом процессе регистрации на сайте поставщика. Предварительно подтвержденные номера — это номера телефонов компании, которые вы уже подтвердили для нее. Благодаря этому клиентам не придется обращаться к вам за одноразовым паролем.

Предварительно подтвержденные номера телефонов компании представлены одноименными объектамивременного действия. Когда конечный клиент выбирает один из номеров и проходит процесс регистрации на сайте поставщика, временный объект заменяется объектом номера телефона WhatsApp Business. При этом вам необходимо получить ID нового объекта, чтобы зарегистрировать номер.

Требования

Ваша компания должна быть одобренным партнером по решениям.
Пользователь приложения должен быть администратором в аккаунте компании, в который добавляются предварительно подтвержденные номера телефонов.
Маркер доступа пользователя или системного пользователя.
Разрешение business_management.
Действительные номера телефонов компании.

Ограничения

Функция доступна только при использовании нового процесса регистрации на сайте поставщика. Подробнее о том, как включить новый процесс, см. в этом документе.
Вы должны отслеживать, кто запрашивает предварительно одобренный номер телефона компании.
Если конечный клиент не запросит предварительно подтвержденный номер телефона в процессе регистрации на сайте поставщика в течение 90 дней после подтверждения, номер вернется в статус неподтвержденного. Чтобы восстановить статус на следующие 90 дней, его нужно будет подтвердить повторно.
Незапрошенные предварительно подтвержденные номера телефонов можно подтвердить заново не ранее, чем за 45 дней до их запланированного возврата в неподтвержденное состояние. Это время указывается в поле verification_expiry_time.
Если вы добавляете номер телефона в пул предварительно подтвержденных номеров компании (шаг 1), но не подтверждаете его в течение 90 дней (шаг 3), номер будет удален из пула и его придется добавить заново.

Создание предварительно подтвержденных номеров

Чтобы создать предварительно подтвержденный номер телефона компании, передать информацию о нем в процесс регистрации на сайте поставщика и зарегистрировать, когда клиент запросит его.

Шаг 1. Создание предварительно подтвержденного номера телефона компании

Чтобы создать предварительно подтвержденный номер телефона компании, используйте конечную точку Бизнес-аккаунт > Добавить номера телефонов. Он будет добавлен в ваш пул номеров.

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

POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers
  ?phone_number=<PHONE_NUMBER>

Ответ

В случае успеха API вернет ID объекта предварительно подтвержденного номера телефона WhatsApp Business. Это значение нужно сохранить: оно понадобится в будущем.

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

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

curl -X POST 'https://graph.facebook.com/v20.0/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'

Пример ответа

{
  "id": "106540352242922"
}

Сведения о поддерживаемых форматах номеров и параметрах запроса см. в справке по конечной точке Бизнес-аккаунт > Добавить номера телефонов.

Шаг 2. Запрос кода подтверждения

Чтобы запросить одноразовый пароль для созданного предварительно подтвержденного номера в SMS или голосовом сообщении, воспользуйтесь конечной точкой Предварительно подтвержденный номер телефона WhatsApp Business > Запросить код.

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

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code
  ?code_method=<CODE_METHOD>
  &language=<LANGUAGE>

Ответ

В случае успеха API вернет значение true.

{
  "success": <SUCCESS>
}

Мы отправим SMS или голосовое сообщение с одноразовым паролем для номера телефона. Одноразовый пароль нужно сохранить: он понадобится в следующем запросе.

Синтаксис SMS с одноразовым паролем

WhatsApp code <CODE>

Синтаксис голосового сообщения с одноразовым паролем

Повторяется три раза.

Verification code is <CODE>

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

curl -X POST 'https://graph.facebook.com/v20.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

Пример ответа

{
  "success": true
}

Пример SMS с одноразовым паролем

WhatsApp code 123-456

Пример голосового сообщения с одноразовым паролем

Повторяется три раза.

Verification code is 123456

Поддерживаемые способы получения кода, языки и параметры запроса см. в справке по конечной точке Предварительно подтвержденный номер телефона WhatsApp Business > Запросить код.

Шаг 3. Подтвердите номер

Чтобы подтвердить номер телефона компании с помощью одноразового пароля, воспользуйтесь конечной точкой Предварительно подтвержденный номер телефона WhatsApp Business > Подтвердить код.

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

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code
  ?code=<CODE>

Ответ

В случае успеха API вернет значение true, а для параметра code_verification_status номера телефона компании на 90 дней будет установлено значение VERIFIED.

{
  "success": <SUCCESS>
}

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

curl -X POST 'https://graph.facebook.com/v20.0/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'

Пример ответа

{
  "success": true
}

Поддерживаемые параметры запроса см. в справке по конечной точке Предварительно подтвержденный номер телефона WhatsApp Business > Подтвердить код.

Если у вас есть предварительно подтвержденные номера телефонов компании, покажите их на экране регистрации на сайте поставщика.

Показ предварительно подтвержденных номеров телефонов на экране регистрации на сайте поставщика

Чтобы показывать предварительно подтвержденные номера телефонов компании на экране в процессе регистрации на сайте поставщика, можно воспользоваться автоматическим заполнением данных формы. Для этого добавьте объект preVerifiedPhone со свойством ids в объект setup и назначьте ID предварительно одобренных номеров телефонов компании в виде массива строк свойству ids:

{
  scope: '<SCOPE>',
  extras: {
    feature: '<FEATURE>',
    setup: {
      preVerifiedPhone: {
        ids: [<IDS>]
      }
    }
  }
}

Пример:

{
  scope: 'business_management,whatsapp_business_management',
  extras: {
    feature: 'whatsapp_embedded_signup',
    version: 2,
    setup: {
	business: {
	  name: 'Acme Inc.',
	  email: 'johndoe@acme.com',
	  phone: {
	    code: 1,
	    number: '6505551234'
        },
	  website: 'https://www.acme.com',
        address: {
          streetAddress1: '1 Acme Way',
          city: 'Acme Town',
          state: 'CA',
          zipPostal: '94000',
          country: 'US'
        },
        timezone: 'UTC-08:00'
      },
      phone: {
        displayName: 'Acme Inc.',
        category: 'ENTERTAIN',
        description: 'Gears and widgets'
      },
      preVerifiedPhone: {
        ids: ['106540352242922','105954558954427']
      }
    }
  }
}

Примечание. Если не запросить предварительно подтвержденный номер телефона компании со статусом VERIFIED в течение 90 дней после подтверждения, номер вернется в статус UNVERIFIED. При этом он по-прежнему будет отображаться на экране регистрации. Если конечный клиент попытается принять неподтвержденный номер, ему придется подтвердить его самостоятельно, запросив у вас одноразовый пароль.

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

Если вы точно не помните, когда в последний раз предварительно подтверждали конкретный номер телефона компании, выполните запрос к конечной точке Предварительно подтвержденный номер телефона WhatsApp Business и считайте поля code_verification_time и verification_expiry_time. В них указаны время последнего подтверждения и когда срок его действия истечет.

Как определить, запросил ли клиент номер телефона в процессе регистрации?

См. раздел Получение ID номеров телефонов, запрошенных клиентами.

Получение ID номеров телефонов, запрошенных клиентами

Отправьте запрос GET к конечной точке Бизнес-аккаунт WhatsApp > Номера телефонов. Он вернет все номера телефонов WhatsApp Business аккаунта WhatsApp Business.

Найдите в каждом возвращенном объекте свойство display_phone_number. Если объект содержит номер телефона (например, 16505551234) в качестве значения поля display_phone_number, клиент запросил этот номер. Скопируйте значение свойства id объекта: этот ID теперь представляет объект нового номера телефона WhatsApp Business (старый ID работать не будет).

Можно также использовать ту же конечную точку с расширением field, запросить поле display_phone_number и указать номер телефона. Пример:

GET /102290129340398/phone_numbers?display_phone_number=16505551234

Если в ответе вы получите объект номера телефона WhatsApp Business с параметром display_phone_number, это означает, что клиент запросил номер, а вам нужно скопировать значение id объекта.

Получение предварительно подтвержденных номеров телефонов компании

Используйте конечную точку Бизнес-аккаунт > Предварительно подтвержденные номера, чтобы получить список всех объектов предварительно подтвержденных номеров телефонов WhatsApp Business, независимо от их статуса, для своего пула номеров телефонов бизнес-аккаунта:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers

Результаты автоматически сортируются по времени создания. Кроме того, с помощью расширения поля можно запросить поле code_verification_status, чтобы API возвращал только предварительно подтвержденные номера с указанным статусом подтверждения:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED

Общий доступ к предварительно подтвержденным номерам

Отправьте запрос POST к конечной точке Business > Share Preverified Numbers, чтобы поделиться предварительно подтвержденными номерами телефонов компании с бизнес-партнерами, или запрос DELETE, к той же конечно точке, чтобы отменить общий доступ.

Бизнес-партнеры могут передавать предварительно подтвержденные номера телефонов, к которым предоставлен общий доступ, в процесс регистрации на сайте поставщика.

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

Синтаксис запроса на предоставление доступа

POST /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Синтаксис запроса на отзыв доступа

DELETE /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Ответ

В случае успеха API вернет значение true. Если вы предоставили доступ, сообщите своему бизнес-партнеру о новом подтвержденном номере и предоставьте его ID. Если вы отменили доступа, номер больше не будет отображаться в реализации регистрации на сайте поставщика этого партнера.

{
  "success": <SUCCESS>
}

Пример запроса на предоставление доступа

curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Пример запроса на отзыв доступа

curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Пример ответа

{
  "success": true
}

Регистрация предварительно подтвержденных номеров программным путем

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

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

Используйте этот запрос, чтобы создать номер телефона WhatsApp Business в аккаунте WhatsApp Business с использованием ID предварительно подтвержденного номера телефона компании. Это действие заменяет шаг 1.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

Тело публикации

{
  "preverified_id": "<PREVERIFIED_ID>",
  "country_dial_code": "<COUNTRY_DIAL_CODE>",
  "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

Свойства

Заполнитель Описание Пример значения

Заполнитель	Описание	Пример значения
`<PREVERIFIED_ID>` Строка	Обязательный параметр. ID предварительно подтвержденного номера телефона компании.	`6635066806614622`
`<COUNTRY_DIAL_CODE>` Строка	Обязательный параметр. Код страны для предварительно подтвержденного номера телефона компании.	`1`
`<DISPLAY_PHONE_NUMBER>` Строка	Обязательный параметр. Отображаемый номер телефона для предварительно подтвержденного номера телефона компании.	`5550783881`
`<VERIFIED_NAME>` Строка	Обязательный параметр. Отображаемое имя для предварительно подтвержденного номера телефона компании.	`Lucky Shrub`

<PREVERIFIED_ID>

Строка

Обязательный параметр.

ID предварительно подтвержденного номера телефона компании.

6635066806614622

<COUNTRY_DIAL_CODE>

Строка

Обязательный параметр.

Код страны для предварительно подтвержденного номера телефона компании.

1

<DISPLAY_PHONE_NUMBER>

Строка

Обязательный параметр.

Отображаемый номер телефона для предварительно подтвержденного номера телефона компании.

5550783881

<VERIFIED_NAME>

Строка

Обязательный параметр.

Отображаемое имя для предварительно подтвержденного номера телефона компании.

Lucky Shrub

Синтаксис ответа

В случае успеха API вернет ID номера телефона WhatsApp Business. Используйте этот ID, чтобы зарегистрировать номер (шаг 4 в документе Регистрация номеров телефонов).

{
  "id": "<ID>"
}

Свойства ответа

Заполнитель Описание Пример значения

Заполнитель	Описание	Пример значения
`<ID>`	ID номера телефона WhatsApp Business. Этот объект заменил объект предварительно утвержденного номера телефона WhatsApp Business.	`108692048990658`

<ID>

ID номера телефона WhatsApp Business.

Этот объект заменил объект предварительно утвержденного номера телефона WhatsApp Business.

108692048990658

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

curl 'https://graph.facebook.com/v20.0/506914307656634/phone_numbers' \
-H 'Content-Type: text/plain' \
-H 'Authorization: Bearer EAAH7...' \
-d '
{
  "preverified_id": "6635066806614622",
  "country_dial_code": "1",
  "display_phone_number": "5550783881",
  "verified_name": "Lucky Shrub"
}'

Пример ответа

{
  "id": "108692048990658"
}