Перейти к основному содержанию
Veriqa поставляет каналы из списка Поддерживаемые мессенджеры, но канальный слой — открытая точка расширения. Если ваши пользователи общаются в мессенджере, которого нет в списке, вы пишете адаптер против MIT-пакета контрактов и регистрируете его в своём хосте. Без форка ядра, без патчей и без ожидания пул-реквеста. Адаптер — это один класс и один вызов регистрации:
Program.cs
По этому вызову Veriqa регистрирует адаптер, открывает маршрут его вебхука с теми же защитами, что у встроенных каналов, и показывает канал в окне входа. Полный рабочий пример — в samples/dotnet/custom-channel: библиотека адаптера и хост, который её подключает. Не пишете на .NET или работаете со стандартным образом Veriqa, который не пересобираете? Напишите адаптер отдельным сервисом на любом языке и подключите его конфигурацией — см. Свой канал на любом языке. Внешний адаптер на .NET — samples/dotnet/custom-channel-id-providers: вход через аккаунты Google, Apple и HUAWEI ID.

1. Проект адаптера

Подключите пакет контрактов:
Acme.Chat.Adapter.csproj
Veriqa.Core.Contracts — пакет под лицензией MIT: это и есть бесплатный SPI. Адаптеру, который только реализует IChannelAdapter, другие пакеты Veriqa не нужны; так устроен samples/dotnet/custom-channel/adapter. Разделам о шаблонах из ядра, об опросе и о работе по тенантам нужен ещё пакет ядра Veriqa.Core.ChannelAdapter (MPL-2.0) в проекте адаптера. Состав каждого пакета описан в его README (он же виден на странице пакета в NuGet). Строка NoWarn нужна потому, что [Experimental("VERIQAEXP0001")] помечены два типа: ChannelInboundResult, тип результата ProcessInboundEventAsync, и ConfirmationPromptContext, тип параметра SendConfirmationPromptAsync. Такие типы могут измениться в минорной версии, и компилятор считает их использование ошибкой, пока ваш проект с этим не согласится. Пометку объясняет README пакета контрактов.

2. Реализация IChannelAdapter

Поток держат три метода; остальные — исходящие операции, которых у вашей платформы может и не быть.

ValidateWebhookAsync — проверка безопасности

Вызывается раньше вашей обработки, но не раньше всего. Сначала запрос проходит демультиплексор тенантов: на неизвестный сегмент тенанта он отвечает 403, вообще не обращаясь к адаптеру. Только после этого Veriqa читает тело и собирает конверт. Вернули false — запрос получает 403 и до вашей обработки не доходит; исключение отсюда трактуется так же, как отказ (уходит в лог, ответ — 403), поэтому сломанный разбор подписи никогда не превратится в 500. Проверяйте подпись платформы здесь, за постоянное время, и отказывайте по умолчанию:

Объявите уровень проверки своего канала — и задокументируйте его

То, что ваш ValidateWebhookAsync вернул успех, ядру говорит только «проверка выполнилась и прошла». Чем она была, ядро не знает и вывести не может: закрытого перечня каналов у него нет, а самозаявление адаптера ничего не гарантировало бы — заявляет тот, кто несёт риск, то есть интегратор. Поэтому секция вашего канала несёт тот же обязательный ключ InboundVerification, что и секции поставляемых каналов:
appsettings.json
Словарь значений — signature (подпись тела ключом платформы), shared_secret (секрет, предъявляемый входящим запросом), outbound_fetch (входящих запросов нет, события забирает исходящий запрос) и none (подлинность не проверяется); полное описание — в справочнике конфигурации.
Для канала, подключённого показанным здесь способом, ключ обязателен, но на старте не проверяется. Проверка, которая останавливает хост, если у включённого канала нет значения, перебирает каналы, объявившие себя на уровне ядра, — тот же набор, из которого ядро строит список включённых каналов. Вызов AddChannel регистрирует адаптер и его маршрут, но объявления на уровне ядра не создаёт, поэтому в этот набор такой канал не входит, пока вы не объявите его сами, как в разделе «Работа по тенантам». После этого проверка распространяется и на ваш канал наравне с каналами поставки. Значение при этом читается тем же резолвером и так же доезжает до записи журнала аудита, поэтому пропуск проявится пустым атрибутом в журнале, а не отказом при запуске.
Обязанность автора адаптера — задокументировать, какое значение даёт его канал в каждом режиме, который он поддерживает. Интегратор выбирает значение по вашей документации: сам он вашу проверку не читает, а ядро её не выводит. Пример выше даёт shared_secret, потому что показанная выше проверка сравнивает заголовок с настроенным секретом; канал, забирающий события своим исходящим запросом, объявляет outbound_fetch.

ProcessInboundEventAsync — на входе сырое тело, на выходе намерение

