Перейти к основному содержанию
Номер телефона Veriqa берёт только из канала: его передаёт мессенджер, пользователь его не вводит. Поля телефона на странице входа нет, а номер, набранный в чате сообщением, не принимается. Ваше приложение получает его стандартным claim phone_number в формате E.164, рядом с phone_number_verified.

Когда Veriqa запрашивает номер

Veriqa спрашивает, только если номер нужен вашему приложению, а канал его ещё не дал. Нужен ли номер, определяет уровень требования claim phone_number: Требование действует, только если вход запрашивает scope phone. При Required окно входа предлагает только каналы, способные дать номер; если таких не осталось, /connect/authorize отвечает 400 no_channel_for_required_phone (разбор проблем). Запрос приходит, когда пользователь подтвердил вход — в чате или кнопкой «Да» на странице подтверждения в браузере. Бот отправляет его в тот чат, из которого пользователь входил: короткий текст, кнопку, которая отправляет номер, и вторую кнопку, смысл которой зависит от уровня. Тексты показываются на языке пользователя. Текст запроса — сообщение, вид которого зависит от уровня: phone-number-request для номера Optional, phone-number-request-required для номера Required. Для обоих видов продукт поставляет текст Share your phone number, а для Instagram* и Messenger* — свою формулировку. Переформулировать его можно для тенанта, для одного приложения или для одного канала; для канала — по адресу Veriqa:MessageTemplates:{вид}:BySurface:in-channel:ByChannel:{канал}:Templates. Подписи кнопок в это сообщение не входят: это локализуемые строки, они переводятся через locale-файлы.
Формулировка, заданная для одного вида, на другой не действует. Если вы переформулировали phone-number-request и запрашиваете номер Required, задайте свою формулировку и для phone-number-request-required — иначе пользователь увидит поставляемый текст этого вида.
Окно по умолчанию — 60 секунд. Меняется ключом Veriqa:ClaimCompletion:PhoneOptionalWindow, а для одного приложения — членом ClaimCompletionPhoneOptionalWindow его записи клиента (см. ключи в каталоге объявлений). Окно не заходит за срок транзакции: шаг пропускается не позже чем за 5 секунд до её истечения. Если присланный номер завершает вход, в чате появляется обычная квитанция подтверждённого входа; Отменить вход показывает квитанцию отклонённого.

Что получает ваше приложение

  • phone_number — в E.164: + и цифры. Номер, который канал передал в другом виде, считается отсутствующим: он не выдаётся, а шаг ждёт так, будто пользователь не ответил.
  • phone_number_verified — JSON boolean: true, только если канал доказал, что номер принадлежит отправившему его пользователю, иначе false.
  • Оба claim выходят только под выданным scope phone.
Контакт, не прошедший проверку принадлежности в канале, не принимается, и бот спрашивает снова. Это чужая карточка контакта, пересланный контакт, контакт без подписи или с неверной подписью. Запрос, который не удалось доставить в чат и после повторов, ничего не меняет: шаг ждёт так же, как без ответа.

По каналам

«Кто» — чей код получает номер: адаптер канала Veriqa или ваша собственная интеграция с платформой. Для каналов, адаптера которых ещё нет в поставке, указано, что позволяет API платформы.

MAX

Бот отправляет кнопку «поделиться номером» и callback-кнопку со вторым действием. Номер берётся из vcf_info, только если совпала подпись hash контакта — она вычисляется на токене бота того тенанта, который получил контакт. Когда вход завершается — подтверждением, отказом, ошибкой или истечением срока, — кнопки с сообщения запроса снимаются, а исход приходит новым сообщением под ним. Бот запрашивает номер и в режиме Webhook, и в режиме Polling.

Telegram

