Перейти к основному содержанию

Общее описание

Этот же каталог есть на сайте veriqa.app/channels.
Пользователь подтверждает вход в мессенджере или почте, которыми и так пользуется, — устанавливать ничего не нужно. Ваше приложение получает обычные токены OpenID Connect, через какой бы канал ни прошёл вход. Любой канал выдаёт базовые claims channel_type, channel_user_id и name — в карточке указано, что канал добавляет к ним. Для каналов, которых ещё нет в поставке, — что позволяет API платформы. Помимо claims, в описании канала используются ещё три термина: секретное сообщение, подтверждение в канале и кнопки в чате.

Секретное сообщение

Секретное сообщение — это сообщение с кодом входа, которое пользователь сам отправляет в канал, когда перешёл по ссылке или отсканировал QR-код. Veriqa заполняет его заранее, мессенджер показывает готовым — остаётся нажать «Отправить». Нужно оно не во всех каналах. Примеры:
  • MAX и Telegram: не нужно — мессенджер сам открывает бота и передаёт ему код.
  • WhatsApp: нужно ради повышенной безопасности — готовое сообщение уходит в один тап.
  • Email: так же, готовым письмом — письмо в один тап (режим Push), — или, опционально, классический magic link.
Вход на компьютере через WhatsApp: камера телефона сканирует QR-код, WhatsApp открывает готовое сообщение, пользователь отправляет его, бот отвечает «Вход подтверждён».

Секретное сообщение в WhatsApp: пользователь сканирует QR-код, и приложение открывает готовое сообщение.

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

Подтверждение в канале — это функция, при которой бот прямо в чате спрашивает, пропустить ли вход: в какое приложение и с какого устройства, — с кнопками «Подтвердить» и «Отклонить». Её можно переключить в автоматический режим — тогда вход происходит без дополнительного запроса. Режим задаётся для всех каналов сразу или для одного канала — см. Veriqa:LoginConfirmation. Примеры:
  • Telegram: вопрос приходит сразу после перехода по ссылке.
  • WhatsApp: вопрос приходит в ответ на секретное сообщение.
  • Email: в канале вопроса нет — по желанию он задаётся на странице в браузере.
Вход на телефоне: пользователь нажимает «Войти через Telegram», подтверждает вход в чате Telegram, бот отвечает «Вход подтверждён».

Подтверждение в канале: бот спрашивает в чате, пользователь отвечает кнопкой.

Кнопки в чате

Кнопки в чате — это сообщения с кнопками, которые канал присылает в переписку после того, как вход подтверждён. В карточке они описаны двумя строками:
  • Форма добора claims — кнопка-ссылка на страницу, где пользователь заполняет claims, которых приложению не хватило. Канал присылает её, когда форма показывается на устройстве, где подтвердили вход, — это решает настройка ClaimCompletionFormSurface клиента.
  • После входа — какие действия Veriqa:CompletionBehavior канал исполняет: WelcomeMessage — приветственное сообщение, Menu — сообщение со списком кнопок, Redirect — сообщение с одной кнопкой-ссылкой.
Кнопку, которую нельзя отрисовать, канал пропускает и пишет Warning в журнал; сообщение, в котором не осталось ни одной кнопки, не отправляется. У WhatsApp, Messenger* и Viber подпись длиннее лимита платформы обрезается с «…». Что каждый канал проверяет до отправки, сказано в Veriqa:CompletionBehavior.

Встроенные мессенджеры

Входят в поставку Veriqa — нужные включаются в конфигурации.

Telegram

Claims сверх базовых: given_name, family_name, preferred_username, locale, pictureНомер телефона: phone_number и phone_number_verified по запросу — пользователь делится номером кнопкой в чате (номер телефона)Подтверждение в канале: даФорма добора claims: да — кнопка-ссылка под сообщениемПосле входа: WelcomeMessage, Menu, RedirectСекретное сообщение: не нужно

WhatsApp