Оба метода получают один и тот же конверт ChannelInboundRequest: HTTP-метод, сырые байты тела, заголовки и параметры строки запроса (имена сравниваются без учёта регистра, повторяющиеся значения склеены через ", "). Байты — именно байты: подпись считается ровно по ним, и между платформой и вашим HMAC не встаёт шаг декодирования. Формат тела Veriqa не интерпретирует — JSON, form-encoded, XML, что угодно; разбор своими опциями сериализации — ваша обязанность.
Намерение — это тип результата, и у каждого свой обязательный набор полей: ChannelAuthStartResult (пользователь пришёл на платформу по deep link), ChannelAuthStartByCodeResult (прислал код, показанный на странице входа, — см. Старт по коду), ChannelAuthConfirmResult / ChannelAuthDeclineResult (нажал кнопку в вашем канале), ChannelPhoneSharedResult / ChannelPhoneStepActionResult (ответы на запрос номера телефона), ChannelUnaddressedResult или ChannelUnrelatedResult. Последние два похожи, и их легко перепутать. ChannelUnaddressedResult — это личное сообщение вашему боту от отправителя, которого вы уже проверили (голая стартовая команда, произвольный текст), не называющее транзакции; оно несёт отправителя, поэтому Veriqa может ответить на него, если регистрация объявила ответ (UnaddressedReplyText ниже). ChannelUnrelatedResult — всё, на что Veriqa отвечать не вправе: групповой чат, callback чужой кнопки, событие, не прошедшее вашу собственную проверку отправителя. Отправителя оно не несёт, и ответа не будет. Рядом есть синхронный bool OwnsInboundEvent(ChannelInboundRequest request) — дешёвый ответ «это событие Veriqa?» до разбора. Он нужен, если транспортом канала владеете вы и раздаёте события между своим ботом и Veriqa: разбирать событие дважды не придётся (этот и другие способы делить бота — У меня уже есть бот). Тело по умолчанию уже есть — поиск любого маркера CallbackDataPrefixes (vq_confirm_, vq_decline_, vq_phone_skip_, vq_phone_cancel_, vq_menu_, auth_) в сырых байтах тела, — поэтому реализовывать член не обязательно. vq_menu_ помечает кнопку меню пост-действия: за ним идёт значение из конфигурации развёртывания, а не идентификатор транзакции. Ответ односторонний: событие от кнопки или deep link Veriqa всегда даёт true, но true ещё не значит, что событие можно обработать. Поиск подстрочный, а у auth_ нет вендорного префикса, поэтому слово oauth_ в сообщении пользователя тоже даст true. Если ложное срабатывание вам чем-то стоит — переопределите член точной проверкой своего wire-формата.

Capabilities — что ваш канал умеет

Возможности канала объявляются фактом, а не заглушкой операции: один объект ChannelCapabilities говорит, умеет ли канал подтверждать вход у себя внутри (SupportsInChannelConfirmation), какие виды контента он принимает, умеет ли обновлять своё сообщение (SupportsMessageUpdate), показывает ли пользователю, где находится транзакция (DeliversOutcomeNotice), отдаёт ли локаль получателя (ProvidesRecipientLocale) и рендерит ли эмодзи (RendersEmoji). Veriqa не вызывает того, что канал не объявил, — поэтому «не умею» пишется один раз и в одном месте. О подтверждении вы сообщаете ровно один факт — собственную способность задать вопрос и получить ответ внутри канала. Как именно вы это делаете (inline-кнопки, веб внутри мессенджера, что угодно) — ваше дело, ядро способ не знает и не спрашивает. Поверхности ядра адаптер не называет: нужно ли подтверждение вообще — политика ядра, а страницу с вопросом, когда канал подтверждать у себя не умеет, показывает само ядро. По умолчанию факт — «не умею»: собранный адаптер, который об этом факте ничего не знает, не получит подтверждение, которое не сумеет показать.
RendersEmoji решает, какую из двух формулировок для канала получит терминальная квитанция, и это правило канала, а не точки показа. true даёт формулировку с эмодзи, false и незаданное значение — формулировку без них. Списка каналов на этот случай у ядра нет: адаптеры мессенджеров из поставки так же заявляют true.

Исходящие операции

SendMessageAsync(ChannelMessage) отправляет сообщение и возвращает ссылку на отправленное (ChannelMessageRef) — или null в успехе, если адресуемой ссылки у канала нет. SendConfirmationPromptAsync отправляет вопрос подтверждения и возвращает такую же ссылку; хранит её Veriqa, а не вы. ReportOutcomeAsync(TransactionOutcomeNotice) — намерение «покажи пользователю, где находится транзакция»; какими вызовами платформы это сделать, решаете вы, и вызывается он только если канал объявил DeliversOutcomeNotice. Уведомление везёт ещё и DisplayIntent — где развёртывание хочет видеть квитанцию: на месте сообщения с вопросом (ReplacePrompt, поставочное значение) либо отдельным сообщением (NewMessage). Исполнять его вы не обязаны: заменять на вашей платформе может быть нечего, и показ исхода единственным доступным ей способом ошибкой не считается — в журнал ошибка не пишется, возвращаемый вами результат не меняется. Уведомление терминально во всех случаях, кроме одного. Outcome — confirmed, declined, expired или failed, когда транзакция завершена, и awaiting_claims, когда вход подтверждён и ждёт данных, которые ещё запрашивает ваше приложение; различает их IsTerminal. Показывайте это состояние так же, как квитанцию, — ответьте на нажатие, поставьте StatusText на место вопроса. Вход, который затем закончился подтверждением, отказом или ошибкой, сообщается снова и всегда новым сообщением. Состояние сообщается на нажатие, которым вход подтверждён. Нажатие, сделанное позже, пока вход ещё ждёт, приносит то же уведомление только каналу, объявившему SupportsMessageUpdate. Канал, который не умеет править свои сообщения, на него не вызывается: состояние пришло бы новым сообщением под запросом идущего шага и могло бы снять его кнопки. Вместо этого, пока вход ждёт номер телефона, такому каналу заново отправляется запрос номера: на многих платформах само нажатие встаёт в переписку сообщением пользователя и снимает кнопки запроса, а повторный запрос их возвращает. Если ваша платформа ждёт ответа на каждое нажатие кнопки, дайте этот ответ сами, когда получаете событие. Истечение сообщается по каждой транзакции, начатой из вашего канала, — задавался вопрос в чате или нет. PromptMessage заполнен, только если вопрос ушёл в чат, канал объявил SupportsMessageUpdate и вернул ссылку из отправки вопроса. Без неё — вопрос задан на веб-странице, вход обошёлся без вопроса либо хранить было нечего — покажите StatusText новым сообщением. Не сообщается только истечение, запись о котором Veriqa уже не хранит: по умолчанию она лежит в памяти инстанса, обработавшего старт (канальные хранилища). Исполнение NewMessage — это два шага, а не один, и забывают обычно второй: доставить квитанцию новым сообщением и снять кнопки у сообщения с вопросом, не трогая его формулировку. Пропустите второй — и пользователь смотрит на завершённую транзакцию с живой кнопкой под ней: вопрос, который ничего не решает, но по-прежнему приглашает нажать. Снимайте кнопки той операцией, которая меняет разметку сообщения, не переписывая его текст; если такой операции у платформы нет, оставьте вопрос нетронутым, а не обнуляйте его текст — неисполненное намерение ошибкой не считается, а вопрос, потерявший формулировку, считается. На возвращаемый вами результат снятие кнопок не влияет: его решает доставка квитанции.

