phone_number в формате E.164, рядом с
phone_number_verified.
Когда Veriqa запрашивает номер
Veriqa спрашивает, только если номер нужен вашему приложению, а канал его ещё не дал. Нужен ли номер, определяет уровень требования claimphone_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.
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* продукт формулирует сам — с подсказкой, что делать, если номера в
профиле нет:
Ваша формулировка по тому же адресу заменяет поставляемую — сохраните в ней подсказку.
Messenger*
Страница отправляет то же сообщение, что и аккаунт Instagram*: текст запроса с двумя кнопками quick reply под ним — ту, что показывает сам Messenger* и которая отправляет номер телефона из профиля пользователя, и кнопку второго действия шага. Messenger* не сообщает, что проверил номер, поэтому токен несётphone_number с phone_number_verified: false. Номер, набранный пользователем в чате,
не принимается — только тот, что отправила кнопка.
Запрос для 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 держит в записи чата, из которого начат вход, — одном из канальных хранилищ. Если запись потеряна, запрос остаётся, а истечение в чат не сообщается.
- Номер, отправленный кнопкой после конца шага, не находит ожидающего запроса и не принимается; бот на него не отвечает. Нажатие второй кнопки тогда — обычное сообщение боту.