Veriqa:Channels:{Channel} и сделать его вебхук доступным из интернета.
Veriqa.Core.BaseChannels (Telegram, WhatsApp, Email); MAX, Instagram*, Messenger*, WeChat и Viber в него не входят и
ставятся явно — dotnet add package Veriqa.Core.ChannelAdapter.Max,
dotnet add package Veriqa.Core.ChannelAdapter.Instagram,
dotnet add package Veriqa.Core.ChannelAdapter.Messenger,
dotnet add package Veriqa.Core.ChannelAdapter.WeChat,
dotnet add package Veriqa.Core.ChannelAdapter.Viber. Нужен один канал — ставьте только его пакет
(Veriqa.Core.ChannelAdapter.Telegram, .WhatsApp, .Max, .Instagram, .Messenger, .WeChat, .Viber, .Email): вместе с ним приедет
только его SDK, и почтовая библиотека не окажется в установке, которая пускает пользователей
через Telegram. Вызов регистрации от выбора пакета не зависит — adapters.AddTelegram() пишется
одинаково в обоих случаях. Если пакета канала нет, а Add*() вызван — это ошибка компиляции,
а не молчаливо отсутствующий канал. Вход через аккаунт провайдера — тоже отдельный пакет,
Veriqa.Core.ChannelAdapter.WebProviders, см.
Вход через аккаунт провайдера."Enabled": true; иначе регистрируются лишь его опции и стартовый валидатор, а канал
никогда не появляется на странице входа. Добавляйте только те каналы, которые используете.
Уровень проверки входящего события
У каждой канальной секции есть обязательный ключInboundVerification — он объявляет, как
проверяется подлинность входящего события этого канала. Факт объявляете вы: Veriqa видит лишь то,
что проверка выполнилась и прошла, но не то, чем именно она была.
Значения для поставляемых каналов — по режиму, в котором вы их запускаете:
Polling (в том числе Email, который читает ящик по IMAP) объявлено значение,
отличное от outbound_fetch, при старте в логе появляется Warning; старт при этом продолжается. Полный словарь значений — в
справочнике конфигурации.
Настройки, общие для любого канала с чатом
В секцию любого канала — поставляемого, канала вашего адаптера или HTTP-канала — можно добавить два необязательных ключа. Задавать их не требуется: развёртывание, которое о них молчит, ведёт себя так, как описано на этой странице.Telegram

Что видит пользователь: QR-код, камера телефона, одно касание в Telegram.
Webhook Veriqa регистрирует вебхук сам на старте (и снимает при остановке) — вы не
вызываете setWebhook вручную. Эндпоинт — POST {WebhookBaseUrl}/api/channels/telegram/webhook, а
заголовок X-Telegram-Bot-Api-Secret-Token каждого запроса Veriqa сверяет с WebhookSecretToken.
Регистрация не задерживает старт: если Bot API не отвечает или отказывает, хост всё равно стартует,
пишет предупреждение в лог и повторяет попытки в фоне, а пауза между ними растёт до пяти минут. Пока
вебхук не зарегистрирован, проверка здоровья каналов показывает канал unhealthy.

Что видит пользователь: QR-код, камера телефона, отправка готового сообщения в WhatsApp.
BusinessPhoneNumber — номер в формате E.164, на который пишут пользователи; на него указывают
deep link и QR-код.
В отличие от Telegram, вебхук регистрируется на стороне Meta*. В панели приложения WhatsApp →
Configuration задайте callback URL https://auth.your-domain.com/api/channels/whatsapp/webhook,
вставьте тот же WebhookVerifyToken и подпишитесь на поле messages. Meta* верифицирует URL
запросом GET с hub.mode и hub.verify_token; Veriqa отвечает на него автоматически, как только
канал включён и хост публично доступен.
Каждый следующий POST Meta* подписывает заголовком X-Hub-Signature-256, а Veriqa сверяет подпись
с AppSecret. Если AppSecret не задан или неверен, Veriqa отвергает и подлинные доставки.
MetaCloudApi, по умолчанию) и
Twilio (Twilio). Ключ Provider выбирает, какой из них регистрируется, и объявляет, какого
провайдера ожидает установка; на старте он сверяется с фактически зарегистрированным. Собственный
провайдер, подключённый через UseWhatsAppProvider<TProvider>(), заменяет поставляемый, и в
Provider ставится его код. Расхождение останавливает хост с ошибкой, называющей оба кода.
Такой провайдер обязан заполнять SenderUserId каждого входящего сообщения business-scoped user ID
(BSUID) отправителя — сообщение без него отклоняется — и получает BSUID как получателя каждого
исходящего сообщения.Доставка через Twilio
Что нужно: аккаунт Twilio (Account SID и Auth Token), WhatsApp-отправитель (чтобы попробовать — Twilio Sandbox for WhatsApp, в продакшне — зарегистрированный отправитель) и контентtwilio/quick-reply, созданный в Twilio Content Template Builder.
BusinessPhoneNumber — номер отправителя Twilio (при Sandbox — номер песочницы). При
Provider = Twilio обязательны AccountSid, AuthToken, QuickReplyContentSid и WebhookUrl:
без любого из них хост не стартует, а ошибка называет ключ, но не его значение. ApiBaseUrl
необязателен, по умолчанию https://api.twilio.com. Учётные данные Twilio тенант хранит в той
же группе WhatsApp, что и учётные данные Meta*.
Контент quick-reply. Вопрос подтверждения уходит одним контентом с двумя кнопками. Создайте его
типа twilio/quick-reply ровно с этими переменными — Veriqa заполняет их сама:
POST): https://auth.your-domain.com/api/channels/whatsapp/webhook. Twilio
подписывает каждый запрос заголовком X-Twilio-Signature, посчитанным над URL, который знает
он, поэтому WebhookUrl должен совпадать с этим URL символ в символ — схема, хост, порт, путь и
query. За прокси Veriqa видит свой внутренний адрес, поэтому URL берётся из конфигурации, а не из
запроса; расхождение отвергает каждое входящее сообщение с 403. Тенант со своим маршрутом вебхука
указывает свой WebhookUrl. GET-рукопожатия у Twilio нет: GET на вебхук отвергается.
При Sandbox каждый тестовый телефон один раз присоединяется к песочнице, отправив на её номер
join <keyword>; ключевое слово показано в консоли Twilio.
Этот провайдер работает внутри Veriqa. Пример node/custom-channel-whatsapp-twilio — другое: внешний
адаптер, работающий отдельным сервисом под собственным типом канала, см.
Свой канал на любом языке.
Текст предзаполненного сообщения
WhatsApp — единственный из поставляемых каналов, где deep link несёт текст сообщения, а не служебный параметр: пользователь видит его в поле ввода и отправляет как обычное сообщение. Текст зависит от того, где открывается ссылка. Кнопка канала и ссылка, к которой ведёт QR-код hop-режима, несут сообщение с линейками. В QR-код, который несёт саму ссылку, идёт короткое сообщение без графики: каждый лишний символ делает такой QR-код плотнее (см. предупреждение ниже). Код входа в обоих стоит на последней строке:wwwroot/locales/{язык}.json, см. Локализация). Ключей
четыре: у каждого из двух сообщений есть полный вариант с именем приложения и запасной без него.
Запасной используется, когда имя приложения недоступно. Отдельной секции в Veriqa:Channels:WhatsApp
для текста нет.
deeplink-prefill:ByType:confirmation, поэтому правка ключей входа их не меняет.
Какое сообщение получает какая ссылка, задаёт конфигурация шаблонов deeplink-prefill — ось
link_purpose в Veriqa:MessageTemplates.
Чтобы, например, кнопка тоже получала короткое сообщение, задайте там свой шаблон для button.
Свой текст задаётся значением этих ключей (для английского — правкой en.json). Доступны два
слота: {app} — имя приложения, к которому идёт вход, и {code} — код входа auth_…. Язык
берётся из транзакции, поэтому переводить стоит все языки, которые вы поставляете.
Имя приложения приходит из регистрации вашего OIDC-клиента и подставляется как есть —
Veriqa его не сокращает (общий предел значения слота — 128 символов). Держите имя коротким:
длинное ломает вёрстку сообщения и целиком уходит в QR-код, увеличивая его плотность
(см. предупреждение ниже).
Отсюда следуют правила оформления:
- код — последней отдельной строкой: его длина — 48 символов (
auth_+ идентификатор транзакции на 43 символа) и не влезает ни в какую рамку; - не использовать
*,_,~как элементы графики — WhatsApp трактует их как разметку (жирный, курсив, зачёркнутый). Безопасны-,.,:,+,|; - рамки с вертикальными палками (
|…|) выравниваются только внутри моноширинного блока (тройные бэктики) — в обычном сообщении шрифт пропорциональный и рамка разъедется. Часть клиентов к тому же показывает в поле ввода сами бэктики, а моноширинность — уже в отправленном сообщении, поэтому такое оформление проверяйте на устройстве до запуска; - горизонтальные линейки (
------) работают в любом клиенте и обёртки не требуют.
{app} и {code} подставит Veriqa.
\n.
Например, так QR-код с самой ссылкой получит линейки, как у кнопки:
{app} — приблизительное: имя приложения у каждого клиента своей длины, поэтому
ни центрирование пробелами, ни правая граница рамки не сойдутся точно. Если рамка нужна ровной —
берите вариант без имени приложения.MAX

