Общее описание механизма
Механизм вебхуков позволяет сторонним сервисам подписываться на определенные события. После регистрации сервиса, ему станет доступна возможность получать события (принимать запросы с вебхуками) по указанному URL адресу.
URL должен быть доступен через интернет и отдавать status code 200 при успешном запросе. Если endpoint не отдает status code 200 на запрос - вебхук отправится еще раз, и так до 5 раз.
Если по каким-то причинам требуется отписаться от получения событий, то такая возможность предусмотрена.
События разделены на два типа: события приема/отправки сообщения и события команд. Подробный список событий приведен ниже.
Список отсылаемых событий
| Наименование события | Описание |
|---|---|
ChannelConnected |
Канал подключен и работает |
ChannelCreationCommand |
Канал создан |
ChannelDisconnected |
Канал не работает |
ChannelMessageReadCommand |
Сообщение прочитано получателем |
ConversationStartContextUpdateCommand |
Посетитель сайта нажал в виджете кнопку канала для начала беседы в чате |
ChatMemoChanged |
Изменились примечания к чату |
EndUserActionCommand |
Была нажата интерактивная кнопка |
EndUserActivatedNotificationDeepLink |
Посетитель сайта перешел по диплинку, то есть хочет подписаться или начать чат |
EndUserSubscribedOnNotification |
Пользователем осуществлена подписка |
EndUserUnsubscribedFromNotification |
Пользователем осуществлена отписка |
FirstMessageFromEndUserInChatCommand |
Первое входящее сообщение в чате |
MessageDeliveryCommand |
Сообщение доставлено/недоставлено |
new_message |
Получено входящее сообщение или отправлено исходящее сообщение |
NewChatCreatedCommand |
Создан новый чат |
OperatorReadChatCommand |
Сообщение прочитано |
OperatorUnReadChatCommand |
Сообщение отмечено непрочитанным |
TagAssignedOnChatCommand |
Чату присвоен тег |
TagRemovedFromChatCommand |
Тег снят с чата |
WidgetCreateCommand |
Виджет создан |
WidgetDeleteCommand |
Виджет удален |
WidgetDisableCommand |
Виджет отключен |
WidgetEnableCommand |
Виджет подключен |
WidgetUpdateCommand |
Виджет обновлен |
Подключение вебхука
-
curl (инструкция написана под bash)
-
Идентификатор аккаунта - accountId
-
URL приемника вебхуков
-
Список событий
Действия:
-
Подготовить токен зайдя в ЛК аккаунта, затем в интеграцию: https://my.textback.io/messaging.html#!/integration
-
Нажать "Сгенерировать API токен" и сохранить в переменную bash-терминала:
token=eyJ0eXA…-
Сохранить базовый URL в переменную bash-терминала:
base_url=https://tb-notificationsrv-prod.textback.io/notification-
Установить URL приемника вебхука в переменную:
webhook_url=http://somedomain.ru/webhooks-
Установить список событий в переменную (переменная содержит json-массив имен событий)
events=[\"EndUserSubscribedOnNotification\"]Не забывайте про двойные кавычки вокруг имен событий - это должен быть валидный JSON.
-
Подключить вебхук, выполнив запрос:
curl -v $base_url/webhooks -X POST --data "{\"url\":\"$webhook_url\",\"events\":$events}" -H "Authorization: Bearer $token"В теле ответа придет JSON объект, содержащий параметр "id" и являющийся идентификатором вебхука. Он требуется для отключения вебхука.
Отключение вебхука
Полученный ранее идентификатор вебхука необходимо использовать в запросе на отключение
-
Установить идентификатор вебхука в переменную:
id=23...-
Отключить вебхук, выполнив запрос:
curl -X DELETE $base_url/webhooks/$id -H "Authorization: Bearer $token"Описание модели данных вебхуков
ChannelConnected
Канал подключен и работает
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
fullChannel |
Канал |
|
id |
Уникальный идентификатор |
string |
reason |
Причина, по которой канал работает |
enum (new_channel_configured, phone_gone_online, token_refreshed, token_updated) |
userId |
Идентификатор пользователя TextBack |
string |
ChannelCreationCommand
Канал создан
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channel |
Тип канала |
|
channelId |
Идентификатор канала в транспорте |
integer (int64) |
id |
Уникальный идентификатор |
string |
userId |
Идентификатор пользователя TextBack |
string |
ChannelDisconnected
Канал не работает
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
fullChannel |
Канал |
|
id |
Уникальный идентификатор |
string |
reason |
Причина, по которой канал не работает |
enum (phone_gone_offline, token_expired, token_revoked, channel_deleted) |
userId |
Идентификатор пользователя TextBack |
string |
ChannelMessageReadCommand
Сообщение прочитано получателем
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channel |
Тип канала |
|
channelId |
Идентификатор канала в транспорте |
integer (int64) |
channelMessageIdExact |
Конкретное сообщение, которое было прочитано |
string |
channelMessageIdNumericFrom |
Все сообщения прочитаны, начиная с данного идентификатора сообщения и ранее |
integer (int64) |
id |
Уникальный идентификатор |
string |
messageId |
Идентификатор TextBack сообщения |
string (uuid) |
readKind |
Тип параметра сообщения, на основе которого определяется |
|
remoteAddress |
Адрес другой стороны, специфичный для канала |
string |
tbChatId |
Уникальный идентификатор чата в TextBack |
integer (int64) |
timestamp |
Дата события |
integer (int64) |
timestampFrom |
Все сообщения прочитаны до этой отметки времени |
string (date-time) |
userId |
Идентификатор пользователя, прочитавшего сообщение с messageId |
string |
Каналы типа vk, tg, whatsapp, instagram статус прочитываемости не отдают.
ConversationStartContextUpdateCommand
Посетитель сайта нажал в виджете кнопку канала для начала беседы в чате
| Name | Description | Schema |
|---|---|---|
chatAddress |
Ссылка на чат |
|
conversationStartContext |
Информация о месте и условиях когда началась беседа (адрес страницы, данные браузера, cookies, и т.д.) |
|
id |
Уникальный идентификатор |
string |
ChatMemoChanged
Изменились примечания к чату
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
chatAddress |
Подробный адрес чата |
|
id |
Уникальный идентификатор |
string |
memo |
Примечание |
|
tbChatId |
Идентификатор сессии чата при условии поддержки каналом |
integer (int64) |
EndUserActionCommand
Была нажата интерактивная кнопка
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channel |
Тип канала |
|
channelId |
Идентификатор канала в транспорте |
integer (int64) |
id |
Уникальный идентификатор |
string |
payload |
Идентификатор действия, которое вызывается в ответ на действие из мессенджера пользователя |
string (uuid) |
button |
Данные нажатой кнопки типа GetContactButton (только Telegram) |
|
remoteAddress |
Адрес другой стороны, специфичный для канала |
string |
remoteContact |
Информация об участнике диалога |
|
tbChatId |
Идентификатор сессии чата при условии поддержки каналом |
integer (int64) |
timestamp |
Дата события |
integer (int64) |
EndUserActivatedNotificationDeepLink
Посетитель сайта перешел по диплинку, то есть хочет подписаться или начать чат
| Name | Description | Schema |
|---|---|---|
address |
Адрес чата |
|
commandName |
Какой тип команды активирован |
enum (subscribe, start_chat) |
deepLinkId |
Идентификатор диплинка |
string (uuid) |
id |
Идентификатор |
string (uuid) |
messageId |
Идентификатор сообщения |
string (uuid) |
parameters |
URL параметры диплинка |
object |
remoteContaсt |
Информация об участнике диалога |
EndUserSubscribedOnNotification
Пользователем осуществлена подписка
| Name | Description | Schema |
|---|---|---|
id |
Индентификатор |
string (uuid) |
subscription |
Подписка на рассылку |
EndUserUnsubscribedFromNotification
Пользователем осуществлена отписка
| Name | Description | Schema |
|---|---|---|
id |
Идентификатор |
string (uuid) |
initiator |
Информация об инициаторе данного события |
enum (USER_ACTION, OPERATOR) |
remoteContact |
Информация об участнике диалога |
|
subscription |
Подписка |
|
unsubscribedFromAllSubscriptions |
Отписан ли пользователь от всех подписок |
boolean |
FirstMessageFromEndUserInChatCommand
Первое входящее сообщение в чате
| Name | Description | Schema |
|---|---|---|
id |
Идентификатор события |
string (uuid) |
accountId |
Идентификатор аккаунта |
string (uuid) |
userId |
Идентификатор пользователя |
string |
name |
Наименование события |
string |
comand |
Содержимое события |
object |
firstMessage |
Первое сообщение в чате |
MessageDeliveryCommand
Сообщение доставлено/не доставлено
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
address |
Содержит информацию об адресе доставки |
|
channel |
Тип канала |
|
channelDeliveryStatus |
Статус доставки конкретного канала |
string |
channelId |
Идентификатор канала в транспорте |
integer (int64) |
channelJobId |
Временный идентификатор, необходимый для соответствия статусам сообщения |
string |
channelMessageId |
Идентификатор сообщения в канале |
string |
chatId |
Идентификатор сессии чата при условии поддержки каналом |
string |
compositeMessageType |
Тип сообщения |
|
deliveryStatus |
Расширенный статус |
|
id |
Уникальный идентификатор |
string |
isDelivered |
Базовый статус, доставлено ли сообщение |
boolean |
isFinal |
Является ли это изменение статуса окончательным и не предвидится повторных попыток отправки сообщения |
boolean |
masterMessageId |
Идентификатор мастер-сообщения, содержащего вложенные сообщения. Может быть пустым, если сообщение не является частью мастер-сообщения |
string (uuid) |
message |
Доставленное сообщение |
|
messageId |
Идентификатор TextBack сообщения |
string (uuid) |
notificationId |
Идентификатор рассылки, если сообщение является частью массовой рассылки |
string (uuid) |
remoteAddress |
Адрес другой стороны, специфичный для канала |
string |
tbChatId |
Уникальный идентификатор чата в TextBack |
integer (int64) |
timestamp |
Дата события |
integer (int64) |
MessageDeliveryCommand
Канал типа whatsapp ("неофициальный" WhatsApp) отдает статусы доставки нестабильно, поэтому опираться на них не желательно.
Канал типа instagram статус доставки не отдает.
new_message
Событие "Получено новое сообщение"
Polymorphism : Composition
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
id |
Уникальный идентификатор |
string |
message |
Сообщение между оператором и клиентом. Представляет как исходящее, так и входящее сообщения |
|
name |
Наименование события |
string |
substitutions |
Дополнительные значения подстановки для процессора шаблонов |
object |
userId |
Идентификатор пользователя |
string |
NewChatCreatedCommand
Создан новый чат
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channel |
Тип канала |
|
channelId |
Идентификатор канала |
integer (int64) |
chat |
Созданный чат |
|
chatId |
Идентификатор чата |
string |
compositeMessageType |
Тип составного сообщения |
|
createdTs |
Дата создания |
string (date-time) |
firstMessage |
Первое сообщение в чате |
|
id |
Идентификатор |
string |
notificationId |
Идентификатор рассылки, если сообщение является частью массовой рассылки |
string (uuid) |
remoteAddress |
Адрес другой стороны, специфичный для канала |
string |
tbChatId |
Уникальный идентификатор чата в TextBack |
integer (int64) |
OperatorReadChatCommand
Сообщение/чат прочитано оператором
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channel |
Тип канала |
|
channelId |
Идентификатор канала в транспорте |
integer (int64) |
chatId |
Идентификатор сессии чата при условии поддержки каналом |
string |
exactMessageId |
Идентификатор одиночного прочитанного сообщения |
string (uuid) |
id |
Уникальный идентификатор |
string |
remoteAddress |
Адрес другой стороны, специфичный для канала |
string |
sessionId |
Сессия, в которой была инициирована команда или идентификатор токена |
string |
tbChatId |
Уникальный идентификатор чата в TextBack |
integer (int64) |
timestamp |
Дата события |
integer (int64) |
upToChannelMessageId |
Идентификатор сообщения, до которого были прочитаны предыдущие сообщения. Нельзя использовать совместно с параметром upToTimestamp |
string |
upToTimestamp |
Дата, до которой были прочитаны предыдущие сообщения. Нельзя использовать совместно с параметром upToChannelMessageId |
integer (int64) |
userId |
Идентификатор пользователя, прочитавшего сообщение/сообщения |
string |
OperatorUnReadChatCommand
Чат отмечен непрочитанным
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channel |
Тип канала |
|
channelId |
Идентификатор канала в транспорте |
integer (int64) |
chatId |
Идентификатор сессии чата при условии поддержки каналом |
string |
id |
Уникальный идентификатор |
string |
remoteAddress |
Адрес другой стороны, специфичный для канала |
string |
sessionId |
Сессия, в которой была инициирована команда или JTI токен |
string |
tbChatId |
Уникальный идентификатор чата в TextBack |
integer (int64) |
timestamp |
Дата события |
integer (int64) |
upFromTimestamp |
Дата, с которой предыдущие сообщения были отмечены непрочитанными. Нельзя использовать совместно с параметром upToChannelMessageId |
integer (int64) |
upToChannelMessageId |
Идентификатор сообщения, до которого предыдущие сообщения были отмечены непрочитанными. Нельзя использовать совместно с параметром upFromTimestamp |
string |
userId |
Идентификатор пользователя, отметившего сообщения непрочитанными |
string |
TagAssignedOnChatCommand
Чату присвоен тег
| Name | Description | Schema |
|---|---|---|
id |
Идентификатор |
string |
isNewTag |
Является ли тег новым |
boolean |
tag |
Тег |
|
wasActuallyChanged |
Равен true, если на момент назначения тега он был, и false - иначе |
boolean |
TagRemovedFromChatCommand
Тег снят с чата
| Name | Description | Schema |
|---|---|---|
chat |
Чат |
|
id |
Идентификатор |
string |
reason |
Причина, по которой произошло событие |
enum (operator_removed, user_activated_response, ve_removed) |
tag |
Тег |
|
wasActuallyChanged |
Равен true, если на момент удаления тега он был, и false - иначе |
boolean |
WidgetCreateCommand
Виджет создан
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
id |
Идентификатор |
string |
userId |
Идентификатор пользователя |
string |
widget |
Виджет |
|
widgetCode |
Javascript код виджета |
string |
WidgetDeleteCommand
Виджет удален
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
id |
Идентификатор |
string |
userId |
Идентификатор пользователя |
string |
widget |
Виджет |
WidgetDisableCommand
Виджет отключен
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
id |
Идентификатор |
string |
userId |
Идентификатор пользователя |
string |
widget |
Виджет |
WidgetEnableCommand
Виджет подключен
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
id |
Идентификатор |
string |
userId |
Идентификатор пользователя |
string |
widget |
Виджет |
WidgetUpdateCommand
Виджет обновлен
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
id |
Идентификатор |
string |
userId |
Идентификатор пользователя |
string |
widget |
Виджет |
|
widgetCode |
Javascript код виджета |
string |
Attachment
Информация об отправленном или принятом файле. Для отправки необходимо минимально заполнить поле channelFileId ссылкой на закачанный файл
| Name | Description | Schema |
|---|---|---|
channelFileId |
При отправке файла содержит ссылку на закачанный при помощи сервиса /uploads файл |
string |
fileName |
Имя файла в локальной файловой системе отправителя (мессенджеры передают не всегда) |
string |
fileSize |
Размер файла в байтах |
number (integer) |
kind |
Тип вложения. Некоторые мессенджеры по разному могут отображать принятый пользоваетелем файл. Для более user-friendly отображения файла испоьзуйте правильный kind |
enum (document, image, audio, video, thumb, sticker, voice) |
mediaDuration |
Длительность файла, если вложение является видео или аудиозаписью |
number (integer) |
mediaHeight |
Высота кадра, если вложение является фото или видео |
number (integer) |
mediaWidth |
Ширина кадра, если вложение является фото или видео |
number (integer) |
mimeType |
MIME-type файла, если мессенджер пользователя его указал. При отправке из TB не имеет значения |
string |
publicUrl |
Ссылка для скачивания файла оператором TB. Слово public означает не то, что файл доступен без авторизации, а указывает возможность скачивания по API в принципе |
string |
thumbnails |
Массив превью-изображений для данного файла. Наличие превью зависит от мессенджера и kind отправляемого файла |
< Attachment > array |
| Name | Description | Schema |
|---|---|---|
type |
Тип нажатой кнопки |
enum (GetContactButton) |
text |
Название кнопки |
string |
oneTime |
Скрывается ли клавиатура с кнопкой при нажатии |
boolean |
removeKeyboard |
Убирается ли клавиатура после обработки нажатия |
boolean |
payload |
Идентификатор действия, которое вызывается в ответ на действие из мессенджера пользователя |
string |
Channel
Канал
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channel |
Тип канала |
|
channelId |
Идентификатор канала в транспорте |
integer (int64) |
id |
Уникальный идентификатор |
string |
tbUserId |
Идентификатор пользователя, который подключился к каналу или обновил его |
integer (int64) |
channelRead
Информация о прочитанности сообщения в мессенджере
| Name | Description | Schema |
|---|---|---|
channelMessageIdExact |
Идентификатор конкретного прочитанного сообщения |
string |
channelMessageIdNumericFrom |
Все сообщения прочитаны, начиная с данного идентификатора сообщения и ранее |
integer (int64) |
id |
Уникальный идентификатор |
string (uuid) |
readKind |
Тип параметра сообщения, на основе которого определяется прочитанность сообщения |
|
timestampFrom |
Все сообщения прочитаны до этой отметки времени |
string (date-time) |
Channels
Типы каналов
Type : enum (tg, sms, vk, facebook, viber, vibersm, whatsapp, instagram)
Channels
Описание каналов в виджете чата
| Name | Description | Schema |
|---|---|---|
channel |
Тип канала |
|
enabled |
Включен ли |
boolean |
id |
Идентификатор |
string |
slug |
Пользовательская ссылка в мессенджерах |
string |
Chat
Чат между оператором и клиентом
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
address |
Подробный адрес чата |
|
id |
Идентификатор чата |
string |
lastConversationStartContext |
Информация о месте и условиях когда началась беседа (адрес страницы, данные браузера, cookies, и т.д.) |
|
lastMessage |
Посследнее сообщение |
|
messagingStats |
Статистика отправленных в чат сообщений |
|
remoteAddresses |
Список адресов другой стороны, специфичный для канала |
< string > array |
remoteContaсt |
Информация об участнике диалога |
|
tags |
Список тегов |
< string > array |
tbChatId |
Уникальный идентификатор чата в TextBack |
integer (int64) |
unreadCount |
Количество непрочитанных сообщений в чате для аккаунта |
integer (int32) |
ChatAddress
Подробные данные о чате
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channel |
Тип канала |
|
channelId |
Идентификатор канала в транспорте |
integer (int64) |
chatId |
Идентификатор сессии чата при условии поддержки каналом |
string |
remoteAddress |
Адрес другой стороны, специфичный для канала |
string |
tbChatId |
Уникальный идентификатор чата в TextBack |
integer (int64) |
Сity
Информация о городе, указанном в профиле в мессенджере
| Name | Description | Schema |
|---|---|---|
internationalName |
Международное наименование |
string |
nationalName |
Национальное наименование |
string |
CompositeMessageType
Типы сообщений. Полезно в том случае, когда канал не поддерживает более одного прикрепления к сообщению
Type : enum (MASTER_MESSAGE, CHILD_MESSAGE, REGULAR_MESSAGE)
Contact
Информация об участнике диалога
| Name | Description | Schema |
|---|---|---|
birthday |
Дата рождения |
|
channel |
Тип канала |
|
channelUserId |
Идентификатор пользователя в канале |
string |
channelUsername |
Имя пользователя в канале (если доступно) |
string |
city |
Город |
|
country |
Страна |
|
email |
Основная электронная почта |
string (email) |
gender |
Пол |
enum (male, female) |
id |
Идентификатор контакта TextBack |
string (uuid) |
internationalName |
Имя в EN-локали |
|
nationalName |
Имя в пользовательской локали |
|
parentContactId |
Идентификатор TextBack объединенного контакта |
string (uuid) |
phone |
Номер телефона, привязанный к чату в мессенджере |
string |
preferredLanguage |
Предпочитаемая локаль |
string |
timezone |
Cмещение относительно UTC (пользовательская временная зона) |
string |
userPicUrl |
URL аватара пользователя в чате |
string |
userProfileUrl |
URL на профиль пользователя |
string |
ConversationStartContext
Информация о месте и условиях когда началась беседа (адрес страницы, данные браузера, cookies, и т.д.)
| Name | Description | Schema |
|---|---|---|
cookies |
Хранит cookies из HTTP запроса |
object |
insecureContext |
Передаваемый с клиента незащищенный контекст подписки, содержащий, например, номер заказа |
object |
pageTitle |
Заголовок окна |
string |
pageUrl |
URL адрес страницы |
string |
referer |
URL источника запроса |
string |
secureContext |
Защищенный средствами JWT контекст подписки, содержащий, например, номер заказа |
object |
secureContextToken |
Токен |
string |
timezoneOffset |
Смещение часового пояса |
integer |
urlParameters |
Параметры в URL адресе |
object |
userAgentString |
User-Agent браузера |
string |
viewerId |
Идентификатор пользователя текущей страницы |
string (uuid) |
visitDate |
Время посещения |
string (date-time) |
visitsCount |
Число посещений |
integer |
widgetId |
Идентификатор виджета |
string (uuid) |
Сountry
Информация о городе, указанной в профиле в мессенджере
| Name | Description | Schema |
|---|---|---|
internationalName |
Международное наименование |
string |
isoCode |
Код страны в ISO-формате |
string |
nationalName |
Национальное наименование |
string |
DeliveryStatus
Расширенный статус сообщения
Type : enum (DELIVERED, SENT, ACCEPTED_BY_PARTNER, QUEUED, ERROR, API_TIMEOUT, CONNECTION_TIMEOUT, WRONG_ACCOUNT_ID, SERVER_UNAVAILABLE, INVALID_API_TOKEN, INVALID_SENDER, API_REQUEST_LIMIT, BOT_NOT_PUBLISHED, MESSAGE_OUTSIDE_OF_ALLOWED_WINDOW, BLOCKED, INSUFFICIENT_API_PERMISSIONS, USER_DIALOG_NOT_INITIATED, FILE_SEND_LIMITATION, ATTACHMENT_TYPE_NOT_SUPPORTED_BY_CHANNEL, MAXIMUM_CHARACTERS_EXCEEDED, NO_MATCHING_USER_FOUND, INVALID_ADDRESS_FORMAT, PHONE_OFFLINE, PARTIALLY_SENT, PARTIALLY_SENT_WITH_ERROR, ALL_CHILD_SENT_WITH_ERROR, PAYMENT_REQUIRED, BAD_WORDS_FOUND, SPAM, UNSUPPORTED_DEVICE, EXTERNAL_MESSAGE_TIMEOUT, TB_MESSAGE_TIMEOUT, BLACKLISTED UNKNOWN)
EndUserNotificationSubscription
Подписка на события через мессенджеры
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
address |
Адрес чата |
|
id |
Идентификатор |
string (uuid) |
insecureContext |
Незащищенный контекст подписки |
object |
messagingStats |
Статистика отправленных в чат сообщений |
|
remoteContact |
Информация об участнике диалога |
|
secureContext |
Защищенный контекст подписки |
object |
secureContextToken |
Защищенный токен контекста |
string |
sourceOptions |
Причина создания подписки |
|
subject |
Тема события |
string |
subscribedTs |
Дата подписки |
string (date-time) |
unsubscribedTs |
Дата отписки |
string (date-time) |
user |
Кто подписан |
|
widgetId |
Идентификатор виджета |
string (uuid) |
Event
Отсылается по адресу подписки на вебхук
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
id |
Уникальный идентификатор |
string |
name |
Наименование события |
string |
substitutions |
Дополнительные значения подстановки для процессора шаблонов |
object |
userId |
Идентификатор пользователя |
string |
Location
Данные о местоположении
| Name | Description | Schema |
|---|---|---|
latitude |
Широта в градусах |
number (float) |
longitude |
Долгота в градусах |
number (float) |
Memo
Заметка к чату
| Name | Description | Schema |
|---|---|---|
changedTs |
Дата последней модификации |
string (date-time) |
memo |
Текст заметки |
string |
phones |
Контактные телефоны пользователя |
< string > array |
emails |
Контактные emails пользователя |
< string > array |
tbUserId |
Идентификатор последнего оператора TextBack, изменившего примечание |
string (uuid) |
MessageDeliveryStatus
Статус доставки сообщения
| Name | Description | Schema |
|---|---|---|
channelDeliveryStatus |
Статус доставки сообщения конкретного канала |
string |
deliveryStatus |
Расширенный статус |
|
id |
Идентификатор, присвоенный команде MessageDeliveryCommand |
string (uuid) |
isDelivered |
Общий признак, доставлено ли сообщение или нет |
boolean |
isFinal |
Статус доставки сообщения окончательный и не предвидится повторных попыток доставки |
boolean |
timestamp |
Время доставки сообщения |
integer (int64) |
MessagingStats
Статистика отправленных в чат сообщений
| Name | Description | Schema |
|---|---|---|
lastInboundMessageTimestamp |
Дата крайнего входящего сообщения |
string (date-time) |
received |
Количество входящих сообщений |
integer (int32) |
receivedUserSentMessages |
Количество входящих сообщений (user_sent_message) |
integer (int32) |
sent |
Количество исходящих сообщений |
integer (int32) |
total |
Количество входящих и исходящих сообщений |
integer (int32) |
totalNotificationsSent |
Количество исходящих сообщений (tb_sent_end_user_notification) |
integer (int32) |
unread |
Количество непрочитанных сообщений (user_sent_message) |
integer (int32) |
PartialDate
Дата, которая может быть лишь частично указана (например, только год)
| Name | Description | Schema |
|---|---|---|
day |
День |
integer (int32) |
month |
Месяц |
integer (int32) |
year |
Год |
integer (int32) |
PersonalName
Содержит имя и фамилию пользователя
| Name | Description | Schema |
|---|---|---|
displayName |
Отображаемое имя |
string |
firstName |
Имя |
string |
lastName |
Фамилия |
string |
ReadNotificationKind
Типы параметров сообщений, на основе которых определяется
Type : enum (BY_TIMESTAMP, BY_NUMERIC_MESSAGE_ID, BY_EXACT_MESSAGE_ID, BY_TEXTBACK_MESSAGE_ID)
Reads
Информация о прочитанности сообщения в TextBack
| Name | Description | Schema |
|---|---|---|
readTimestamp |
Время, когда сообщение было прочитано |
integer (int64) |
sessionId |
Идентификатор сессии, во время котором было прочитано сообщение |
string |
userId |
Идентификатор пользователя, прочитавшего сообщение |
string |
SenderInfo
Информация об отправителе на стороне TextBack
| Name | Description | Schema |
|---|---|---|
channelUserId |
Идентификатор для типа эндпоинта FROM_CHANNEL |
string |
endpointType |
Источник отправки сообщения |
enum (UNKNOWN, REST_API, TEXT_BACK_WEB, FROM_CHANNEL, END_USER_NOTIFICATION_API, CHANNEL_NOTIFICATION, BOT_API) |
tbUserId |
Идентификатор крайнего пользователя, изменившего примечание |
string (uuid) |
userAgent |
User-Agent браузера |
string |
SubscriptionSourceOptions
Причина создания подписки
| Name | Description | Schema |
|---|---|---|
channelChat |
Чат, импортированный из истории сообщений |
boolean |
createdByOperator |
Если требуется преобразовать существующий tbChat в subscription |
boolean |
subscription |
Пользователь использовал виджет уведомления / deeplink / подписан администратором |
boolean |
tbChat |
Подписка была автоматически создана пользователем, начавшим чат. Будет утановлен в false, если будет создан OptOut. |
boolean |
Tag
Тег присвоен чату
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
chatId |
Идентификатор чата |
string |
id |
Идентификатор |
integer (int64) |
name |
Наименование тега |
string |
assignedTs |
Дата присвоения тега |
string |
reason |
Причина возникновения события |
enum (operator_assigned, user_activated_response, user_subscribed_on_widget, ve_assigned) |
tagId |
Внешний ключ для тега, созданного учетной записью |
integer (int64) |
TbUniMessage
Сообщение между оператором и клиентом. Представляет как исходящее, так и входящее сообщения
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
actionNumbers |
Для каналов, не поддерживающих кнопки |
object |
attachments |
Информация об отправленных или принятых файлах в зависимости от направления сообщения |
< Attachment > array |
channel |
Тип канала |
|
channelId |
Идентификатор канала в транспорте |
integer (int64) |
channelRead |
Информация о сообщении, прочитанном участником диалога. Заполняется для исходящих сообщений, если они прочитаны |
|
chatId |
Идентификатор сессии чата, в котором сообщение было отправлено |
string |
chatTitle |
Название чата |
string |
childMessages |
Если данное сообщение велико для отправки, то оно разбивается на дочерние сообщения. В таком случае, данному сообщению выставляется тип MASTER_MESSAGE, оно не отправляется в канал, но отправляются дочерние сообщения. |
< TbUniMessage > array |
compositeMessageType |
Типы сообщений. Полезно в том случае, когда канал не поддерживает более одного прикрепления к сообщению |
|
contact |
Переадресованный контакт в качестве номера телефона с именем |
|
deliveryStatuses |
Список статусов доставки |
< MessageDeliveryStatus > array |
deliveryTimeout |
Период доставки в формате ISO-8601 |
string (date-time) |
direction |
Входящее или исходящее сообщение |
enum (inbound, outbound) |
id |
Уникальный идентификатор сообщения. Назначается TextBack |
string (uuid) |
location |
Данные о местоположении |
|
masterMessageId |
Идентификатор мастер-сообщения. Указывается в том случае, если присутствуют дочерние сообщения |
string (uuid) |
notificationId |
Идентификатор рассылки, если сообщение является частью массовой рассылки |
string (uuid) |
pushType |
Способ оповещения пользователя о новом сообщении. Поддерживается только Facebook |
enum (REGULAR, SILENT_PUSH, NO_PUSH) |
reads |
Список прочтений сообщений операторами |
< reads > array |
reason |
Причина, по которой данное сообщение было отправлено |
enum (undefined, operator_sent_message, operator_sent_reply_from_messenger, user_sent_message, user_activated_interactive_menu_option, messenger_sent_deep_link_message, tb_sent_end_user_notification, tb_sent_subscription_welcome_message, tb_sent_auto_reply_message, tb_sent_interactive_action_response, tb_sent_operator_notification) |
remoteAddress |
Адрес другой стороны, специфичный для канала |
string |
remoteContact |
Информация об участнике диалога |
|
remoteFirstName |
Имя собеседника |
string |
remoteLastName |
Фамилия собеседника |
string |
replyToChannelMessageId |
Идентификатор сообщения, на которое текущее отвечает |
string |
replyToMessage |
Сообщение, на которое данное сообщение является ответом |
|
senderInfo |
Информация об отправителе сообщения. Заполняется для исходящих (outbound) сообщений |
|
sentTimestamp |
Дата, когда сообщение было отправлено |
string (date-time) |
subject |
Тема сообщения |
string |
substitutions |
Дополнительные значения подстановки для процессора шаблонов |
object |
tbChatId |
Уникальный идентификатор чата в TextBack |
integer (int64) |
templateId |
Идентификатор шаблона сообщения |
string |
text |
Текст сообщения |
string |
textMarkup |
Разметка сообщения |
enum (PLAIN, HTML, MARKDOWN) |
User
Описание пользователя аккаунта
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
externalId |
Идентификатор пользователя во внешней системе |
string |
id |
Идентификатор |
string (uuid) |
User
Информация о операторе аккаунта TextBack
| Name | Description | Schema |
|---|---|---|
displayName |
Отображаемое имя |
string |
email |
Адрес электронной почты |
string (email) |
login |
Логин |
string |
options |
Дополнительные опции |
object |
password |
Пароль |
string |
phone |
Номер телефона в формате E.164 (+7…) или местном для набора (8…) |
string |
Widget
Виджет чата
| Name | Description | Schema |
|---|---|---|
accountId |
Идентификатор аккаунта |
string (uuid) |
channels |
Список виджет каналов |
|
id |
Идентификатор |
string (uuid) |
userId |
Идентфиикатор пользователя |
string |
Описание заголовка Authorization
При отправке вебхуков в запросах к сторонним сервисам, в качестве заголовка авторизации используется JWT токен. Мы передаем авторизационный токен, чтобы принимающая сторона могла убедиться в том, что вебхук был передан действительно от TextBack и для вашего аккаунта.
Authorization: JWT eyJhbGciO...Токен состоит из двух base64 кодированных json объектов:
-
заголовок (Header)
-
полезные данные (Payload)
и сигнатуры (Signature), разделенных точками
xxxxx.yyyyy.zzzzzБолее подробно описано в спецификации RFC 7519 JSON Web Token (JWT)
Заголовок
Содержит параметры:
-
alg - алгоритм шифрования. Применяется ассиметричный RS512
-
typ - тип, значение которого указывает, что это JWT
-
x5u - URI на сертификат X.509, который используется для подписи данного токена (X.509 URL)
Полезные данные
-
iss - уникальный идентификатор стороны, генерирующей токен: TextBack
-
sub - уникальный идентификатор стороны, о которой содержится информация в данном токене: идентификатор аккаунта
-
aud - получатель данного токена: доменное имя сервиса, подписанного на вебхук
-
exp - время в секундах в формате Unix Time, определяющее момент, когда токен станет не валидным
-
iat - время в секундах в формате Unix Time, в которое был выпущен JWT. Используется для определения возраста JWT
Верификация
Ниже описаны шаги для валидации JWT токена.
-
Получение JWT токена из заголовка Authorization
Authorization: Bearer [token]-
Проверка подписи при помощи публичного ключа
Перед тем как начать проверку, следует получить json-объекты заголовка и полезных данных токена. Для этого необходимо разделить токен на заголовок и полезные данные (разделителем является точка) и base64 декодировать полученные строки (не затрагивать сигнатуру).
Для начала, следует проверить, что алгоритм соответствует RS512: у объекта заголовка значение параметра alg должно равняться RS512.
Для проверки токена на валидность, нужно получить публичный ключ по URL, который хранится в параметре x5u заголовка. После этого необходимо воспользоваться готовой библиотекой верификации. Объемный список библиотек представлен на сайте JWT.io.
Если проверка подтвердила подпись, то следующим шагом нужно проверить значения параметров из полезных данных.
-
Проверка значений параметров полезных данных
Для проверки следует использовать полученный ранее на 2 этапе json-объект полезных данных.
-
Проверка времени жизни токена
Текущие дата и время должны быть:
— меньше значения параметра exp
— больше значения параметра iat
-
Проверка стороны, выпустившей JWT
— значение параметра iss должно соответствовать значению TextBack
-
Проверка получателей данного токена
— значение параметра aud должно содержать доменное имя API, подписанного на вебхук