Бот отправляет reply-клавиатуру: сверху кнопка «поделиться номером», под ней вторая кнопка; после нажатия клавиатура скрывается, а сообщение с исходом входа убирает её окончательно. Об истечении входа, пока запрос ещё ждёт, бот по той же причине сообщает новым сообщением: клавиатуру снимает только оно. Veriqa принимает только собственный контакт пользователя: user_id контакта должен совпадать с отправителем, а пересланный контакт или карточка из записной книжки отклоняются. Вход на сайт через Telegram (Log In With Telegram) тоже умеет отдавать номер — это ваша собственная интеграция с Telegram, вне Veriqa.
Допустим, обновления (update) бота раздаёте вы сами: один бот обслуживает и ваш код, и Veriqa, а ваш код через OwnsInboundEvent решает, какое событие отдать Veriqa (см. телефон по запросу). Тогда кнопки Пропустить и Отменить вход уходят вашему боту, а не Veriqa: в Telegram это обычные текстовые кнопки без маркера, по которому их можно узнать. Сам присланный контакт узнаётся. Номер Optional тогда пропускается по окну, а Required ждёт до истечения транзакции. Другие способы делить бота сравнивает страница У меня уже есть бот.

WhatsApp

Veriqa узнаёт пользователя WhatsApp по business-scoped user ID (BSUID), а не по номеру. Пока WhatsApp присылает номер с сообщением, токен несёт phone_number с phone_number_verified: true, и ничего не спрашивается. Пользователь, включивший username WhatsApp, может скрыть номер — тогда его сообщения приходят без него. Когда ваше приложение запрашивает номер такого пользователя, запрос отправляется по BSUID: интерактивное сообщение request_contact_info, а следом отдельное сообщение со второй кнопкой — своих кнопок у запроса нет. Карточка контакта, отправленная пользователем вручную (origin = other), отклоняется. Запрос отправляет поставляемый провайдер Meta* Cloud API; провайдер Twilio его не отправляет. Собственный провайдер WhatsApp (IWhatsAppProvider) отправляет запрос, только если реализует SendContactRequestAsync, иначе запрос не доставляется, и шаг ждёт так же, как без ответа.

Instagram*

Аккаунт отправляет одно сообщение: текст запроса с двумя кнопками quick reply под ним. Первую показывает сам Instagram*, и она отправляет номер телефона из профиля Instagram* пользователя; вторая несёт второе действие шага. Instagram* не сообщает, что проверил номер, поэтому токен несёт phone_number с phone_number_verified: false. Номер, набранный пользователем в чате, не принимается — только тот, что отправила кнопка.
Кнопку видит не каждый пользователь. Кнопку, которая отправляет номер, Instagram* показывает только в мобильном приложении и только пользователю, у которого в профиле указан номер телефона; на компьютере quick reply не показываются вовсе — включая вторую кнопку (Meta*: quick replies). Канал при этом считается способным дать номер, поэтому при номере Required Instagram* остаётся в окне входа. Пользователь, которому кнопка не показана, поделиться номером не может: номер Optional пропускается по истечении окна, а при Required вход ждёт, пока не истечёт транзакция или пользователь его не отменит. Другого способа передать номер в этом канале нет.
Поэтому запрос для Instagram* продукт формулирует сам — с подсказкой, что делать, если номера в профиле нет: Ваша формулировка по тому же адресу заменяет поставляемую — сохраните в ней подсказку.

Messenger*

Страница отправляет то же сообщение, что и аккаунт Instagram*: текст запроса с двумя кнопками quick reply под ним — ту, что показывает сам Messenger* и которая отправляет номер телефона из профиля пользователя, и кнопку второго действия шага. Messenger* не сообщает, что проверил номер, поэтому токен несёт phone_number с phone_number_verified: false. Номер, набранный пользователем в чате, не принимается — только тот, что отправила кнопка.
Кнопку видит не каждый пользователь. Кнопку, которая отправляет номер, Messenger* показывает только пользователю, у которого в профиле указан номер телефона (Meta*: quick replies). Канал при этом считается способным дать номер, поэтому при номере Required Messenger* остаётся в окне входа. Пользователь, которому кнопка не показана, поделиться номером не может: номер Optional пропускается по истечении окна, а при Required вход ждёт, пока не истечёт транзакция или пользователь его не отменит.
Запрос для Messenger* продукт формулирует сам — теми же двумя текстами, что и для Instagram*: для номера Optional — по адресу phone-number-request:BySurface:in-channel:ByChannel:messenger, для номера Required — по адресу phone-number-request-required:BySurface:in-channel:ByChannel:messenger. Ваша формулировка по тому же адресу заменяет поставляемую — сохраните в ней подсказку.