Что видит пользователь: QR-код, камера телефона, одно касание в MAX.
Webhook. При остановке она снимает
свою подписку — ту, что зарегистрировала на этот адрес. Эндпоинт —
POST {WebhookBaseUrl}/api/channels/max/webhook, аутентифицируется заголовком X-Max-Bot-Api-Secret.
BotPublicName — имя, показываемое пользователю на странице входа.
ApiBaseUrl — адрес MAX Bot API, на который канал отправляет все запросы. По умолчанию это
https://platform-api2.max.ru: с 19 июля 2026 года MAX требует от ботов обращаться на этот домен.
Меняйте значение, только если MAX объявит другой адрес. Это настройка установки, а не тенанта.
Значение должно быть абсолютным HTTPS-адресом из схемы, хоста и при необходимости порта, без пути,
строки запроса и фрагмента, иначе хост не запустится.
Instagram*
Пользователь подтверждает вход в Instagram* Direct — в переписке с вашим аккаунтом Instagram*. Канал работает на Instagram* API with Instagram* Login и обращается кgraph.instagram.com по обычному
HTTP — SDK платформы в пакете нет.

Что видит пользователь: QR-код, камера телефона, одно касание в Instagram*. Интерфейс на английском.
"Enabled": true обязательны AppSecret, WebhookVerifyToken, AccessToken, AccountId и
Username: если любой из них пуст, развёртывание не стартует, а сообщение об ошибке называет ключ. У GraphApiBaseUrl и
GraphApiVersion есть значения по умолчанию; это настройки установки, а пять обязательных ключей —
учётные данные тенанта.
Ссылка входа — https://ig.me/m/{Username}?ref=auth_{transactionId}. Она открывает переписку с
вашим аккаунтом, Instagram* передаёт значение ref в Veriqa, и пользователь получает вопрос с
кнопками подтверждения и отказа; итог приходит отдельным сообщением.
Когда значение ref не дошло, у входа есть второй способ начаться. Страница входа показывает
под кнопкой и QR-кодом Instagram* короткий код; пользователь отправляет его вашему аккаунту
сообщением — одни цифры, с пробелами или без, — и вход начинается так же, как по ссылке. На код,
по которому вход не нашёлся, — набранный с ошибкой, истёкший или уже использованный — ответ один
на все причины: сверьте код на странице входа и отправьте его ещё раз либо откройте страницу входа
заново.
Код появляется тогда, когда он может понадобиться, а не вместе со страницей, и только пока ваш
аккаунт не ответил. Где он появится, зависит от устройства, на котором открыта страница входа:
- Компьютер или планшет показывает код через 8 секунд после загрузки — если только QR-код Instagram* на странице не hop-QR hop-режима. Тогда код ждёт перехода телефона в Instagram*, и страница входа показывает его под инструкцией «продолжите на телефоне» через 6 секунд после перехода.
- Телефон сам код не открывает. Когда пользователь нажал кнопку Instagram* и вернулся на страницу, под строкой состояния появляется ссылка «Проблема со входом» — для канала, нажатого последним; ссылка открывает код. Перезагрузка страницы нажатие забывает.
- Страница, которую телефон открывает по QR-коду hop-режима с несколькими каналами, оставляет выбор канала ему. Нажатие кнопки Instagram* переводит её на этот канал: заголовок и инструкция уступают место «Продолжите в Instagram*» со значком канала, кнопки каналов скрываются, а ссылка «Вернуться к выбору канала» под ним возвращает выбор, не трогая вход. По возвращении из приложения под строкой состояния появляется ссылка «Проблема со входом», и код за ней идёт с кнопкой «Скопировать и открыть Instagram*», как на странице запуска. Когда ваш аккаунт ответил или вход закончился, путь назад к выбору исчезает со страницы насовсем.
- Страница запуска на телефоне в hop-режиме предлагает код за той же ссылкой через 6 секунд после того, как увела пользователя в приложение. Код там идёт с одной кнопкой — «Скопировать и открыть Instagram*»: она копирует код и открывает приложение. Когда код открыт, кнопка Instagram* над ним со страницы исчезает.
SpareStartCodeEnabled.
На нажатую кнопку, которая не называет вход, — Icebreaker, нажатый без ссылки за ним, — канал
отвечает подсказкой ровно об этом: отправьте код со страницы входа или отсканируйте QR-код ещё раз.
Набранное сообщение, которое не код и не маркер входа, ответа не получает: человек, пишущий
вашему аккаунту о другом, входа не просит. Чтобы выключить подсказку, добавьте в секцию канала
"UnaddressedReplyEnabled": false: на такое нажатие ваш аккаунт не ответит ничего, а код
продолжит работать. Ключ необязателен, значение по умолчанию — true. Оба ответа — обычные тексты канала:
их формулировка меняется в locale-файлах.
Вебхук регистрируется на стороне Meta*, как и у WhatsApp. В Meta*-приложении задайте callback URL
https://auth.your-domain.com/api/channels/instagram/webhook, вставьте тот же WebhookVerifyToken
и подпишитесь на поля messages, messaging_postbacks и messaging_referral. Meta* верифицирует
URL запросом GET с hub.mode, hub.verify_token и hub.challenge; Veriqa отвечает на него
автоматически, как только канал включён и хост публично доступен. Каждый последующий POST
подписывается заголовком X-Hub-Signature-256 — HMAC-SHA256 тела запроса на секрете приложения, — и
доставка без подписи или с неверной подписью отклоняется
(Meta*: webhooks).
Разрешения: instagram_business_basic и instagram_business_manage_messages
(Meta*: send messages).
Тенант со своим Meta*-приложением получает тот же адрес с именем тенанта последним сегментом:
https://auth.your-domain.com/api/channels/instagram/webhook/{tenant}. Без сегмента доставка
относится к тенанту по умолчанию; на доставку для тенанта, которому канал не разрешён, приходит
ответ 403.
- Окно 24 часа. Аккаунт может писать пользователю только в течение 24 часов после его последнего сообщения аккаунту (Meta*: send messages). Вход в него укладывается: каждое сообщение сценария отвечает пользователю, только что открывшему ссылку.
- Реферал может не прийти, пока Meta*-приложение в режиме разработки. Пользователь открывает
ссылку
ig.me, а Instagram* ничего не доставляет на вебхук. Это ограничение платформы, а не адаптера. Вход тогда начинается кодом со страницы входа: пользователь отправляет его аккаунту сообщением. - Первое нажатие нового пользователя может прийти без значения
ref. Пока пользователь ни разу не писал вашему аккаунту, открытие ссылкиig.meсамо ничего не доставляет: Instagram* сообщает о ссылке вместе с первым действием пользователя — нажатым Icebreaker или отправленным сообщением (Meta*: ссылки ig.me). Настройте Icebreakers аккаунта до того, как предлагать канал, чтобы новому пользователю было что нажать, — но и это первое нажатие может дойти до Veriqa без значенияref. Пользователь тогда получает подсказку (если вы её не выключили) и продолжает кодом со страницы входа либо сканирует QR-код ещё раз: переписка к этому моменту уже есть, и Instagram* сообщает о ссылке сразу. Ссылка работает только в мобильном приложении Instagram*. - Ссылка входа не срабатывает из открытой переписки с аккаунтом. Если у пользователя в приложении Instagram* уже открыта переписка с вашим аккаунтом, ссылка
ig.meпросто возвращает его в неё, а значениеrefв Veriqa не приходит — вход не начинается. С любого другого экрана приложения ссылка работает. Пользователю достаточно отправить в эту переписку код со страницы входа либо выйти из неё и открыть ссылку ещё раз. От hop-режима и стиля перехода это не зависит. Наблюдалось на Instagram* для iPhone в октябре 2026; поведение принадлежит платформе и может измениться. - Одно событие на доставку. Когда Meta* кладёт в одну доставку вебхука несколько событий, Veriqa обрабатывает одно из них, а остальные пропускает: событие, называющее вход (открытая ссылка, нажатая кнопка), идёт раньше переданного номера телефона, а тот — раньше любого другого сообщения.
- Текст вопроса обрезается до 640 символов — это лимит сообщения с кнопками (Meta*: button template).
- Языка пользователя нет. Instagram* не сообщает адаптеру язык пользователя, поэтому сообщения идут на языке входа.
- Номер телефона запрашивается кнопкой, которую Instagram* показывает только в мобильном приложении и только пользователю с номером в профиле, — см. номер телефона.
Messenger*
Пользователь подтверждает вход в Messenger* — в переписке с вашей страницей Facebook*. Канал работает на Messenger* Platform и обращается кgraph.facebook.com по обычному HTTP — SDK платформы в пакете
нет.