Текст вопроса и ссылки — шаблон берите у ядра

Интегратор задаёт формулировки в Veriqa:MessageTemplates для установки, тенанта или приложения. Ваш адаптер получает их у ядра через IChannelMessageTemplates. Адаптеру нужны два шаблона: вопрос подтверждения (MessageKinds.ConfirmationPrompt) и текст, которым deep link заранее заполняет сообщение пользователя (MessageKinds.DeeplinkPrefill). Второй понадобится, только если ваша платформа умеет передавать текст в ссылке. Если адаптер не запрашивает шаблон у ядра, пользователь видит ваш текст по умолчанию, даже когда интегратор задал свой. Ядро регистрирует два сервиса: IChannelMessageTemplates и IConfirmationPromptLocalizer, который переводит тексты на язык получателя. При регистрации AddChannel<TAdapter>("acme-chat") контейнер внедряет их в конструктор адаптера сам. При регистрации через фабрику передайте их в конструктор вместе с остальными параметрами:
Program.cs
В ResolveAsync адаптер передаёт себя (this), вид сообщения и идентификатор транзакции, а для текста ссылки — запрос, который получил GetDeepLinkAsync. Остальное ядро берёт само: канал — из ChannelType переданного адаптера, поверхность — in-channel, а уровень настройки (установка, тенант или приложение), язык, часовой пояс и имя приложения — из транзакции. Сообщение собирает сам адаптер: рендерит шаблон, добавляет кнопки и разметку, соблюдает лимиты платформы.
AcmeChatChannelAdapter.cs
  • Вопрос. ConfirmationPromptRenderer рендерит его на языке получателя из promptContext.
  • Текст ссылки. Для его шаблона передайте в ResolveAsync запрос, который получил GetDeepLinkAsync: ResolveAsync(this, MessageKinds.DeeplinkPrefill, request, cancellationToken). Тогда ядро учитывает и назначение ссылки: отдаёт формулировку, которую интегратор задал для этого назначения, а если её нет — формулировку канала. Рендерите текст в MessageTextRenderer.Render в режиме MessageRenderMode.PlainText и передайте Locale и TimeZone из результата ResolveAsync. В слот SlotNames.App положите ApplicationName, если оно есть. В результате есть и BrandName — имя бренда страницы входа. Встроенные каналы Veriqa кладут его в слот {brand_name} в переводе на язык получателя; ваш адаптер может положить его в SlotNames.BrandName только как есть, без перевода. В слот SlotNames.Code положите то, по чему ProcessInboundEventAsync узнает транзакцию. Поставляемый шаблон для своего канала — Send this message to sign in., для подтверждения — Send this message to continue., слота {code} в нём нет. Поэтому держите идентификатор транзакции в самой ссылке, а интегратор может объявить для вашего канала шаблон с {code} (deeplink-prefill:BySurface:in-channel:ByChannel:acme-chat, для одного назначения — …:ByLinkPurpose:hop-qr), а для подтверждения — тот же адрес под ByType:confirmation. Если ни одна ступень шаблона не объявляет редакцию Plain, Render возвращает null.
  • Сбой. Шаблона может не оказаться: вид сообщения не настроен или хранилище транзакций не ответило. Тогда ResolveAsync возвращает ошибку с кодом message_send_failed, а ядро уже записало её в лог на уровне Error и учло в счётчике veriqa.channel.template.failures (метрики). Верните её из SendConfirmationPromptAsync и не отправляйте вопрос. Что делать со ссылкой, решаете вы. Встроенный WhatsApp, например, оставляет в тексте только код входа.

Телефон по запросу

Канал, который умеет дать номер телефона пользователя, объявляет это в Capabilities.PhoneNumber: как он получает номер и доказывает ли платформа, что номер принадлежит отправителю. Что ядро делает с номером дальше — когда спрашивает, сколько ждёт, что попадает в токен, — описано на странице Номер телефона.
Не указанный PhoneNumber — это PhoneNumberCapability.None: канал номера не даёт, и вход, которому номер обязателен, этот канал не предлагает. При Automatic кладите номер в E.164 в поле снапшота PhoneNumber, а доказана ли принадлежность — в PhoneNumberVerified (оставили null — claim выйдет как false). При OnRequest ядро вызывает SendMessageAsync с сообщением вида PhoneNumberRequest: Text — текст запроса, а PhoneNumberRequest везёт метку кнопки «поделиться номером» (ShareButtonLabel), второе действие (SecondaryAction — Skip или CancelSignIn) с его меткой (SecondaryButtonLabel) и TransactionId. Тексты приходят уже локализованными. Покажите кнопку платформы «поделиться контактом» и рядом вторую кнопку: кнопка с payload несёт CallbackDataPrefixes.PhoneSkip или CallbackDataPrefixes.PhoneCancel и следом идентификатор транзакции, а кнопка клавиатуры, которая умеет только отправлять текст, отправляет свою метку. Ответы возвращайте так:
  • присланный контакт — ChannelPhoneSharedResult с номером в E.164 с ведущим + и снапшотом отправителя. Привести номер к E.164 — задача адаптера: платформы редко обещают этот формат, а номер вне формата ядро считает отсутствующим. Приводит номер E164PhoneNumber.TryNormalize из Veriqa.Core.Contracts. Если контакт не прошёл проверку принадлежности вашей платформы, поставьте OwnershipRejected = true: ядро номер не возьмёт и спросит снова. Транзакции контакт не называет — запрос ядро находит по чату;
  • вторая кнопка с payload — ChannelPhoneStepActionResult с разобранными TransactionId и Action; идентификатор, который не разбирается, делает событие ChannelUnrelatedResult;
  • вторая кнопка текстом — ChannelUnaddressedResult с Text: ядро сверит его с меткой, которую отправило в этот чат.
