Справочник SDK

Каждый SDK Telybot — Android, iOS, React Native, Flutter, Ionic — реализует один и тот же простой контракт. Если вы использовали один из них, вы освоили их все.

API

Открыть с вопросом. Передайте вопрос в show, и он появится в поле сообщения чата; клиент читает его и нажимает «Отправить». Он передаётся во #fragment ссылки и поэтому никогда не попадает в журнал сервера. До 500 символов, одной строкой.

Чат внутри вашего экрана. Android KeydaBotView, iOS KeydaBot.makeChatViewController или SwiftUI KeydaBotView, React Native <KeydaBotChat />, Flutter KeydaBotChat и embedWidget() пакета Ionic. У него нет кнопки закрытия — выход через навигацию вашего экрана. На Android кнопка «Назад» сначала закрывает открытый товар или корзину: React Native и Flutter делают это за вас, пока чат — экран на переднем плане, а с нативным KeydaBotView ваша обработка «Назад» вызывает его goBack().

Ваш авторизованный клиент. Передайте SDK имя, номер телефона или e-mail клиента, и чат заполнит то, что ваше приложение уже знает. Данные предлагаются, но не отправляются: они появляются в форме «поговорить с человеком», в заказе, записи и приветственном вопросе об имени, телефоне или e-mail, а отправляет их сам клиент. Они передаются во #fragment ссылки и являются словом вашего приложения, а не подтверждённой личностью. Значение, которое чат отклонил бы, не передаётся: имя длиннее 80 символов, номер телефона не из 8–15 цифр, адрес e-mail без настоящего домена. Полноэкранный чат Ionic открывается в системном браузере, который хранит адреса в истории, поэтому их не принимает; его встроенный виджет принимает.

Ответ, пока чат закрыт. Когда клиент просит позвать человека и закрывает чат, ваш ответ из панели управления ждёт в беседе. SDK для Android, iOS, React Native и Flutter проверяют это, когда ваше приложение выходит на передний план, и сообщают приложению, чтобы вы могли показать точку на кнопке чата, пока клиент его не откроет. Они спрашивают только о чатах, в которых клиент просил человека за последние 14 дней. Чат, который ваше приложение держит загруженным вне поля зрения, например вкладка «Помощь» в фоне, не считается прочитанным: точка остаётся, пока клиент не посмотрит. Это не push-уведомление: ответ замечается при открытии приложения.

Больше ничего нет — намеренно. Ни API для отправки сообщений, ни вызова идентификации пользователя: ни то ни другое пока не работает от начала до конца, а метод, который не работает, хуже отсутствующего.

URL, который открывает каждый SDK

{baseUrl}/chat/{clientId}

baseUrl по умолчанию https://telybot.com и может быть переопределен на каждой платформе для staging или самостоятельной установки.

Почему веб-представление и сколько это вам стоит

Существует единый интерфейс чата, предоставляемый платформой, который загружается на всех поверхностях.

Что вы получаете: изменения, которые владелец вносит в панели управления — цвет акцента, приветственное сообщение, имя бота, запуск — мгновенно отображаются во всех приложениях без необходимости выпуска обновлений. Исправление применяется везде одновременно. Чат выглядит одинаково на всех платформах.

Стоимость: для работы чата требуется подключение. Офлайн-режима нет, push-уведомлений пока тоже.

Мы предпочитаем, чтобы вы знали об этом до запуска, а не обнаружили после.

Гарантирует, что каждый SDK делает

1. Выходы из навигации. Ссылка на любой другой источник открывается в системном браузере вместо замены чата. Без этого одно нажатие на ссылку в нижнем колонтитуле завершает разговор клиента без возможности вернуться.
2. Непрерывность диалога. DOM-хранилище включено, поэтому клиент, который закрыл приложение и вернулся, найдет свою переписку там, где остановился (в течение 24 часов).
3. Клавиатура никогда не закрывает поле ввода.
4. Безопасные зоны учитываются — чат не перекрывается вырезом экрана или индикатором «Домой».
5. Никакая ошибка не достигнет вашего приложения. При неудачной загрузке отображается возможность повторить попытку.
6. Никакой аналитики, никаких идентификаторов устройств, никаких сторонних зависимостей. Добавление SDK Telybot не добавляет трекеры в ваше приложение.
7. «Назад» сначала закрывает то, на что смотрит клиент. На Android «Назад» поверх открытого товара, корзины или записи закрывает их, и только потом чат (SDK 0.2.0 и новее).

Внутри чата

Всё это приходит с размещённой страницы, поэтому попадает в каждое приложение без обновления SDK:

• Приветственное сообщение с кнопками подсказок на языке, установленном для бота.
• Беседа хранится на устройстве 24 часа, и чат не создаёт идентификатор посетителя. На сайте беседа живёт одну вкладку браузера. (Полноэкранному чату Ionic SDK для этого нужна версия 0.2.0.)
• Заказы и записи, если бизнес их принимает: корзина, даты и время записи, ссылка, чтобы позвонить в бизнес, когда заказ или запись слишком долго ждут, и «Добавить в календарь» для подтверждённой записи.
• Вложения: фото (JPEG, PNG, WebP, GIF) и файлы PDF, DOCX, TXT, CSV и MD. SDK для Android и Flutter нужна версия 0.1.4 или новее для кнопки вложения, а Flutter — 0.2.0 для документов.
• «Добавить в календарь» — это ссылка на файл .ics. iOS открывает его в Календаре как календарь для подписки. Android предлагает календарь телефона, если он импортирует файлы .ics — актуальный Google Календарь это делает, — а иначе браузер скачивает файл.

Формат Client ID

kb_live_ followed by 8-48 hexadecimal characters

Все остальное отклоняется при инициализации, а не открывает 404-ю страницу перед клиентом. Client ID является публичным по своей сути — он виден на любом сайте, где встроен виджет, — и не дает возможности читать или изменять ваш аккаунт. См. лимиты и безопасность.

Источник

Публичный репозиторий с лицензией MIT: github.com/telybotai/telybot-Sdks. Общий контракт, которому должен соответствовать каждый пакет, находится в CONTRACT.md в корне этого репозитория.