Что видит пользователь: QR-код, камера телефона, одно касание в Messenger*. Интерфейс на английском.
"Enabled": true обязательны PageId, PageAccessToken, AppSecret, WebhookVerifyToken и
InboundVerification (для Messenger* — signature), а если DeepLinkByPageId не включён, — ещё и
PageName. Если любой из них пуст, развёртывание не стартует, а сообщение об ошибке называет ключ.
У GraphApiBaseUrl и GraphApiVersion есть значения по умолчанию; это настройки установки, а
PageId, PageName, PageAccessToken, AppSecret и WebhookVerifyToken — учётные данные тенанта.
Ссылка входа — https://m.me/{PageName}?ref=auth_{transactionId}. Она открывает переписку с вашей
страницей, Messenger* передаёт значение ref в Veriqa, и пользователь получает вопрос с кнопками
подтверждения и отказа; итог приходит отдельным сообщением. В уже существующей переписке значение
ref приходит событием реферала, в новой Messenger* сообщает его вместе с нажатием кнопки Get Started
(Meta*: ссылки m.me) —
и это первое нажатие может дойти до Veriqa без значения ref.
Если ссылка открывает магазин приложений вместо переписки, добавьте в секцию канала
"DeepLinkByPageId": true. Ссылка станет https://m.me/{PageId}?ref=auth_{transactionId}, а
PageName больше не нужен. Ссылка по username — единственная форма, которую описывает Meta*, поэтому
она остаётся значением по умолчанию; ссылка по идентификатору — для страницы, чья ссылка по username
не открывает переписку в приложении Messenger* (наблюдалось на iPhone с установленным Messenger* в
октябре 2026 года).
Когда значение ref не дошло, у входа есть второй способ начаться. Страница входа показывает
под кнопкой и QR-кодом Messenger* короткий код; пользователь отправляет его вашей странице
сообщением — одни цифры, с пробелами или без, — и вход начинается так же, как по ссылке. На код,
по которому вход не нашёлся, — набранный с ошибкой, истёкший или уже использованный — ответ один
на все причины: сверьте код на странице входа и отправьте его ещё раз либо откройте страницу входа
заново. Код появляется и исчезает на условиях, описанных для Instagram*: показывается,
когда может понадобиться, и скрывается, как только ваша страница ответила.
На iPhone путь в Messenger* может пройти через страницу браузера. В hop-режиме, как только замечен
переход телефона в Messenger*, инструкция «продолжите на телефоне» на странице входа получает ещё одну
строку: «На iPhone сначала может открыться страница браузера с двумя кнопками. Нажмите ту, что
открывает Messenger*, затем подтвердите, что хотите открыть приложение Messenger*.» Операционную систему
телефона страница входа не знает, поэтому строка написана для iPhone и показывается для любого
телефона; она исчезает вместе с кнопкой «Выбрать другой способ» и как только ваша страница ответила.
Страница запуска на телефоне показывает ту же строку под своей инструкцией, тоже на любом телефоне.
Это подсказка канала: её текст и каналы, которые её получают, задаёт вид сообщения hop-channel-hint
(см. строки канала).
На нажатую кнопку, которая не называет вход, — Get Started, нажатый без ссылки за ним, — канал
отвечает подсказкой ровно об этом: отправьте код со страницы входа или отсканируйте QR-код ещё раз.
Набранное сообщение, которое не код и не маркер входа, ответа не получает: человек, пишущий
вашей странице о другом, входа не просит. Чтобы выключить подсказку, добавьте в секцию канала
"UnaddressedReplyEnabled": false: на такое нажатие ваша страница не ответит ничего, а код
продолжит работать. Ключ необязателен, значение по умолчанию — true. Оба ответа — обычные тексты канала:
их формулировка меняется в locale-файлах.
Вебхук регистрируется на стороне Meta*, как и у WhatsApp. В Meta*-приложении задайте callback URL
https://auth.your-domain.com/api/channels/messenger/webhook, вставьте тот же WebhookVerifyToken
и подпишите страницу на поля messages, messaging_postbacks и messaging_referrals — два
последних и доставляют ref ссылки m.me
(Meta*: messaging_referrals).
Meta* верифицирует URL запросом GET с hub.mode, hub.verify_token и hub.challenge; Veriqa
отвечает на него автоматически, как только канал включён и хост публично доступен. Каждый
последующий POST подписывается заголовком X-Hub-Signature-256 — HMAC-SHA256 тела запроса на
секрете приложения, — и доставка без подписи или с неверной подписью отклоняется.
Тенант со своим Meta*-приложением получает тот же адрес с именем тенанта последним сегментом:
https://auth.your-domain.com/api/channels/messenger/webhook/{tenant}. Без сегмента доставка
относится к тенанту по умолчанию; на доставку для тенанта, которому канал не разрешён, приходит
ответ 403.
- Реферал может не прийти, пока Meta*-приложение в режиме разработки. Пользователь открывает
ссылку
m.me, а Messenger* ничего не доставляет на вебхук. Это ограничение платформы, а не адаптера. Вход тогда начинается кодом со страницы входа: пользователь отправляет его странице сообщением. - Окно 24 часа. Страница отвечает пользователю в стандартном окне переписки — 24 часа после его последнего сообщения. Вход в него укладывается: каждое сообщение сценария отвечает пользователю, только что открывшему ссылку.
- Профилю нужны свои разрешения. Имя и фото читаются при функции Business Asset User Profile
Access, язык — при разрешении
pages_user_locale. Без них вход всё равно завершается: пользователя определяет page-scoped ID, а в токене нетgiven_name,family_name,pictureиlocale. - Одно событие на доставку. Когда Meta* кладёт в одну доставку вебхука несколько событий, Veriqa обрабатывает одно из них, а остальные пропускает: событие, называющее вход (открытая ссылка, нажатая кнопка), идёт раньше переданного номера телефона, а тот — раньше любого другого сообщения.
- Текст вопроса обрезается до 640 символов — это лимит сообщения с кнопками.
- Язык сообщений — язык профиля Facebook* пользователя, если у приложения есть разрешение
pages_user_locale, иначе язык входа: сам вебхук языка пользователя не несёт. - Номер телефона запрашивается кнопкой, которую Messenger* показывает только пользователю с номером в профиле, — см. номер телефона.
api.weixin.qq.com по обычному HTTP — SDK платформы в пакете нет.
Что нужно: верифицированный Service Account WeChat — платформа верифицирует юридическое лицо, —
а из его консоли AppID и AppSecret, плюс Token, который вы сами задаёте в настройке сервера
аккаунта.
"Enabled": true обязательны первые три ключа, а с ними и InboundVerification — его значение
для WeChat shared_secret: если любой из них пуст, развёртывание не стартует, а сообщение об
ошибке называет ключ.
ApiBaseUrl — настройка установки; остальные три — учётные данные тенанта.
Ссылку здесь строить не из чего: на каждый вход Veriqa запрашивает у платформы временный QR-код со
сценой auth_{transactionId}, и страница входа показывает именно его. Пользователь сканирует код в
WeChat — тот, кто ещё не подписан на аккаунт, сначала подписывается — и получает вопрос с двумя
вариантами под ним; нажатие варианта и есть ответ, а итог приходит отдельным сообщением. Код живёт
30 минут — это наибольший допустимый срок жизни транзакции, поэтому код не истекает раньше входа.
Вебхук задаётся на стороне платформы. В настройке сервера аккаунта укажите URL
https://auth.your-domain.com/api/channels/wechat/webhook, введите тот же Token и выберите режим
сообщений без шифрования. Платформа проверяет URL запросом GET с signature, timestamp, nonce
и echostr; Veriqa отвечает на него автоматически, как только канал включён и хост публично
доступен. Каждый запрос — и эта проверка, и любой POST после неё — подписан SHA-1 над Token,
меткой времени и nonce; запрос без подписи, с неверной подписью или подписанный более чем в пяти
минутах от часов хоста отклоняется.
Тенант со своим Official Account получает тот же адрес с именем тенанта последним сегментом:
https://auth.your-domain.com/api/channels/wechat/webhook/{tenant}. Без сегмента запрос относится к
тенанту по умолчанию; на запрос для тенанта, которому канал не разрешён, приходит ответ 403.
Подпись проверяется Token этого тенанта, и у каждого аккаунта свой access-токен.
Что ограничивает платформа:
- Окно сообщений. Аккаунт может отправить три сообщения в течение минуты после скана и пять в течение 48 часов после сообщения пользователя. Вход в него укладывается: вопрос идёт за сканом, итог — за нажатым вариантом. Сообщение вне окна платформа отклоняет, и повторно оно не уходит.
- Только режим без шифрования. Доставка в шифрованном режиме не читается.
- Медленный ответ повторяет вопрос. Платформа доставляет событие повторно, не получив ответа за пять секунд, и канал не отличает такую доставку от нового скана — пользователь может получить вопрос дважды. Ответить можно на любой из двух вопросов.
- OpenID и больше ничего. Платформа не даёт Official Account ни имени, ни фото, ни языка
пользователя: в токене только базовые claims, в
nameстоит OpenID, а сообщения идут на языке входа. - Номера телефона нет. У Official Account нет способа запросить номер телефона в чате, поэтому канал его не даёт — см. номер телефона.
- Подтверждённый способ входа — скан. Кнопка канала открывает содержимое того же QR-кода. Передаёт ли мобильный браузер этот адрес приложению WeChat и что делает с кодом системная камера, не подтверждено — рассчитывайте на сканер самого WeChat.
- Несколько хостов, один аккаунт. Access-токен берётся вызовом stable-token платформы, поэтому хосты одного аккаунта не отзывают токен друг у друга.
- Имя
wechatзанято. HTTP-канал, зарегистрированный под этим именем, останавливает старт хоста — переименуйте его.
Viber
Пользователь подтверждает вход в Viber, в чате с вашим ботом. Канал обращается кchatapi.viber.com по обычному HTTP — SDK платформы в пакете нет.
Что нужно: бот Viber, а от Viber — его токен аутентификации и URI.
"Enabled": true обязательны AuthToken, BotUri и WebhookBaseUrl, а с ними и
InboundVerification — его значение для Viber signature: если любой из них пуст, развёртывание
не стартует, а сообщение об ошибке называет ключ. У SenderName и ApiBaseUrl есть значения по умолчанию.
WebhookBaseUrl и ApiBaseUrl — настройки установки; AuthToken, BotUri и SenderName —
учётные данные тенанта.
Ссылка входа — viber://pa?chatURI={BotUri}&context=auth_{transactionId}. Она открывает чат с
вашим ботом, Viber передаёт значение context в Veriqa, и пользователь получает вопрос с кнопками
подтверждения и отказа; итог приходит отдельным сообщением.
Вебхук собственного бота установки регистрирует Veriqa. Как только хост начал принимать
запросы, он вызывает set_webhook с адресом {WebhookBaseUrl}/api/channels/viber/webhook и
подписывается на событие conversation_started; сообщения пользователя доставляются вебхуку без
подписки. Viber отвечает на этот вызов только после того, как отправил на адрес проверочный запрос
и получил 200, поэтому к этому моменту хост должен быть публично доступен по HTTPS. Отклонённая
регистрация пишется в лог предупреждением и хост не останавливает: остальные каналы продолжают
работать, а Veriqa повторяет попытки в фоне, и пауза между ними растёт до пяти минут. Пока вебхук не
зарегистрирован, проверка здоровья каналов показывает канал unhealthy. При остановке хост вебхук
снимает.
Каждая доставка несёт заголовок X-Viber-Content-Signature — HMAC-SHA256 тела запроса ключом —
токеном бота, в шестнадцатеричной записи. Доставка без подписи или с неверной подписью отклоняется.
Тенант со своим ботом получает тот же адрес с именем тенанта последним сегментом:
https://auth.your-domain.com/api/channels/viber/webhook/{tenant}. Veriqa регистрирует вебхук
только собственного бота установки. Вебхук бота тенанта регистрирует тот, кто заводит тенанта:
вызов set_webhook с токеном этого бота, адресом с сегментом {tenant} и типом события
conversation_started
(Viber: setting a webhook).
Без сегмента доставка относится к тенанту по умолчанию; на доставку для тенанта, которому канал не
разрешён, приходит ответ 403. Подпись проверяется токеном, который разрешается для этого
тенанта, — его собственным, а если своего нет — токеном установки.
Что ограничивает платформа:
- Одно сообщение до ответа пользователя. После открытия чата бот может отправить одно сообщение; следующее пройдёт только после того, как пользователь написал боту. Вход в это укладывается: вопрос и есть это одно сообщение, а нажатие кнопки подтверждения или отказа — ответ пользователя.
- Нажатие видно в чате. Кнопка клавиатуры Viber отправляет своё значение сообщением
пользователя, поэтому в переписке появляется строка, начинающаяся с
vq_confirm_илиvq_decline_. - Отправленное сообщение изменить нельзя. Итог всегда приходит новым сообщением; оно же убирает кнопки вопроса.
- Профиль — то, что несёт событие: имя, фото и язык пользователя. Сообщения идут на этом языке; если его нет — на языке входа.
- Номер телефона запрашивается кнопкой
share-phone, и Viber не доказывает, что номер принадлежит пользователю, — см. номер телефона. - Опроса нет. Bot API доставляет события только вебхуком, поэтому канал не работает на хосте, недоступном из интернета.
- Имя
viberзанято. HTTP-канал, зарегистрированный под этим именем, останавливает старт хоста — переименуйте его.
- Pull (magic link) — Veriqa отправляет письмо со ссылкой, пользователь переходит по ней. Включено
по умолчанию (
PullEnabled). Вместо ссылки письмо может нести код, который вводится на странице, или и то и другое — см. Ссылка, код или оба. - Push — письмо в один тап (one-tap email) — пользователь отправляет готовое письмо на
входящий адрес (один тап с кнопки или по QR-коду), Veriqa его читает. Выключено по умолчанию
(
PushEnabled); требует входящей доставки и политики верификации отправителя.Push— значение в конфигурации; «письмо в один тап» — как режим называется для пользователей.
PublicBaseUrl обязателен всегда, когда канал включён — из него строятся magic-link и QR-код.
TokenTtl — срок жизни magic-link, кода письма входа и токенов добора claims; токен письма входа Push живёт иначе —
до истечения своей транзакции.
MailResendInterval — наименьшее время между двумя письмами одного входа, см.
Повторная отправка письма.
Port: 587 с UseSsl: false означает STARTTLS; UseSsl: true означает неявный TLS на порту 465.
RequireStartTls (по умолчанию true) действует, когда UseSsl равен false и заданы Username
и Password: если сервер не предлагает STARTTLS, соединение отвергается — пароль никогда не уходит
открытым текстом. Ставьте false только для внутреннего релея, к которому вы сознательно ходите без
TLS: тогда STARTTLS применяется, лишь если сервер его предложил. На анонимный релей (без учётных
данных) настройка не влияет.
Username и Password задаются только вместе. Обе настройки пустые — допустимая конфигурация:
это релей без аутентификации, типовой вариант для внутреннего SMTP в контуре компании. А вот
заданное ровно одно из двух приложение отвергает на старте: аутентификация в таком случае не
выполнялась бы вовсе, то есть указанное значение молча никогда не применялось бы. Если Veriqa
не стартует с сообщением про Username и Password — удалите лишнее из двух значений либо задайте
оба.
Какой режим выбрать
Magic link включён по умолчанию и не требует ничего, кроме исходящей почты, — это более дешёвый старт. Письму в один тап нужны способ принимать почту и политика отправителя; отдельный провайдер входящей почты для него не обязателен: Veriqa умеет читать обычный ящик сама, см. Письмо в один тап через IMAP. Оно даёт четыре вещи, которых magic link дать не может:- Пользователю ничего не нужно доставлять. Письмо идёт в обратную сторону, поэтому вход
больше не зависит от того, дойдёт ли ваше исходящее письмо: ни папки «Спам», ни greylisting, ни
репутации домена. При
PullEnabled: falseканалу вообще не нужен SMTP — валидатор настроек требует блок исходящей почты только при включённом Pull. - Нет ссылки, которую израсходует почтовый шлюз. Корпоративная почтовая защита открывает ссылки во входящих письмах для проверки, и одноразовый magic link может быть израсходован до того, как по нему перейдёт человек. В письме, которое отправляет сам пользователь, такой ссылки нет.
- Доказывается владение ящиком, а не факт получения письма. Переход по ссылке показывает, что
письмо до кого-то дошло, — в том числе через правило пересылки или общий ящик. Отправка письма
показывает, что отправитель управляет ящиком, и отправитель проверяется политикой
VerificationPolicy(по умолчаниюDmarcAlignedPass). - Это то же действие, что и в мессенджерах. Пользователь отправляет готовое сообщение в один тап — секретное сообщение. Email — тот же приём, только письмом вместо сообщения в чате: страница входа учит одной привычке, а не двум.
PreferredMode решает, какой из них страница входа
предлагает первым, а при первом Push на странице входа, пока включён Pull, остаётся поле адреса —
запасной путь через magic link.
Режимы для одного тенанта или приложения
PullEnabled и PushEnabled задают режимы, которые обслуживает установка. Тенант и приложение
выбирают из них членами Channels:Email:SignInModes и Channels:Email:PreferredMode своей записи —
см. Режимы входа по Email для одного приложения.
Вход и подтверждение предлагают режимы, оставшиеся после этого выбора. Где эта страница описывает,
что показывает вход при включённом Pull или Push, имеется в виду, что режим есть среди них.
- Выбор только сужает. Запись не включает режим, выключенный в секции. Пустой список или список, в котором нет ни одного режима, обслуживаемого установкой, пропускается с предупреждением в журнале, и действует уровень выше.
- Добор claims зависит от секции. Письма с кодом и ссылкой, которыми подтверждается недостающий адрес, уходят, пока Pull включён в секции, — даже у приложения, которое предлагает только Push.
- Список не выключает Email. Для этого служит
Enabledсекции, а клиент сужает каналы своих входов параметромacr_values— см. Как дать клиенту выбрать канал.
Ссылка, код или оба
PullMethods задаёт, что несёт письмо входа: magic link (MagicLink, по умолчанию), код, который
пользователь вводит на той же странице, где ввёл адрес (Code), или то и другое в одном письме. Секция
задаёт значение для установки; тенант и приложение задают своё членом Channels:Email:PullMethods своей
записи. Значение приложения заменяет значение тенанта, а значение тенанта — значение секции. Порядок
значений в списке ничего не меняет. Настройка действует только там, где предлагается Pull.
["MagicLink"]. О пустом списке в записи тенанта или приложения Veriqa пишет предупреждение в журнал.
Код состоит из шести цифр. Он действует до времени, указанного в письме: TokenTtl после отправки
письма, но не дольше самого входа или подтверждения. На ввод даётся SignInCodeAttempts попыток, по
умолчанию 5. Тенант и приложение могут уменьшить это число членом Channels:Email:SignInCodeAttempts
своей записи; большее значение лимит уровня выше не поднимает. Эта настройка не зависит от
ClaimCompletionEmailLimits:CodeAttempts, поэтому лимит добора claims на вход не влияет. Истёкший код
и код без оставшихся попыток не действуют — пользователь запрашивает новое письмо. Каждое новое письмо
несёт новый код, и код прежнего письма перестаёт действовать, как только новое ушло.
Письмо с кодом и ссылкой. Пользователь вводит код или переходит по ссылке, и засчитывается то,
что сделано первым.
Что видит пользователь. Когда письмо ушло, на месте поля адреса и кнопки появляются строка «Код
отправлен на u***@example.com», поле кода и кнопка «Подтвердить». На неверный код страница отвечает
«Неверный код. Осталось попыток: 4». «Отправить снова» возвращает поле адреса с тем же адресом, и
следующее письмо уходит, когда пройдёт MailResendInterval, см.
Повторная отправка письма. Верный код делает то же, что ссылка того же
письма:
- при входе страница продолжает так же, как после ссылки. Там, где вопрос задаёт окно входа, — по
умолчанию у Email, см. Страница ссылки из письма, — окно его задаёт; при
LoginConfirmation.Mode, равномNone, вход завершается. Форма добора claims, которая показывается на устройстве, подтвердившем вход (ClaimCompletionFormSurface: CrossDevicePage), открывается в браузере, где введён код; - при подтверждении браузер, где введён код, переходит на страницу, где показано, что именно подтверждается; там пользователь и отвечает.
/auth/email/start спрашивает код так же: после
верного кода она открывает страницу, которую назвал ответ, или показывает строку, которую при том же
исходе показывает страница ссылки из письма.
В письме с одним кодом нет ссылки, которую корпоративная защита почты может израсходовать, открыв её.
В браузере с выключенным JavaScript форма письмо отправляет, но поля кода страница не показывает. Если
у ваших пользователей могут быть выключены скрипты, оставьте в письме ссылку: ["MagicLink", "Code"].
Своя страница входа. Ответ POST /auth/email/start несёт code_expected — true, когда в письме
есть код. Тогда страница отправляет код в формате JSON на POST /auth/email/code —
{ "session_id": "…", "code": "123456" }. Лимит запросов старта действует и на этот эндпоинт.
session_id эндпоинт отвечает 400, как и старт.
Режим Push — письмо в один тап
Push дополнительно требует блокInbound. Входящая почта попадает в Veriqa одним из двух способов:
провайдер входящей почты отправляет её на вебхук (ниже) либо Veriqa сама читает ящик —
Письмо в один тап через IMAP.
POST https://auth.your-domain.com/api/channels/email/inbound
с заголовком аутентификации X-Email-Webhook-Secret. Эндпоинт принимает один плоский JSON-объект в
собственном формате Veriqa — не родной payload почтового сервиса:
Provider = Custom и зарегистрируйте собственный
IEmailInboundProcessor.
В мультитенантной установке тот же маршрут принимает и необязательный тенант-сегмент —
POST https://auth.your-domain.com/api/channels/email/inbound/{tenant}, — и каждый тенант
прописывает свой сегмент в настройках своего входящего провайдера. Письмо, пришедшее туда,
обрабатывается настройками Inbound и webhook-секретом этого тенанта. Без сегмента маршрут
использует настройки установки целиком.
UsePlusAddressing встраивает correlation-токен в адрес для ответа (login+{token}@…), чем входящее
письмо и привязывается обратно к своей транзакции входа.
VerificationPolicy решает, насколько доверять отправителю: From в письме легко подделать,
поэтому от этой настройки зависит безопасность входа:
Что видит пользователь после нажатия