Когда вход завершается — исходом или истечением срока, — терминальное уведомление ReportOutcomeAsync везёт PhoneRequestMessage — ссылку, которую ваш SendMessageAsync вернул для запроса. Снимите то, что предлагал запрос, — его кнопки или клавиатуру ввода — средствами своей платформы. Ссылки нет, если вы её не вернули, а уведомление awaiting_claims её не несёт никогда: шаг ещё идёт. Если вы раздаёте события через OwnsInboundEvent, переопределите его: тело по умолчанию узнаёт маркеры кнопок, а у присланного контакта маркера нет. Отвечайте true на событие с контактом и сохраните проверку маркеров вызовом CallbackDataPrefixes.ContainsAnyMarker(request.Body.Span) — тело члена интерфейса по умолчанию из своего класса не вызвать. У кнопки, которая отправляет обычный текст, маркера нет вовсе, поэтому в этом режиме её нажатие уходит вашему боту: Optional номер тогда пропускается по истечении окна, а Required ждёт до истечения транзакции. У встроенного адаптера Telegram то же ограничение.

Имена claims — какие ваши, а какие ядра

Всё, что вы знаете о пользователе, кладите в типизированные поля снапшота: имя, username, локаль, телефон и признак доказанной принадлежности (PhoneNumberVerified), email и признак его подтверждённости (EmailVerified) — у каждого своё поле. Ядро само выпустит из них claims; email_verified выходит только рядом с непустым email, phone_number_verified — только рядом с непустым номером. Свободные имена — это AdditionalClaims, и там действуют группы имён реестра VeriqaClaimTypes: Стандартный claim профиля попадает в токены так же, как любой claim адаптера: если его объявляет строка каталога Veriqa:ScopesClaims под каким-то scope, он идёт в оба токена, когда этот scope выдан; без строки каталога — только в access token. nickname входит в стандартный набор scope profile, строка каталога ему не нужна. Ключ, нарушивший правило, отбрасывается с предупреждением в логе — аутентификация при этом не прерывается. Так что «занять» email или locale своей строкой не выйдет: положите значение в поле снапшота. Имена сравниваются без учёта регистра — Email_Verified это то же имя, что email_verified, и смена регистра резервирование не обходит. Префикс своего типа канала делает коллизии между адаптерами невозможными. Регистр решает, чьё имя, но не даёт свободы написания: свой claim принимается только в объявленном написании. При ChannelType = "acme-chat" ключ ACME-CHAT_workspace отбрасывается — пишите префикс так же, как записан тип канала (veriqa_channel — тоже как в реестре). Часть после префикса ваша: acme-chat_Workspace пройдёт. А вот два своих ключа, различающиеся только регистром, — это один claim: один из них будет принят, второй отброшен с предупреждением в логе. Какое из написаний выживет — не определено: набор доезжает до проверки замороженным, и порядок его обхода задаётся раскладкой, а не тем, как вы его записали. Присылайте одно написание — регистровая пара означает потерю одного из значений.

Коды ошибок — из объявленного реестра, а не свои строки

Отказ вы возвращаете через Result<T>.Failure(code, message), и code берётся из VeriqaErrorCodes — реестра кодов, объявленного в том же MIT-пакете. Своя строка выглядит работающей, но ядро её не распознаёт: на объявленных кодах ядро ветвит поведение и метит телеметрию, а неизвестный код остаётся строкой в логе. Тело неизвестного формата — UnsupportedEventType, тело без нужных полей идентичности — IdentityExtractionFailed; семантика каждого кода — в XML-документации VeriqaErrorCodes. Один код выделен: ChannelCannotContinue («провести это подтверждение не могу»). Верните его из SendConfirmationPromptAsync, когда канал физически не может задать вопрос по этой транзакции, — и ядро завершит транзакцию неуспехом с этим же кодом причины вместо ожидания до истечения TTL. Пользователь сразу увидит в браузере сообщение об ошибке, в канал ему при этом ничего не придёт. Любой другой код отказа означает «не вышло сейчас»: транзакция ждёт повторной попытки или истечения своего TTL. Причину вы не сообщаете и на выбор ядра не влияете — вы объявляете только собственную неспособность, решение принимает ядро.

GetDeepLinkAsync — куда в итоге ведут кнопка и QR-код