Claims сверх базовых: given_name, preferred_username (если пользователь включил username WhatsApp)Номер телефона: phone_number и phone_number_verified автоматически, когда WhatsApp присылает номер с сообщением; если пользователь скрыл его за username — по запросу, пользователь делится номером кнопкой в чате (номер телефона)Идентификатор пользователя: sub и channel_user_id несут business-scoped user ID (BSUID) — свой для каждого бизнес-портфеля Meta* и новый при смене пользователем номера; preferred_username — подсказка, а не идентичностьПодтверждение в канале: даФорма добора claims: да — сообщение cta_url: текст и одна кнопка, открывающая формуПосле входа: WelcomeMessage, Menu, Redirect. Redirect — сообщение cta_url. В Menu отрисовываются только callback-пункты: до трёх — кнопками ответа, от четырёх до десяти — строками списка, который открывается одной кнопкой; пункты сверх десяти пропускаются. Пункты-ссылки WhatsApp в меню не показывает, и они пропускаются: меню из одной ссылки уходит как Redirect, а меню из нескольких ссылок без callback-пунктов не отправляетсяСекретное сообщение: нужно — в один тап

WhatsApp через Twilio

Тот же канал WhatsApp, но доставка идёт через аккаунт Twilio, а не через Meta* WhatsApp Business Platform — провайдер выбирается одним ключом конфигурации (доставка через Twilio).Claims сверх базовых: given_name, preferred_username (если пользователь включил username WhatsApp)Номер телефона: phone_number и phone_number_verified автоматически, когда WhatsApp присылает номер с сообщением; номер, скрытый за username, не запрашивается — запрос кнопкой в чате отправляет только провайдер Meta* Cloud API (номер телефона)Идентификатор пользователя: sub и channel_user_id несут business-scoped user ID (BSUID), как и у провайдера Meta*; preferred_username — подсказка, а не идентичностьПодтверждение в канале: да — две кнопки быстрого ответаФорма добора claims: через Twilio нет (только у провайдера Meta* Cloud API): форма открывается на окне входа, а при CrossDevicePageOnly вход с недостающим обязательным claim завершается ошибкойПосле входа: выполняется только WelcomeMessage; при Menu и Redirect через Twilio не отправляется ничегоСекретное сообщение: нужно — в один тап

MAX

Claims сверх базовых: given_name, family_name, preferred_username, locale, pictureНомер телефона: phone_number и phone_number_verified по запросу — пользователь делится номером кнопкой в чате (номер телефона)Подтверждение в канале: даФорма добора claims: да — кнопка-ссылка под сообщениемПосле входа: WelcomeMessage, Menu, RedirectСекретное сообщение: не нужно

Instagram*

Пользователь подтверждает вход в Instagram* Direct — в переписке с вашим профессиональным аккаунтом Instagram*. Вход пользователей вне вашей команды требует доступа, который выдаёт Meta* (настройка канала).Claims сверх базовых: preferred_username, pictureНомер телефона: phone_number по запросу, с phone_number_verified: false — пользователь делится номером из своего профиля Instagram* кнопкой в чате; кнопка видна только в мобильном приложении Instagram* и только если номер указан в профиле (номер телефона)Подтверждение в канале: даФорма добора claims: да — шаблон с кнопками: текст и кнопка, открывающая форму. В веб-версии Instagram* шаблон не показывается — что из этого следуетПосле входа: WelcomeMessage, Menu, Redirect — тем же шаблоном. В Menu остаются первые три кнопки, остальные пропускаются. Текст длиннее 640 символов приходит отдельным сообщением перед шаблономСекретное сообщение: не нужно

Messenger*