Что видит пользователь: QR-код, готовое письмо, страница проверяет отправителя, и пользователь подтверждает вход на компьютере.
mailto: с заполненными получателем, темой и текстом. Никакая страница Veriqa между ними не
открывается: телефон, отсканировавший код, или компьютер, на котором нажали кнопку, открывает
почтовый клиент с готовым письмом.
- По нажатию своей кнопки страница входа сама показывает строку «Письмо-подтверждение открыто в почтовом приложении. Отправьте его, чтобы продолжить.». Когда пользователь возвращается на страницу из почтового приложения, а эта строка ещё на ней, строка меняется на «Если вы уже отправили письмо, ожидайте подтверждения — обычно это занимает несколько секунд.». Перезагрузка нажатие забывает.
- Письмо, открытое по QR-коду, странице входа ничего не сообщает, пока не придёт; дальше страница показывает, что письмо получено и чем закончился вход.
- Отправитель, прошедший проверку, — ещё не вход: если вход уже занят учётной записью другого канала, письмо в учётную запись не входит, и вместо «Отправитель подтверждён» страница говорит «Вход уже начат в другом канале.» («Подтверждение уже начато в другом канале.» — на странице подтверждения).
- Там, где спрашивает окно входа (для Email это поведение по умолчанию, см. «Страница ссылки из
письма» ниже), письмо само в учётную запись не входит: оно доказывает владение ящиком, и страница входа переходит к
тому же вопросу, который пришёл бы в чат мессенджера, —
Confirm sign-in to "{app}" — request at {requested_at} from {browser} on {os}, {region}с подставленными значениями. «Да» входит в учётную запись; «Нет» отклоняет вход, и приложение получаетaccess_denied. ПриLoginConfirmation.Mode=Noneписьмо завершает вход само; чтобы убрать вопрос только у Email, задайтеVeriqa:LoginConfirmation:ModeByChannel:email=None.
Inbound:TokenInLocalPart выбирает, в какой форме записан адрес получателя:
deeplink-prefill для канала email. Если токен передаётся в тексте, тема
письма входа — Sign in to {app}: {token}, а письма подтверждения — Confirm in {app}: {token};
без имени приложения тема — Sign in: {token} или Confirm: {token}. Формулировки можно менять как
угодно: Veriqa находит токен по его форме, а не по словам вокруг. Оставьте {token} в тексте, если токена
нет в адресе. QR-код несёт письмо целиком, поэтому самый маленький код получается с TokenInLocalPart.
Если письмо собрать не удалось, причина пишется в журнал. Так бывает, когда на InboundAddress
письмо нельзя адресовать (адрес не задан вне Production либо в нём нет домена при включённом
TokenInLocalPart) или когда отказало хранилище токенов. Канал при этом сохраняет то, что осталось: при PullEnabled страница входа
показывает поле адреса без кнопки почтового клиента и без QR-кода; без него канал Email не
предлагается. Письмо, которое не помещается в QR-код (длинный текст заполненного письма), оставляет
канал с кнопкой и без QR-кода.
Email в hop-режиме
В hop-режиме QR-код канала Email несёт hop-ссылку вместо письма, и телефон по-прежнему попадает в само письмо. Как он туда попадает, решаетRedirectStyle, как у любого канала; вход по ссылке из письма (PullEnabled) меняет только страницу
при Interstitial:
Direct строку «письмо открыто в почтовом
приложении» окно входа получает от самого перенаправления.
Там, где вопрос задаёт окно входа, — по умолчанию у Email, см.
Страница ссылки из письма, — письмо привязывает ящик ко входу, а вопрос
ждёт в окне входа. Тогда обе страницы телефона говорят «Вернитесь к окну входа и подтвердите вход
там.»: страница с кнопкой письма убирает поле адреса и кнопку письма и оставляет обратный отсчёт;
страница запуска убирает инструкцию, кнопку и запасной код и продолжает показывать, чем закончился
вход. Следующие статусы письма эту строку больше не заменяют. Так же ведут себя страницы телефона
любого другого канала, когда LoginConfirmation.Mode этого канала равен OnWebPage. Если в это время
отсканировать код Email ещё раз, страница с кнопкой письма откроется, но в почтовое приложение сама не
перейдёт.
При OnWebPage чат тоже не молчит: как только отправитель привязан ко входу, канал, который отправляет
сообщения в чат, один раз отвечает «Вход начат — подтвердите его на странице входа» на языке получателя,
чтобы пользователь знал, что смотреть надо в окно входа. При подтверждении,
на которое отвечают на странице подтверждения, канал отправляет то же сообщение в формулировке подтверждения:
«Подтверждение начато — подтвердите его на странице подтверждения». Сообщение уходит один раз на
транзакцию — повторный старт по той же ссылке ничего больше не присылает. Email такого письма не
отправляет. Текст — вид сообщения web-confirmation-notice, формулируется как любое другое
сообщение, в том числе по каналам, — см.
Veriqa:MessageTemplates. Когда пользователь
отвечает на странице, в тот же чат новым сообщением приходит квитанция исхода — о подтверждении на «Да»,
об отказе на «Нет» — без значений вызывающей стороны: вопрос в чате не задавался. «Да» на вход, которое ведёт в добор claims, получает квитанцию, когда добор закончится. Квитанция, которую канал не принял, пишется в
лог и не повторяется; ответ приложению не меняется.
Страница входа на компьютере следует за телефоном: скан QR-кода Email показывает «QR-код
отсканирован. Продолжите на телефоне, чтобы подтвердить по почте.», а начало письма — по нажатию, по
автозапуску страницы запуска либо, где страницы нет, от самого перенаправления — «Письмо-подтверждение
открыто в почтовом приложении. Отправьте его, чтобы продолжить.»
Страница ссылки из письма
Ссылка письма входа (PullEnabled) открывает страницу Veriqa, и что она делает, зависит от того, где
подтверждается вход, — режим Veriqa:LoginConfirmation
у канала Email:
- Спрашивает окно входа — умолчание для Email. Страница ни о чём не спрашивает. Под заголовком
«Запрос входа» она называет приложение — «Запрошен вход в
{app}. Если это не вы — закройте страницу.» — и предлагает «Продолжить вход» и «Отмена». «Продолжить вход» передаёт вход окну входа: расходует ссылку и привязывает ящик ко входу, не завершая его, — и страница сменяется строкой «Вернитесь к окну входа и подтвердите вход там.» с кнопкой «Закрыть». Единственный вопрос входа — подтвердить или отклонить — задаётся один раз, в окне входа, где вход начат: «Да» входит в учётную запись, и данные профиля, которых приложению не хватает, добираются там же; «Нет» отклоняет вход, и приложение получаетaccess_denied. Повторно открытая та же ссылка сообщает, что недействительна или устарела. - Окно входа не спрашивает (
None). Ссылка завершает вход при открытии, и страница показывает, чем он закончился. Почтовый шлюз, проверивший ссылку, завершает вход того, кто его начал, поэтому этот режим включают только в исключительных случаях — в тестовых окружениях и приложениях с низким риском, см.Veriqa:LoginConfirmation.
HopMode.CollectFingerprint и
включённым HopMode.CollectIpAddress (по умолчанию), — страница вычисляет отпечаток браузера, в
котором открыта, и при совпадении обоих значений продолжает сама: пользователь видит «Вернитесь к окну
входа…» без нажатия. Любое несовпадение, браузер, не сумевший вычислить отпечаток, или вход без этих
значений оставляют на странице кнопку. Присланный страницей отпечаток сравнивается и отбрасывается: он
не сохраняется и в журнал не пишется.
«Отмена» и «Закрыть» только закрывают вкладку и ничего не меняют; если браузер оставляет вкладку,
открытую не скриптом, страница вместо этого пишет «Эту вкладку можно закрыть.». Когда спрашивает
окно входа, открытие страницы ссылку не расходует: почтовый шлюз, прошедший по ней, ничего дальше не
передаёт — передаёт только POST кнопки. При None вход завершает само открытие.
Ссылка подтверждения открывает ту же страницу с формулировками
подтверждения: под заголовком «Требуется подтверждение» она пишет «Запрошено подтверждение. Если это не
вы — закройте страницу.» и предлагает «Продолжить подтверждение» и «Отмена». В отличие от
страницы входа, приложение здесь не названо. Чтобы страница называла ваше приложение, задайте для него
свою формулировку этой строки в
AuthPage:Texts.
Браузеру, участвовавшему в подтверждении, кнопку тоже нажимать не нужно: страница проверяет его так
же, как при входе. «Продолжить подтверждение» ведёт на страницу, где показано, что именно
подтверждается; там пользователь и отвечает.
Повторная отправка письма
После отправки ссылки поле адреса на странице входа остаётся редактируемым, а кнопка становится «Отправить снова». Она удерживается наMailResendInterval — по умолчанию 30 секунд — и
возвращается сама; запрос, пришедший раньше, отклоняется с 429, письмо не уходит. Письмо с кодом
отправляется снова так же: «Отправить снова» под полем кода возвращает поле адреса, и его кнопка
удерживается на тот же интервал.
- Интервал считается на вход, а не на адрес: исправить адрес и нажать кнопку в пределах интервала — тот же отказ.
- Письмо входа и письма добора claims считаются раздельно: вход по ссылке из письма первое письмо добора не задерживает.
00:00:00выключает интервал; отрицательное значение останавливает старт. Настройка задаётся только в конфигурации хоста: тенант и запись клиента её не переопределяют.- Письма входа ограничены ещё и по адресу и по домену за час, по всем входам тенанта:
SignInMailsPerAddress(по умолчанию 5) иSignInMailsPerDomain(по умолчанию0, лимит выключен; включите его сами). Сверх любого из лимитов запрос отклоняется с429, письмо не уходит. Письма добора claims считаются отдельно. См. справочник конфигурации. - Интервал, лимиты по адресу и домену, лимит запросов и лимиты писем добора
(
ClaimCompletionEmailLimits) действуют независимо друг от друга. - Письмо, которое не удалось отправить, всё равно запускает интервал и засчитывается в лимиты по адресу и домену — следующая попытка ждёт.
POST /auth/email/start несёт retryAfterSeconds — сколько ждать до следующего письма — и при
успехе, и в отказе 429 по интервалу, который также ставит заголовок Retry-After. Отказ 429 по
лимиту адреса или домена не несёт ни того, ни другого: кнопка страницы остаётся доступной, и можно
ввести другой адрес. Собственная страница входа
может удерживать кнопку по этому числу. При успехе ответ несёт ещё и code_expected, см.
Ссылка, код или оба.
Письмо в один тап через IMAP
ПриInbound:Provider = ImapPolling Veriqa читает почтовый ящик сама: не нужны ни входящий
провайдер, ни секрет вебхука, ни публичный адрес вашего сервера — достаточно ящика и пароля к нему.
Фоновый сервис входит в ящик по IMAP, берёт непрочитанные письма и передаёт каждое в ту же
обработку, что и письмо, пришедшее вебхуком, — проверка отправителя и итог входа одинаковы.
Veriqa:Channels:Email:Inbound:Imap:
InboundAddress с этим провайдером обязателен в любом окружении, а не только в Production: это
адрес, на который пользователь отправляет письмо, то есть адрес этого ящика. При
UsePlusAddressing письмо уходит на login+{token}@… — проверьте, что ваш почтовый провайдер
доставляет письма с плюс-адресом в основной ящик.
Как это работает.
- Письмо срабатывает не позже чем через
PollIntervalSecondsплюс время одного обращения к ящику после того, как пришло: завершает вход либо, где спрашивает окно входа, привязывает к нему ящик. - Берутся только непрочитанные письма, пришедшие не раньше чем
TokenTtlназад: более старое письмо не читается и не помечается. Обработанное письмо — принятое или отклонённое — помечается прочитанным. Письма никогда не удаляются. - Соединение — только по TLS, сертификат сервера проверяется всегда; отключить проверку нельзя.
- Отказ ящика или сервера авторизации — сеть, неверный пароль, отказ в токене — не останавливает приложение и другие каналы. Ошибка пишется в лог без секретов, обращение повторяется через 1 секунду, затем через 2, 4 и так далее до 60 секунд; первое успешное обращение сбрасывает паузу.
- Маршрут вебхука
/api/channels/email/inboundс этим провайдером отвечает404. - В мультитенантной установке каждого тенанта с этим провайдером читает свой цикл со своими настройками ящика.
AuthservId. SPF, DKIM и DMARC проверяет почтовый сервер ящика и записывает
результаты в заголовок письма Authentication-Results
(RFC 8601). Отправитель может вписать в письмо поддельный
заголовок с тем же именем, поэтому Veriqa доверяет только заголовку, первое слово которого —
authserv-id — равно AuthservId, а из нескольких таких — верхнему. Если в письме нет заголовка
с таким идентификатором, результаты пусты, и политика письмо отклоняет. Политика AllowListOnly
заголовок не читает, ключ ей не нужен.
Чтобы узнать значение, откройте исходник любого письма, полученного этим ящиком («Показать
оригинал» или похожая команда почтового клиента), и посмотрите на верхний заголовок
Authentication-Results:
Authentication-Results: mx.your-provider.com; spf=pass …; dkim=pass …; dmarc=pass …— значение начинается с имени хоста, за которым стоит;. Это имя и естьAuthservId.Authentication-Results: spf=pass …; dkim=pass …; dmarc=pass …— значение начинается с результата (слова с=), то есть серверauthserv-idне указывает. Записать вAuthservIdнечего:spf=passтуда не копируйте.
AuthservId одно. Ящик, у которого идентификатор
отсутствует или различается от письма к письму, для этого режима непригоден — подключите его через
вебхук или возьмите ящик другого провайдера.
Ограничения:
VerificationPolicy: ProviderVerifiedсImapPollingнесовместима — у ящика нет отправителя, проверенного провайдером; с такой парой хост не стартует.- Расхождение
ImapPollingи значенияInboundVerification, отличного отoutbound_fetch, даётWarningпри старте — как у мессенджера в режимеPolling.
Вход в ящик по OAuth
Некоторые ящики пароль не принимают вовсе — Microsoft 365 и организации Google Workspace, отключившие парольный вход. OAuth меняет только способ входа Veriqa в ящик: отправителя письма по-прежнему проверяетVerificationPolicy, поэтому сначала убедитесь, что ящик проходит проверку
AuthservId, описанную выше. Для таких ящиков задайте AuthMode = OAuth2 и заполните секцию
Veriqa:Channels:Email:Inbound:Imap:OAuth. В ней лежит не токен доступа — он живёт около часа, —
а долгоживущие данные для его получения: Veriqa сама запрашивает токен у TokenEndpoint, держит
его в памяти и запрашивает новый, когда срок вышел.
Password в этом режиме игнорируется, а секция OAuth игнорируется при AuthMode: Password.
Вход в ящик выполняется под Username механизмом OAUTHBEARER, если сервер его предлагает, иначе
XOAUTH2.
Какой из двух стандартных способов получения токена (RFC 6749)
применяется, определяет RefreshToken:
- По refresh token — ящик конкретного пользователя, который один раз выдал согласие. Выбирайте, когда ящик — обычная учётная запись и провайдер выдаёт для неё refresh token.
- По учётным данным приложения (
client_credentials) — приложение читает ящик без пользователя. Выбирайте, когда администратор организации может выдать приложению доступ к ящику; refresh token при этом нет, и обновлять нечего.
- Microsoft 365 — Authenticate an IMAP, POP or SMTP connection using OAuth: регистрация приложения, права для каждого из двух способов и — для учётных данных приложения — шаги администратора, открывающие приложению ящик. Адрес выдачи токенов описан в OAuth 2.0 client credentials flow и OAuth 2.0 authorization code flow.
- Google — OAuth 2.0 mechanism называет права доступа по IMAP, а Using OAuth 2.0 to Access Google APIs описывает регистрацию приложения, адрес выдачи токенов и получение refresh token. Здесь применим только способ по refresh token: см. ограничения ниже.
- Согласие выдаётся вне Veriqa. Экрана согласия и адреса возврата у Veriqa для этого нет: администратор получает refresh token по инструкции почтового провайдера и кладёт его в секреты.
- Обновлённый refresh token не записывается обратно. Сервер авторизации может вернуть новый refresh token вместе с токеном доступа; Veriqa пользуется им до остановки процесса и в конфигурацию не записывает. У провайдера, где refresh token имеет срок жизни, администратор заменяет значение в секретах сам.
- Сервисный аккаунт Google не поддерживается — вход подписанным JWT (RFC 7523) не реализован.
Провайдеры
Поставляемые провайдеры —Smtp для исходящих, Webhook и ImapPolling для входящих.
Обе настройки также принимают Custom, в этом случае вы регистрируете свой IEmailOutboundSender /
IEmailInboundProcessor в DI до вызова AddEmail(). Любое другое значение сразу
останавливает старт с ошибкой, а не молча бездействует.
Свой IEmailOutboundSender отправляет только письмо входа, если он не отвечает
SupportsClaimCompletionEmail значением true и не реализует SendClaimCompletionEmailAsync: эти два
члена отправляют письма с кодом и со ссылкой, подтверждающие адрес почты при доборе claims. Без них
способ «Код на почту» («Ссылка на почту», если в списке только MagicLink) — тот, что стоит за Code
и MagicLink, — недоступен, и веб-шаг
предлагает только оставшиеся.
Своё тело письма
Письмо входа — обычное сообщение механизма текстов: и тема, и HTML-документ тела целиком задаются значением ключаVeriqa:MessageTemplates:sign-in-mail (устройство ключа — в
Справочнике конфигурации). Поэтому переписать
письмо можно настройкой, не трогая код: задайте свою лестницу вариантов на нужном уровне.
Письмо подтверждения — то же сообщение, его формулировка задаётся на
Veriqa:MessageTemplates:sign-in-mail:ByType:confirmation со своим контрактом: поставляемый текст
начинается со слов «Требуется подтверждение» и, как письмо входа, называет приложение. Лестница, заданная на самом
sign-in-mail в Veriqa:MessageTemplates, меняет только письмо входа, а в записи приложения — оба
письма этого приложения. Своё письмо подтверждения задайте лестницей на ByType:confirmation на
том же уровне.
Письмо с кодом — отдельный вид сообщения, и задаётся он так же: sign-in-code-mail — письмо с одним
кодом, sign-in-code-link-mail — с кодом и ссылкой (см. Ссылка, код или оба). У
каждого своя формулировка подтверждения на ByType:confirmation, и ни в одном нет QR-кода. Слот
{code} гарантирован в обоих, {link} — только в sign-in-code-link-mail. Лестница, заданная для
sign-in-mail, эти письма не меняет.
- разметку в тексте варианта продукт не экранирует — её пишет владелец конфигурации. Экранируются значения слотов: они приходят снаружи, в том числе от приложения по API;
- видимые фразы остаются ключами локализации.
{button},{qr_instruction},{qr_alt}и прочие подобные — слоты локализованной строки: контракт сообщения указывает, на какой ключ смотрит слот, а подставится перевод на язык получателя. Разметка при этом одна на все языки, и переводить её копиями не нужно. В поставляемом письме вне таких слотов нет ни одной фразы —{heading},{text_intro},{request_from_label},{button_hint},{valid_until_label}и остальные; пример из двух вариантов выше пишет заголовок и строку «Request from» прямо в разметку, и они остаются на том языке, на котором вы их написали; - то, что Veriqa вычисляет сама, не укорачивается; то, что приходит извне, — укорачивается.
{link},{valid_until}и прочие значения, которые продукт вычисляет сам, подставляются полностью. Имя приложения, детали инициатора и переведённая фраза ограничены 128 символами — держите фразу одного слота короткой, а длинное предложение раскладывайте на несколько слотов; - форму QR-кода решает текст, а не настройка. Вариант, сославшийся на
{qr_cid}, получает PNG-вложение; вариант, сославшийся на{qr_url}(ссылку на QR-эндпоинт, если её кладёт ваш композер), получает картинку по ссылке и вложения не несёт; вариант, не назвавший ни одного из них, — письмо без QR-кода. Лишнего вложения, на которое никто не ссылается, не бывает; - письмо одно, а редакций у ступени две. Ступень лестницы — либо строка (текст, годный любому
приёмнику), либо объект
{ "Subject": …, "Html": …, "Plain": … }. Каждая редакция необязательна, но хотя бы одну ступень обязана заявить: ступень без единой редакции останавливает старт с указанием рода сообщения и номера ступени. Ступень, заявившая толькоHtml, для текстовой части не годится — подбор просто идёт ниже по лестнице, так что две части одного письма могут прийти с разных ступеней. Тема при этом берётся у ступени, выбранной дляHtml; - последняя ступень лестницы обязана опираться только на гарантированные слоты (
app,valid_until,link,lang; вsign-in-code-mailместоlinkзанимаетcode, аsign-in-code-link-mailгарантирует оба). Детали инициатора и QR-код гарантированными не являются: транзакция без них штатно доходит до ступени, которая их не называет, — и в письме не появляется ни пустого абзаца, ни литерала{browser}. Считается это по каждой редакции отдельно: подбор идёт среди ступеней, заявивших нужную редакцию, поэтому у лестницы две «последних» ступени — последняя сHtmlи последняя сPlain, — и требование распространяется на обе. Лестница, где последняя ступень сHtmlназывает{browser}, а бесслотовой сделана толькоPlain, останавливает старт; - письмо только в html (или только текстом) — законное объявление. Если
Plainне заявляет ни одна ступень, письмо уходит без текстовой части: ошибки в логе нет, подмены редакций нет. Ровно поэтому проверьте, что односоставное письмо — ваш выбор, а не забытая редакция: в данных эти два случая неотличимы.
IEmailMessageComposer. Он получает данные отправки и возвращает готовое тело письма
(EmailBodyContent: тема, html-часть, текстовая часть и признак QR-вложения), а провайдер доставки
занимается только транспортом.
AddVeriqa*, уже стоит в контейнере и поставляемая не добавляется; после — RemoveAll + Add.
Разметку письма задаёт текст варианта в конфигурации выше (её пример — в начале этого раздела); для
полного контроля — IEmailMessageComposer. Своя реализация композера берёт на себя всё тело
письма целиком: лестницу деградации, локализацию видимых фраз через Natural Key и
решение о QR-вложении она реализует сама.
Нормализация адреса
СекцияNormalization определяет, какую форму адреса Veriqa считает идентификатором пользователя:
user@почта.рф и user@xn--80a1acny.xn--p1ai — один пользователь, а claim email содержит вторую
форму.
ProviderSpecificCanonicalization включает провайдер-специфичную канонизацию. Поддержано одно
семейство — Gmail (gmail.com и googlemail.com): точки в локальной части отбрасываются, +-тег
отсекается, googlemail.com приводится к gmail.com. Так u.ser+shop@googlemail.com и
user@gmail.com становятся одним пользователем. Домены вне этого списка не канонизируются никогда —
у многих провайдеров + входит в адрес, и общее правило склеило бы разных людей.
Вход через аккаунт провайдера
Пользователь входит через свой аккаунт Google, Apple, Huawei, Яндекс, VK ID или другого провайдера изOpenIddict.Client.WebIntegration: сканирует QR-код телефоном, входит у провайдера на телефоне и
подтверждает вход там же. Как это выглядит для пользователя и когда помогает, рассказано на странице
Вход через аккаунт провайдера.