Viber

Бот отправляет текст запроса с двумя кнопками под ним: кнопку платформы share-phone, которая отправляет номер телефона аккаунта Viber, и кнопку второго действия шага. Номер приходит сообщением-контактом. Viber не сообщает, пришёл ли контакт с этой кнопки или выбран из адресной книги, и не утверждает, что номер принадлежит отправителю, — поэтому токен несёт phone_number с phone_number_verified: false, и канал никогда не отклоняет контакт как чужой. Номер, набранный пользователем в чате, не принимается — только контакт. Кнопке share-phone нужен клиент Viber с уровнем API 3 или новее; сообщение запроса говорит об этом платформе, и более старый клиент его не получает. На живой платформе шаг не проверялся — см. Viber.

Канал, подключённый по HTTP

Канал, адаптер которого — внешний сервис, даёт номер теми же двумя способами, а какими именно — объявляет его регистрация ключами Http:Capabilities:PhoneNumber:
  • по запросу (OnRequest) — Veriqa передаёт адаптеру запрос с подписями обеих кнопок; адаптер показывает их так, как принято на его платформе, и возвращает событием номер либо второе действие;
  • автоматически (Automatic) — адаптер кладёт номер в идентичность событий, которые отправляет, и ничего не запрашивается.
Канал, не объявивший ни одного способа, номера не даёт и не предлагается для входа, которому номер обязателен. phone_number_verified равен true, только когда выполнены оба условия: регистрация объявила Proof: Proven, и номер получен по запросу либо само событие утверждает, что он подтверждён. Регистрация без Proven никогда не даёт true: Veriqa понижает утверждение адаптера и пишет предупреждение. Номер всегда в E.164: к этой форме его приводит адаптер, Veriqa его не исправляет.

LINE, KakaoTalk, WeChat и Zalo — ваша интеграция

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

Discord и Threema

Ни одна из платформ не отдаёт боту номер телефона пользователя.

Ограничения

  • Окно номера Optional держится в памяти того инстанса, который отправил запрос. Если инстанс остановился раньше, чем окно истекло, шаг не пропускается, и транзакция ждёт до истечения.
  • Запись, связывающая чат с ожидающим запросом, по умолчанию хранится в памяти процесса. При нескольких репликах перенесите её в Redis вместе с остальными канальными хранилищами (канальные хранилища) — иначе номер, пришедший на другую реплику, запроса не найдёт.
  • Когда в одном чате номера ждут два входа, номер достаётся тому, чей запрос пришёл последним; второй ждёт своего окна или истечения. В Telegram сообщение, которым заканчивается любой из них, снимает reply-клавиатуру, какому бы запросу она ни принадлежала: клавиатура на чат одна. Запрос входа, который ещё ждёт, остаётся после этого без кнопок.
  • Кнопки запроса снимает сообщение, которым вход заканчивается, — квитанция исхода (подтверждения, отказа или ошибки) либо сообщение об истечении срока — там, где это позволяет платформа; как именно, сказано в разделах каналов выше. До этого сообщения они остаются в чате — и на время веб-шага, если он идёт за шагом телефона, — а в WhatsApp, где доставленное сообщение не изменить, не снимаются вовсе. - Ссылку на запрос Veriqa держит в записи чата, из которого начат вход, — одном из канальных хранилищ. Если запись потеряна, запрос остаётся, а истечение в чат не сообщается.
  • Номер, отправленный кнопкой после конца шага, не находит ожидающего запроса и не принимается; бот на него не отвечает. Нажатие второй кнопки тогда — обычное сообщение боту.
* Instagram и Messenger — продукты компании Meta, признанной в России экстремистской организацией; её деятельность в стране запрещена.