Пользователь подтверждает вход в Messenger* — в переписке с вашей страницей Facebook*. Вход пользователей вне вашей команды требует доступа, который выдаёт Meta* (настройка канала).Claims сверх базовых: given_name, family_name, picture, locale — когда Meta* разрешает приложению читать профиль пользователяНомер телефона: phone_number по запросу, с phone_number_verified: false — пользователь делится номером из своего профиля кнопкой в чате; кнопка видна, только если номер указан в профиле (номер телефона)Подтверждение в канале: даФорма добора claims: да — шаблон с кнопками: текст и кнопка, открывающая формуПосле входа: WelcomeMessage, Menu, Redirect — тем же шаблоном. В Menu остаются первые три кнопки, остальные пропускаютсяСекретное сообщение: не нужно

WeChat

Пользователь сканирует QR-код в WeChat и подтверждает вход в чате с вашим Official Account. Каналу нужен верифицированный Service Account (настройка канала).Claims сверх базовых: нет — только базовые; в name стоит OpenIDПодтверждение в канале: даФорма добора claims: да — ссылкой в тексте сообщенияПосле входа: WelcomeMessage, Menu, Redirect. Ссылки — Redirect и пункты-ссылки меню — приходят в тексте сообщения, по одной в строке, а callback-пункты — вариантами сообщения-меню. Меню, где есть и те и другие, уходит двумя сообщениями: сначала варианты с текстом, затем ссылкиКвота сообщений: после сканирования QR-кода аккаунт может отправить три сообщения в течение минуты, после сообщения пользователя — пять в течение 48 часов. Вопрос подтверждения, квитанция исхода, ссылка на форму и сообщения после входа расходуют общую квоту; сообщение сверх неё не отправляетсяСекретное сообщение: не нужно

Viber

Пользователь подтверждает вход в Viber, в чате с вашим ботом. Адаптер проверен только на имитации Bot API, на живой платформе Viber он не проверялся. С 5 февраля 2024 года Viber выдаёт новых ботов только на коммерческих условиях — бота и его токен получают у Viber до развёртывания (настройка канала).Claims сверх базовых: picture, localeНомер телефона: phone_number по запросу, с phone_number_verified: false — пользователь делится номером кнопкой в чате (номер телефона)Подтверждение в канале: даФорма добора claims: да — кнопка open-url клавиатуры под сообщениемПосле входа: WelcomeMessage, Menu, Redirect — кнопками клавиатуры. Кнопка-ссылка открывает адрес, не показывая его в чате; Viber до версии 6.7 показывает адрес в переписке, а для формы это ссылка с её токеном. На сообщение, в котором нет ничего, кроме одной ссылки, Veriqa не отвечает, даже если его набрал пользователь. Нажатая callback-кнопка меню остаётся в переписке строкой, которая начинается с vq_menu_Секретное сообщение: не нужно

Email

Claims сверх базовых: email, email_verified, preferred_username, veriqa_channel, veriqa_email_modeПодтверждение в канале: нет — опционально через браузерСекретное сообщение: нужно — в один тап, или классический magic linkДва режима: письмо в один тап (пользователь отправляет готовое письмо — значит, доставлять ему ничего не нужно, и почтовый шлюз ничего не отправляет) и классический magic link, включённый по умолчанию. Чем режимы отличаются, описано в разделе какой режим выбрать.Приём письма в один тап: вебхуком провайдера входящей почты либо без него — Veriqa сама читает обычный ящик (письмо в один тап через IMAP).

Instagram* в веб-версии

В веб-версии Instagram* шаблон с кнопками не показывается: пользователь, который читает переписку в браузере, видит текст сообщения без кнопок. Платформа при этом сообщение принимает, и Veriqa считает его доставленным. Меню и кнопку-ссылку после входа такой пользователь не увидит. Что будет с формой добора claims, зависит от ClaimCompletionFormSurface:
  • InitiatingPage, а также Auto, когда у аккаунта есть идентификатор для показа, — не затронуты: ссылка в чат не уходит, форма открывается на окне входа.
  • CrossDevicePage, а также Auto, когда идентификатора у аккаунта нет, — окно входа показывает «Заполните форму на телефоне» и ждёт, пока пользователь не отправит форму по кнопке в мобильном приложении Instagram* или не истечёт срок входа. На окно входа форма не переходит.
  • CrossDevicePageOnly — то же самое. Если пользователь не отправит форму из мобильного приложения, вход завершится по истечении срока, а не ошибкой required_claim_unobtainable.