Возвращённая ссылка — то, куда ваш канал приводит пользователя. Ядро просит её запросом DeepLinkRequest: в нём транзакция (TransactionId) и назначение ссылки (Purpose), то есть место, где ссылка будет использована. В hop-режиме (он действует только для канала, объявленного в хосте) QR-код несёт короткую одноразовую hop-ссылку на ваш сервер Veriqa, и её открытие на телефоне приводит к ссылке, которую ваш метод вернул для HopQr. Ссылку в hop-ссылку оборачивает ядро: для hop-режима адаптеру ничего делать не нужно. Назначение можно не учитывать и возвращать одну ссылку на все три. Если платформа передаёт текст в ссылке, передайте запрос в ResolveAsync, как описано в разделе о тексте ссылки выше: тогда ссылка получит формулировку, которую интегратор задал для назначения. Так QR-код с hop-ссылкой может вести к тексту длиннее того, что помещается в QR-код с самой ссылкой. Ссылка для DirectQr должна быть того же вида, что и ссылка для Button: обе — адрес вашего канала или обе — путь страницы Veriqa. По виду ссылки кнопки ядро решает, как показать канал на странице, — например, оборачивать ли QR-код в hop-ссылку. Если ссылка для DirectQr пустая или другого вида, ядро кладёт в QR-код ссылку кнопки и пишет об этом в журнал на уровне Debug. Пронесите идентификатор транзакции в ссылке, чтобы платформа вернула его в вебхуке:
Вызов должен быть идемпотентным и без побочных эффектов. Повторный вызов с тем же запросом возвращает ту же цель и не создаёт состояния: не выпускает новых секретов, ничего не пишет в хранилище и не публикует событий. Вызовы с разными назначениями по одной транзакции тоже не выпускают отдельных секретов. Ядро вызывает метод каждый раз, когда показывает ваш канал, — на странице входа, на странице, где пользователь подтверждения выбирает канал, в ответе API серверного подтверждения — и в hop-режиме ещё раз при каждом открытии hop-ссылки человеком. Метод, который, скажем, выпускает новый одноразовый код на каждом вызове, превращает каждое обновление страницы и каждое сканирование в ещё один живой секрет. Проверить это в вашей реализации ядро не может — обещание держите вы.

Старт по коду — когда на ссылку нельзя положиться

Двум видам платформ одной ссылки мало. У одних нет ссылки, которая и открывает чат с ботом, и несёт полезную нагрузку, — транзакцию в неё не вложить вовсе. У других такая ссылка есть, но то, что она несёт, доставляется не всегда. Канал на любой из них объявляет старт по коду: ядро выдаёт транзакции короткий код из десятичных цифр, показывает его на своих страницах, пользователь отправляет его вашему боту сообщением, а вы передаёте его ядру.
LinkCarriesTransaction — факт о вашей ссылке, остальное ядро решает по нему: Два условия hop-ссылки для первой колонки остаются в силе: канал объявлен в хосте, а issuer — абсолютный HTTPS-адрес. Если хотя бы одно не выполнено, в QR-коде ваша ссылка — она открывает чат, а код пользователь читает со страницы входа. Хост, где такой канал объявлен и включён, маршрутизирует hop-адрес и при выключенном hop-режиме. То, что отправил пользователь, вернётся к вам вебхуком. Снимите свою команду и передайте остальное:
Ядро находит транзакцию по коду и продолжает ровно так же, как после ChannelAuthStartResult. Что кому принадлежит:
  • Формат сообщения — ваш. Ядро подставляет код в MessageTemplate и показывает результат; формулировку оно не толкует. Шаблон пустой, длиннее 64 символов (ChannelCodeStart.MaxMessageTemplateLength) либо содержащий {code} не ровно один раз использовать нельзя: канал с LinkCarriesTransaction = false тогда пропускается на странице, как канал, не построивший ссылку, а канал с true показывается без блока.
  • Код принадлежит ядру. Не нормализуйте его и не проверяйте длину: страница показывает его группами по три цифры, пользователь может прислать его с пробелами или дефисами, и ядро отбрасывает и то и другое. Длина — одна настройка установки, Veriqa:CodeStart:CodeLength: целое от 6 до 10, по умолчанию 6; значение вне диапазона останавливает хост на старте. Один код служит транзакции во всех каналах, объявивших старт, срабатывает один раз и живёт ровно столько же, сколько транзакция.
  • Лимит попыток принадлежит ядру. Событие с кодом списывается с того же бюджета пользователя, что и старт по ссылке, — до поиска кода. Код, не называющий живой транзакции (неизвестный, истёкший, уже использованный), считается как старт, транзакцию которого нельзя обслужить, и получает текст, объявленный для него регистрацией, — UnmatchedCodeReplyText: один на все причины, так что ответ не сообщает, существовал ли такой код. Регистрация, не объявившая его, отвечает текстом StaleLinkReplyText либо молчит, если не объявлен ни тот, ни другой. На адресе вебхука тенанта бюджет пользователя перебор не сдерживает: кто знает секрет вебхука тенанта, подпишет событие от имени любого пользователя. Поэтому коды, которые ничему не подошли, списываются ещё и с бюджета этого тенанта и типа канала: Veriqa:CodeStart:UnmatchedCodePermitLimit кодов (по умолчанию 10) за Veriqa:CodeStart:UnmatchedCodeWindowSeconds секунд (по умолчанию 60). Когда бюджет исчерпан, все события с кодом этой пары до конца окна остаются без ответа, даже с верным кодом. Подошедший код бюджет не тратит, а у адреса без сегмента тенанта такого бюджета нет.
  • Сообщение с кодом маркеров Veriqa не несёт, поэтому OwnsInboundEvent по умолчанию его своим не признаёт. Переопределите член, если раздаёте события по нему.
Код уникален среди всех живых кодов установки, какому бы тенанту ни принадлежал вход. На адресе вебхука без сегмента тенанта он находится для входа любого тенанта. На адресе тенанта принимается только код входа этого тенанта, а код другого тенанта получает ответ на неподходящий код и остаётся действительным. Все тенанты берут коды из одного пространства, поэтому установке, где одновременно идёт много входов, стоит поднять Veriqa:CodeStart:CodeLength.
Из каналов поставки запасной путь объявляют Instagram* и Messenger*: их ссылка транзакцию несёт, но платформа доставляет её не всегда. HTTP-канал объявляет старт конфигурацией — см. Старт по коду. Оба режима можно попробовать на samples/dotnet/custom-channel: его README проводит по старту по коду (AcmeChat:StartByCode) и по запасному пути (AcmeChat:CodeFallback).

3. Имя канала