Что видит пользователь: QR-код, камера телефона, аккаунт Google, сдвиг шторки на странице подтверждения. Интерфейс на английском.
Veriqa:Channels:{канал} с подсекцией WebProvider, а имя секции становится типом канала:
Veriqa__Channels__google__WebProvider__ClientSecret. Имя канала — строчные латинские буквы, цифры и
-; имя канала из поставки (telegram, email и другие) занять нельзя. Два клиента одного провайдера
— это два канала с разными именами.
{PublicBaseUrl}/auth/web-provider/{канал}/callback.
Ошибка в секции включённого канала останавливает старт хоста, и сообщение называет ключ.
Регистрации читаются при старте: чтобы добавить или изменить канал, перезапустите хост.
Задаёт ли страница на телефоне вопрос «Да/Нет», решает
Veriqa:LoginConfirmation:Mode и ModeByChannel,
как у любого канала. При OnWebPage вопрос задаёт окно входа, а телефон показывает сообщение о
том, что подтвердить нужно там. Когда вход завершится, вместо сообщения появится итог.
Состояние страниц на телефоне по умолчанию хранится в процессе. Если реплик несколько, подключите
канальные хранилища в Redis.
Строки статуса на компьютере
Задайтеchannel-launched-line и channel-answer-line для каждого канала провайдера по адресу
BySurface:core-page:ByChannel:{канал}. Формулировке подтверждения в channel-answer-line нужен
свой адрес — под ByType:confirmation. Для канала google из примера выше:
{channel_name} — имя канала на его вкладке. Каждый текст — ещё и ключ locale-файлов: добавьте
русский перевод в ru.json, как описано в разделе «Тексты каналов и писем — те же locale-файлы»
страницы Настройка и кастомизация. Без перевода русская страница покажет
английский текст. Как ищутся эти строки, описано в разделе
Строки канала на страницах Veriqa.
Стартовые провайдеры
Для этих пяти провайдеров известно, какие данные пользователя приходят и что для этого настроить. Подробная таблица со ссылками на документацию провайдеров — в README пакетаVeriqa.Core.ChannelAdapter.WebProviders.
PhoneNumber. Имени пользователя Apple канал
не получает, а адрес почты может быть адресом пересылки Apple.
Каналу Apple задайте DisplayName, например Apple. В OpenIddict этот провайдер называется
«Sign in with Apple», и без ключа кнопка на странице входа читается «Войти через Sign in with Apple».
У остальных четырёх имя по умолчанию — название бренда, менять его не нужно.
Подтверждённый email от провайдера
Яндекс ID и VK ID отдают email, но не сообщают, подтверждён ли он.email_verified остаётся
неизвестным, и RP или политика ограничений, которой нужен подтверждённый email, считает такой вход
неподтверждённым. Блок Email в канале это меняет:
- При
Proof: Provenemail от провайдера получаетemail_verified: true. Если провайдер сам сообщил рядом с emailemail_verified: false, claim остаётсяfalse. Proof: NotProven— значение по умолчанию, оно равносильно отсутствию блока: решает толькоemail_verifiedсамого провайдера.- Если в ответе провайдера нет email, нет и
email_verified.
Proof останавливает старт хоста, и сообщение называет ключ.
Адрес Apple может быть адресом пересылки (private relay). Apple его подтвердил, но он только
пересылает письма на настоящий адрес и идентификатором пользователя не является:
идентифицируйте пользователя по sub.
Номер телефона и другие claims от провайдера
Идентификатор, имя, email, аватар и локаль аккаунта канал берёт сам. Номер телефона и другие данные профиля приходят, только если их сопоставить в секцииWebProvider: готового сопоставления ни для
одного провайдера в пакете нет.
Блок PhoneNumber говорит, где в ответе провайдера номер:
Claims — список записей: Source — путь к значению в ответе, в том же виде, что Claim выше;
Claim — claim, который выдаёт Veriqa; Scopes запрашиваются у провайдера ради этого claim. Имя
claim — один из стандартных claims профиля birthdate, gender, middle_name, nickname,
profile, website или имя, которое начинается с имени канала и _ (yandex_login у канала
yandex), и написано оно должно быть ровно так. Любое другое имя, как и имя, указанное дважды,
останавливает старт хоста.
Объявите claim строкой каталога Veriqa:ScopesClaims
под тем scope, который должен его открывать: для birthdate — под profile. Тогда scopes записи
запрашиваются у провайдера при каждом входе, где приложение получает этот scope, а claim попадает в
оба токена. Без строки каталога они не запрашиваются, а claim, который провайдер всё же вернул, идёт
только в access token, как любой claim вне каталога. Исключение — nickname: он входит в
стандартный набор scope profile и строки каталога не требует, поэтому scopes записи с nickname
запрашиваются при каждом входе, где приложение получает profile.
Пример для Яндекс ID. Номер телефона Яндекс возвращает в поле number объекта default_phone, а дату
рождения — в birthday в виде ГГГГ-ММ-ДД
(Яндекс ID: информация о пользователе). Права
доступа из примера, login:default_phone и login:birthday, должны быть среди прав вашего
приложения; их список — на странице приложения https://oauth.yandex.ru/client/<client_id>/info.
Запрос, в котором названы scopes, получает только названные права, а не выбранные при регистрации
(Яндекс ID: получение кода), поэтому основные права
перечислены в Scopes:
Proof: Proven, вы доверяете номерам Яндекса как
подтверждённым; если не доверяете, оставьте NotProven. Непустой ScopesClaims:Scopes заменяет
собственный набор scopes продукта: перечислите все scopes, которые запрашивают ваши клиенты, как
описано в справочнике.
Другие провайдеры для входа людей
Канал можно построить и на другом провайдереOpenIddict.Client.WebIntegration. Ниже — те, чьё
главное назначение — аккаунт человека, личный или рабочий. Провайдеры, которые дают доступ к данным
сервиса, а не аккаунт человека (Strava, Spotify, Calendly и подобные), в перечень не входят. Данные
пользователя приходят такими, какими их сводит OpenIddict; что именно отдаёт провайдер и какие scopes
для этого нужны, смотрите в его документации.
Как дать клиенту выбрать канал
Клиент может ограничить конкретный вход определёнными каналами через стандартный OIDC-параметрacr_values, в форме channel:{type}:
channel:telegram channel:whatsapp), чтобы сузить выбор, не фиксируя его. Без
параметра предлагается каждый включённый канал.
Чек-лист
Адаптер зарегистрирован и включён
AddXxx() вызван и у секции стоит "Enabled": true.Уровень проверки объявлен осознанно
InboundVerification, и значение соответствует режиму, в
котором канал реально работает.Вебхук доступен
https://…/api/channels/… публично доступен по HTTPS и не заблокирован вашим прокси.Секреты в хранилище секретов
Вход подтверждён от начала до конца