Вход через аккаунт провайдера

Канал входа через аккаунт провайдера добавляет в приложение вход через аккаунт Google, Apple, Huawei, Яндекс, VK ID или другого провайдера. Такой вход работает не только на том устройстве, где открыто приложение, но и кросс-девайсно. Экран показывает QR-код, пользователь входит в свой аккаунт на собственном телефоне, подтверждает вход на странице там же — и вход завершается на экране. Чем такой вход удобнее и безопаснее обычной кнопки провайдера, рассказано на странице Сервисы аккаунтов. Тем же способом подтверждаются действия. Чата и почтового ящика за таким каналом нет. Вместо них Veriqa показывает на телефоне страницу: на ней вопрос с кнопками Yes и No, сообщения после входа и итог. Канал работает в hop-режиме. Он входит в ядро пакетом Veriqa.Core.ChannelAdapter.WebProviders и включается конфигурацией, по каналу на каждого клиента, зарегистрированного у провайдера, — см. Вход через аккаунт провайдера. На карточках ниже — пять стартовых провайдеров; любой другой провайдер OpenIddict.Client.WebIntegration подключается так же.

Google

Claims сверх базовых: email, email_verified, given_name, family_name, picture, localeПодтверждение в канале: да — на странице на телефонеСекретное сообщение: не нужноПоставка: встроенный канал — Veriqa.Core.ChannelAdapter.WebProviders

Apple

Claims сверх базовых: email, email_verifiedПодтверждение в канале: да — на странице на телефонеСекретное сообщение: не нужноПоставка: встроенный канал — Veriqa.Core.ChannelAdapter.WebProviders

Huawei

Claims сверх базовых: email, email_verifiedПодтверждение в канале: да — на странице на телефонеСекретное сообщение: не нужноПоставка: встроенный канал — Veriqa.Core.ChannelAdapter.WebProviders

Яндекс

Claims сверх базовых: email, given_name, family_nameПодтверждение в канале: да — на странице на телефонеСекретное сообщение: не нужноПоставка: встроенный канал — Veriqa.Core.ChannelAdapter.WebProviders

VK ID

Claims сверх базовых: email, given_name, family_name, pictureПодтверждение в канале: да — на странице на телефонеСекретное сообщение: не нужноПоставка: встроенный канал — Veriqa.Core.ChannelAdapter.WebProviders

Каналы, подключаемые настройкой

Подключите канал, которого нет в поставке, — свой бот, корпоративный мессенджер, региональную платформу — как внешний сервис на любом языке. Veriqa общается с ним по HTTP, а ключи платформы остаются у вашего сервиса. Это же способ встроить в процесс Veriqa уже написанного бота — без публикации нового; остальные способы сравнивает страница У меня уже есть бот.
  • Claims сверх базовых: те, что вернёт ваш адаптер
  • Подтверждение в канале: задаёт адаптер
  • Секретное сообщение: задаёт адаптер

Telegram на Python

Рабочий пример адаптера на Python: тот же бот Telegram, что и у встроенного канала, только подключённый по HTTP. Подходит как образец адаптера на любом языке: часть, которая общается с Veriqa, и часть, которая общается с Telegram, разнесены по разным модулям.Claims сверх базовых: given_name, family_name, preferred_username, locale, pictureНомер телефона: phone_number и phone_number_verified по запросу — пользователь делится номером кнопкой в чатеПодтверждение в канале: да — две кнопки под сообщениемСекретное сообщение: не нужноПример: samples/python/custom-channel-telegram/.

WhatsApp через Twilio на Node

Рабочий пример адаптера на Node: доставляет WhatsApp через аккаунт Twilio отдельным сервисом. Встроенный канал WhatsApp тоже умеет доставлять через Twilio (доставка через Twilio); этот пример — отправная точка для своего адаптера.Claims сверх базовых: phone_number, given_nameПодтверждение в канале: да — две кнопки быстрого ответаСекретное сообщение: нужно — в один тапПример: samples/node/custom-channel-whatsapp-twilio/.