Тип канала — контракт, а не отображаемая строка. Он обязан соответствовать паттерну:
Строчный URL-safe токен, начинающийся с латинской буквы: kakaotalk, acme-chat, zalo. Значение сравнивается ординально с acr_values и становится сегментом URL-пути, поэтому всё остальное (KakaoTalk, my_channel, пустая строка, значение с хвостовым переводом строки из конфигурации) останавливает старт с сообщением о допустимом формате. Так же сразу останавливают старт повторная регистрация типа и расхождение типа, переданного в AddChannel, со значением ChannelType вашего адаптера. Повторной считается и регистрация типа, уже занятого каналом поставки: каналы поставки регистрируются этим же AddChannel и живут в том же реестре. Тип в AddChannel и ChannelType адаптера обязаны совпадать, потому что весь код ниже находит канал именно по ChannelType адаптера. Последняя проверка выполняется при старте хоста, а не когда открываются маршруты вебхуков, поэтому канал только исходящий или опрашивающий платформу, с mapWebhook: false, проверяется так же строго.
У последней проверки есть одна граница: перекрёстную подмену — адаптер одного канала зарегистрирован под типом другого — она ловит сверкой рантайм-типов адаптеров. Если хост навешивает сквозной декоратор на каждый IChannelAdapter (Scrutor Decorate<IChannelAdapter, …>() или Castle-прокси на весь набор), все адаптеры получают один рантайм-тип, а типы обёрнутых скрыты за ним: такая подмена становится неотличимой от легального декоратора и не отсекается: в этой конфигурации отлов не гарантирован. Для нативных адаптеров и per-adapter class-прокси он точен. Простой случай — тип из AddChannel не объявлен ни одним адаптером — отсекается всегда, независимо от декораторов.

4. Эндпоинт вебхука

Регистрация канала открывает маршруты:
с той же rate-limit-политикой и тем же лимитом тела в 1 МБ, что и маршруты встроенных каналов — generic-путь не позволяет обойти защиты, применённые к telegram или whatsapp. Семантика ответов: Последняя строка — безусловный инвариант: и Failure, и необработанное исключение вашего адаптера попадают в лог, а ответ всё равно 200 с пустым телом. Правило одно для всех каналов: маршруты каналов поставки обслуживает тот же обработчик, поэтому и там исключение адаптера не превращается в 500. На ответы с кодом вне 2xx платформы отключают вебхуки или засыпают повторными доставками, а тело ответа никогда не раскрывает деталей ошибки. Лимит 1 МБ относится к телу запроса: тело читает сам Veriqa, один раз и целиком в память, при сборке конверта — после демультиплексора тенантов и до валидации. Превышение лимита это чтение обрывает по ходу, не дочитывая тело; отказ чтения вердиктом отказа не является, поэтому ответ — 200 и запись в лог уровня Warning, одинаково на generic-маршруте и на маршрутах встроенных каналов. Сверхлимитное событие теряется, но платформа не уводит вебхук в бесконечную переотправку; признак проблемы — запись в логе, а не код ответа. Если канал только исходящий или сам опрашивает платформу, зарегистрируйте его без маршрута:
Канал с опросом сам передаёт ядру каждое обновление. Маршрута нет, поэтому адаптер никто не вызывает. Ваша фоновая служба забирает обновления, превращает каждое в ChannelInboundResult и передаёт его в ChannelInboundProcessor — ту же обработку, через которую идут маршрут вебхука и встроенные каналы с опросом. Это scoped-сервис пакета Veriqa.Core.ChannelAdapter, поэтому открывайте scope на каждое обновление:
Тексты ответов из регистрации на этом пути не применяются: Natural Keys, которые вы задали бы в настройках регистрации, передайте в ChannelReplyTexts сами. С asksInChannelPrompt: true вопрос подтверждения уходит в чат, как с маршрута вебхука. Запускайте цикл каждого тенанта внутри ChannelTenantContext.BeginScope(tenantId), как в разделе Работа по тенантам: тенанта события обработчик берёт из этого scope. Так работает с 0.7.3: в 0.7.1 scope не ограничивает событие, и событие из цикла может подействовать на транзакцию любого тенанта. Объявите у такого канала уровень проверки outbound_fetch.

Настройки регистрации

mapWebhook — единственная настройка, которую короткие перегрузки называют явно. Всё, что регистрация может объявить, собрано в ChannelRegistrationOptions, и обе перегрузки принимают его вместо флага — и форма с типом адаптера, и форма с фабрикой: Пустая строка и строка из пробелов равносильны null: канал молчит. Каналы поставки идут ровно этим путём: их статусные формулировки и handshake объявлены здесь же. MAX и Telegram объявляют StaleLinkReplyText, WhatsApp — нет: сообщение вне утверждённого шаблона там платное, и ответ на каждую протухшую ссылку стоил бы установке денег. Для своего канала решайте по тарифам его платформы. UnaddressedReplyText объявляют Instagram* и Messenger*: первое нажатие там может прийти без транзакции, и ответ подсказывает пользователю отправить код со страницы входа либо отсканировать QR-код ещё раз. Их адаптеры отдают как ChannelUnaddressedResult только нажатую кнопку — набранное сообщение не о входе уходит как ChannelUnrelatedResult и ответа не получает, — и у каждого есть настройка, выключающая этот ответ (Instagram*, Messenger*). Остальные каналы поставки оставляют его null и ничего не отправляют. UnmatchedCodeReplyText объявляют те же два канала — те, что стартуют вход по коду.

Verification-handshake платформы (GET)

Платформы Meta*-семейства подтверждают владение вебхуком GET-запросом на тот же путь с challenge, который нужно вернуть эхом. Объявите query-параметр, который его несёт, — и Veriqa откроет GET-маршрут рядом с POST:
Подлинность handshake — ваша: GET валидирует тот же ValidateWebhookAsync, что и POST, поэтому verify-token, написание, под которым он приходит, и проверка режима — дело вашего адаптера. Veriqa знает только, из какого query-параметра взять значение для эха. Как и POST-маршрут, при любом сбое этот маршрут отказывает: Не объявили — GET-маршрут не открывается вовсе, и путь отвечает 405: именно этого хочет канал, платформа которого handshake не требует.