WhatsApp через Baileys

Рабочий пример адаптера на Node: привязывает номер WhatsApp как связанное устройство, как WhatsApp Web, — без бизнес-аккаунта Meta* и без провайдера. Подходит для отладки сценариев с WhatsApp, для небольших команд и для собственного использования.Риск: работает через неофициальный клиент WhatsApp Web, и WhatsApp может заблокировать привязанный номер — привязывайте отдельный номер, который не жалко потерять.Claims сверх базовых: phone_number, given_nameПодтверждение в канале: да — опрос с двумя вариантамиСекретное сообщение: нужно — в один тапПример: samples/node/custom-channel-whatsapp-baileys/.
Отдельным сервисом подключаются и посредники для Instagram* и Messenger* через SendPulse и UChat из репозитория channel-adapters (см. Прочие мессенджеры). Вход через Google, Apple, Huawei и других провайдеров встроен в ядро (см. Вход через аккаунт провайдера); пример samples/dotnet/custom-channel-id-providers/ показывает, как написать для такого входа альтернативный адаптер через HTTP-канал. Как написать такой адаптер, с примерами на Python, Node и .NET, рассказано на странице Свой канал на любом языке.

Прочие мессенджеры

Адаптеры LINE, Slack, Microsoft Teams, Discord, Zalo, KakaoTalk и Threema уже реализованы, но поставляются отдельно от ядра — в репозитории channel-adapters (см. исходный код). Каждый — отдельная .NET-сборка Veriqa.ChannelAdapter.<Канал> на пакете контрактов ядра. Её регистрирует хост, который встраивает Veriqa, вместе с объявлением канала для ядра (CoreChannelDeclaration), — без объявления окно входа канал не предложит. README каждого адаптера описывает поток входа, настройку платформы и минимальный хост; у прошедших живой прогон есть раздел о том, что выяснилось на живой платформе. «Живой прогон» — вход на настоящей платформе с настоящим ботом или приложением; «на имитации API» — полный вход на локальном двойнике API платформы, написанного по её документации.

LINE

Claims сверх базовых: picture, localeСтарт: ссылка line.me с заполненным текстомПроверен: на имитации API

Slack

Claims сверх базовых: given_name, family_name, preferred_username, email, picture, localeСтарт: команда /veriqa <код> в SlackПроверен: живой прогон — подтверждение и отказ

Microsoft Teams

Claims сверх базовых: given_name, family_name, preferred_username, emailСтарт: deep link в чат с ботомПроверен: на имитации API

Discord

Claims сверх базовых: preferred_username, picture, localeСтарт: QR-код или ссылка на страницу авторизации OAuth2 либо команда /veriqa code:<код>; бот должен быть на общем с пользователем сервереПроверен: живой прогон — подтверждение и отказ, claims из настоящего профиля

Zalo

Claims сверх базовых: pictureСтарт: текст auth_<код> ботуПроверен: на имитации API

KakaoTalk

Claims сверх базовых: emailНомер телефона: не через бота — только вашей собственной интеграцией Kakao Login или Kakao Sync (номер телефона)Старт: текст auth_<код> ботуПроверен: на имитации API

Threema

Claims сверх базовых: нет — только базовыеСтарт: ссылка threema.idПроверен: на имитации API
У Slack, Zalo и KakaoTalk нет ссылки, которая донесла бы транзакцию до бота, поэтому окно входа пока не предлагает их само: код входа пользователь получает другим путём. В том же репозитории есть посредники для Instagram* и Messenger* через чат-боты SendPulse и UChat: в процессе хоста или отдельным сервисом, подключаемым как HTTP-канал. * Instagram, Messenger и Facebook — продукты компании Meta, признанной в России экстремистской организацией; её деятельность в стране запрещена.