5. Показ канала в окне входа

Зарегистрированный канал уже виден кнопкой — по умолчанию с именем-типом канала и без иконки. Реализуйте опциональный IChannelDisplayMetadata, чтобы задать название и глиф:
DisplayName — название канала на кнопке, вкладке и в инструкции и базовый текст ключа локализации <DisplayName> | channel, здесь — Acme Chat | channel. Без перевода название показывается как заявлено. Locale-файл хоста переводит его по этому ключу, запись AuthPage:Texts по этому ключу его заменяет, а записи для Sign in with Acme Chat и Confirm in Acme Chat меняют формулировку кнопки. Название с : переводится, но записью не заменяется. Длину названия задаёте вы, поэтому на вкладке и кнопке длинное название обрезается, а всплывающая подсказка показывает его целиком. Пустое значение, как и значение длиннее 32 символов (оно ломает вёрстку окна), заменяется типом канала. IconSvgPath — внутренняя разметка глифа во viewBox 24×24, она встраивается в страницу, поэтому это должна быть ваша статическая разметка, а не пользовательский ввод. Перед отрисовкой значение проверяется по allowlist: только простые фигуры (path, circle, ellipse, rect, line, polyline, polygon, g) с атрибутами в двойных кавычках, без style и без обработчиков on*, длина — не больше 4096 символов. Всё остальное отбрасывается с предупреждением в лог, а канал отрисовывается без иконки. Канал без фирменного цвета отрисовывается нейтральным primary-цветом окна; ChannelButtonColors задаёт его кнопке и иконке цвет, который вы выберете. Если пользователь видит чат вашего канала под собственным именем — username бота, имя аккаунта, — реализуйте ещё и опциональный IChannelBotName:
Ядро подставляет значение как есть в тексты, которые говорят пользователю, в какой чат смотреть: в подпись над кодом и в строку, которая просит подтвердить вход в чате, — страница запуска hop показывает её, когда увела пользователя в канал, а окно входа — когда ваш канал ответил на старт входа или подтверждения. Чат может назвать и формулировка вопроса подтверждения, если в ней есть слот bot_name (шаблоны сообщений). Метод вызывается под тенантом транзакции, как и GetDeepLinkAsync. null, пустое значение, значение длиннее 32 символов или исключение дают те же тексты в формулировке без имени — имя канала на его место не подставляется. Имя из настройки старше. Ключ BotName в секции канала читается раньше, чем опрашивается ваш адаптер, и заданное там имя показывается вместо того, что возвращает GetBotNameAsync, — метод в этом случае не вызывается вовсе. Поэтому канал, не реализующий IChannelBotName, тоже получает имя на страницах и в вопросе подтверждения, если интегратор его задал. Статус-сообщения, которые канал отправляет пользователю, берутся из локализованных текстов Veriqa по умолчанию — задавать их не нужно. При входе это «Вход подтверждён» — либо «Вход подтверждён. Нажмите „Назад“, чтобы вернуться на страницу входа.», когда вход начат на телефоне или планшете, — и «Вход отклонён», при подтверждении действия — нейтральные квитанции исхода «Подтверждено ✅», «Отклонено ❌» и «Время истекло ⌛». Сообщение об ошибке обработки ответа — «Что-то пошло не так. Вернитесь на страницу входа и начните заново.» — текст канала, от типа транзакции он не зависит.

Размер QR-кода

Окно входа рисует QR-код каждого канала в боксе, размер которого задан CSS-токеном --veriqa-qr-size (по умолчанию 220 px). Переопределяется он вашей таблицей стилей — её путь задаётся в Veriqa:AuthPageDesign:CustomCssPath:
Переопределяйте именно токен: он и есть штатная точка управления размером. Правило вида #veriqa-panel-acme-chat .veriqa-qr img { width: … } тот же результат даёт в обход токена и поэтому запрещено — при следующем изменении вёрстки окна оно разъедется с остальными размерами. Уменьшать размер нельзя ниже двух порогов сразу:
  • 200×200 px — минимальный физический размер мишени для камеры;
  • 2,86 px на модуль — плотность: размер бокса ÷ полное число модулей QR вместе с quiet zone.
Критерия два, и выполнение одного не заменяет другого: длинный deep link кодируется QR-кодом более высокой версии, и при том же боксе модуль мельчает до нечитаемого, хотя 200 px формально соблюдены. Размер бокса — только половина картинки: вторая половина — разрешение исходного PNG, то есть число пикселей на модуль. Правило одно, и проверить его нужно сразу, а не только если вы увеличили бокс:
Иначе картинку растянет, а сетка модулей размоется. Почему это касается и поставляемого бокса 220 px. Значение PixelsPerModule по умолчанию, 6, рассчитано на deep link, которые поставляет ядро: самый компактный их QR-код — 45 модулей, и 45 × 6 = 270 px бокс покрывают. При боксе 220 px значения по умолчанию хватает начиная с ⌈220 ÷ 6⌉ = 37 модулей. Разреженнее этого QR-код получается только у очень короткой ссылки: acme://c/8f3k9d — 33 модуля, 33 × 6 = 198 px, растянуто уже в поставляемом боксе. Ссылка из §2, которая проносит идентификатор транзакции (43 символа), под этот случай не попадает — она даёт 45 модулей, и значения по умолчанию хватает. Так что запись ниже нужна вам, только если вы ведёте собственный короткий код со своим сопоставлением с транзакцией. Хост в любом случае стартует: значение в допустимом диапазоне, а число модулей вашего QR-кода ядру неизвестно — проверить правило можете только вы. Если это ваш случай, лечится записью для своего канала:
appsettings.json
Здесь 8 — это ⌈220 ÷ 29⌉: 29 модулей у самого компактного QR-кода, какой вообще возможен (версия 1 вместе с quiet zone), поэтому 8 закрывает поставляемый бокс при любой длине вашего deep link. Увеличили бокс — пересчитайте это значение по той же формуле. Допустимый диапазон — 5…35. Верхняя граница — та же формула для бокса в 1000 px и тех же 29 модулей, поэтому диапазон покрывает любой бокс, помещающийся на экране, при любом канале. Значение вне диапазона хост не запустит — но попадание в диапазон, наоборот, ничего не подтверждает: соответствие формуле остаётся на вас.

6. Регистрация в хосте

Хост — это приложение, встраивающее Veriqa, поэтому он ссылается на ядро сервера:
Program.cs
Секция конфигурации вашего канала принадлежит вам: Veriqa её не знает и не связывает. Свяжите её в хосте и передайте результат адаптеру, а секреты держите в user-secrets или в хранилище секретов, не в appsettings.json. Когда зависимости адаптера резолвятся контейнером, вместо фабричной перегрузки используйте AddChannel<TAdapter>("acme-chat"). Объявите канал рядом с AddChannel. AddChannel регистрирует адаптер и его маршрут, но не создаёт объявления канала на уровне ядра (CoreChannelDeclaration) — это отдельный шаг, тот же, что делают поставляемые каналы. Именно объявление вносит канал в channels_enabled — набор каналов, доступных на уровне ядра, и всё, что читает этот набор, пропускает канал вне его: hop-режим не оборачивает его QR-код, опрос не получает тенантов для запуска, стартовая проверка верификации входящих событий его не касается. Хост при этом стартует — с предупреждением (Warning) в логе, называющим канал, у которого есть адаптер, но нет объявления. Как объявить канал — в разделе Работа по тенантам.

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

Адаптер, который уезжает в поставку Veriqa, регистрируется ещё в одном месте — в каталоге «Поддерживаемые мессенджеры» и его версии на сайте (veriqa.app/channels). Список ведётся вручную: канал, которого в нём нет, поддерживаемым не считается, сколько бы упоминаний о нём ни было в других местах. Запись о канале даёт те же три поля, что и остальные: какие claims канал добавляет сверх обязательных, происходит ли подтверждение внутри канала и нужно ли пользователю отправлять секретное сообщение — или мессенджер сам передаёт код боту. Канал в работе заводится в группах «В разработке» или «В плане», а не во встроенных. Собственного адаптера, который остаётся у вас, это не касается: список описывает поставку Veriqa. Но у своей интеграции стоит завести такую же запись в вашей документации — вопросы к каналу задают те же.

Работа по тенантам

Мультитенантность входит в этот SPI, а не вынесена за его границы. Свой канал читает учётные данные, тексты и лимиты тенанта тем же способом, что и каналы поставки, — через те же публичные части и по одному правилу: тенанта называет тот, кто законно его знает, и называет один раз. Набор тенантов даёт IPollingTenantSource. Получите его из контейнера и спросите, для каких тенантов ваш канал активен; элемент null — неявный тенант self-hosted-установки по умолчанию. У этого есть одно предусловие: набор строится из объявлений зарегистрированных каналов на уровне ядра, а AddChannel объявления не создаёт — он регистрирует адаптер и его маршрут. Поэтому объявите свой канал в хосте, рядом с вызовом AddChannel:
Program.cs
Оба факта читаются делегатами, и каналы поставки замыкают их ровно на эти два аксессора. isEnabled спрашивают заново при каждом построении доступного набора, поэтому он обязан читать источник, переживающий перечитывание конфигурации: монитор, а не объект настроек, связанный один раз, — такой заморозил бы правку на стороне развёртывания. usesPolling — решение на старте, и каналы поставки читают его через IOptions. Обоим нужна секция в контейнере (builder.Services.Configure<AcmeChatOptions>(builder.Configuration.GetSection("AcmeChat"))) — на одну строку больше, чем ручное связывание, которое §6 делает для самого адаптера. Тот же isEnabled вводит ваш канал в channels_enabled уровня ядра. Без объявления набор тенантов возвращается пустым и опрос не запускается, а проверка старта, о которой говорит замечание в §2, вашего канала не касается; с объявлением включённый канал, которому причитается значение InboundVerification, останавливает хост так же, как канал поставки. Тенанта называйте скоупом, вокруг обработки, на своём фоновом пути:
Своя проба здоровья работает вне запроса и отчитывается о самой установке, поэтому тенанта по умолчанию она называет явно — ChannelTenantContext.BeginScope(null), — а не умолчанием: чтение учётных данных без единого открытого скоупа неотличимо от пути, забывшего назвать тенанта, и различить их за вас ниже по стеку некому. На вебхуке скоуп не открывайте. Тенант входящего запроса уже назван — маршрутом (/api/channels/{channelType}/webhook/{tenant}), до вызова вашего адаптера. Свой скоуп, открытый там, перенацелит все чтения учётных данных ниже него, включая чтения ядра, на выбранного вами тенанта вместо названного хостом. Свои учётные данные вы резолвите, а не получаете. Объявите свой ключ и резолвите его публичным IConfigurationResolver с ResolutionContext.ForTenant(tenantId) — тем же каноничным резолвером и тем же порядком уровней, которым идут каналы поставки. Публичная фабрика клиентов IChannelClientFactory для этого не нужна: она строит и кеширует клиента на пару (канал, тенант), а это другая работа. Как объявляется свой ключ — каталог, адрес на каждом уровне, регистрация — описано в Свои ключи конфигурации. * Instagram и Messenger — продукты компании Meta, признанной в России экстремистской организацией; её деятельность в стране запрещена.