Кейсы Tomoru в образовании

На встрече посчитаем рентабельность внедрения робота и расскажем про бонусы:
Увеличили доходимость на вебинары в 1,5 раза
Fast Track
ЗАКАЗЧИК:
ЗАДАЧА:
ЗАЧЕМ ПОНАДОБИЛСЯ РОБОТ?
Онлайн-университет SkyPro
№ 1 в онлайн-образовании в России по версии SmartRanking
Увеличить доходимость людей на вебинары и мероприятия
Сократить отмены визитов
Информировать об изменениях в мероприятиях
Приглашать на вебинар целевых посетителей
Выступать как дополнительный канал при доведении до вебинара
Сократили отмену
визитов на
Увеличили доходимость на вебинары и мероприятия
30%
x1,5
«Мы подключаем голосовых помощников, чтобы подогревать лидов или просто охватывать больше контактов меньшими усилиями»
Информирует о начале вебинара
Рассказывает о содержании вебинара
Камила Бекназарова,
руководитель CRM-маркетинга в SkyPro

Для авторов микросервисов

В Tomoru существует такое понятие, как "микросервис". Микросервис — это сторонний сервис, который работает отдельно от Tomoru и выполняет какую-то специфичную для него работу.

Робот Tomoru во время диалога может взаимодействовать с микросервисами, для того, чтоб выполнить в них какие-то действия, либо получить из них какие-то данные. Робот Tomoru во время диалога может взаимодействовать с любым количеством микросервисов, подключенных к роботу. Так же микросервис может отсылать произвольные сообщения в робот Tomoru

Взаимодействие с микросервисами осуществляется при помощи вызова методов микросервиса и получения от микросервиса команд.

Создание REST API для микросервиса

Микросервис представляет из себя обычный HTTP-сервис. Tomoru не накладывает жестких ограничений на структуру HTTP-сервиса, формат запросов к нему и ответов от него. Робот Tomoru подстроится под HTTP-сервис и будет вызывать его методы согласно описанию OpenAPI микросервиса.

Например, микросервис может выглядеть как большой HTTP-сервис, который будет среди множеств других методов три следующие метода REST API:

Ищет клиента по имени

GET /client/find?name=:name HTTP/1.1

RESPONSE 200 (application/json)
# Клиен найден

{
  // Уникальный идентификатор клиента "id": 1,
  // Имя клиента "name": "Ivan Ivanov",
  // Адресс клиента "address": "Moskov, Kremlin",
  // Телефон клиента "phone": "+79999999999"
}

RESPONSE 404 # Клиент не найден

Изменяет данные клиента

POST /client/:id/update HTTP/1.1

{
  // Имя клиента "name": "Ivan Ivanov",
  // Адресс клиента "address": "Moskov, Kremlin",
  // Телефон клиента "phone": "+79999999999"
}

RESPONSE 200 # Данные изменены

RESPONSE 403 # Данные для клиент менять запрещено

RESPONSE 404 # Клиент не найден

Создать заказ для клиента

POST /order/create HTTP/1.1

{
  // ID Клиента "client_id": 1,
  // Описание заказа "order_description": "Ботинки и футболка"
}

RESPONSE 200 (application/json)
# Заказ создан

{
  // ID Заказа "order_id": 12
}


RESPONSE 404 # Клиент не найден

Описание микросервиса

Для того чтоб движок Tomoru распознал REST API микросервиса, необходимо описать API в формате OpenAPI v3.

Tomoru полностью поддерживает формат OpenAPI v3, но есть ограничение: Tomoru в данный момент может работать только с запросами и ответами в формате JSON. Это значит, что любые requestBody.content или responses.CODE.content отличные от application/json поддерживаться не будут.

Общие данные микросервиса

Tomoru поддерживает описание микросервиса в соответствии со спецификацией OpenAPI. Общие данные описываются в разделе info.

Помимо стандартных полей Tomoru позволяет указать URL к изображению с логотипом микросервиса. Для этого URL изображения надо указать в поле x-logo раздела info.

Tomoru позволяет описать конфигурацию, которую должен настроить Администратор робота, для использования микросервиса. Часто возникает ситуация, что для работы каких-то методов микросервиса нужны те или иные данные. Tomoru позволяет гибко указать какие именно данные нужны для работы микросервиса. Для этого нужно использовать поле x-config раздела info. В данном поле должен содержаться объект JSON Schema, описывающий конфигурацию микросервиса. Tomoru обработает этот объект и создаст в интерфейсе поля для конфигурирования микросервиса.

Конфигурация микросервиса обязательно должна быть в виде JSON Schema, которая будет описывать 1-уровневый объект с любым количеством полей. Многоуровневые объекты в данный момент не поддерживаются.

Если в спецификаии микросервиса будет найдено описание конфигурации, то Tomoru при подключении микросервиса к роботу, будет отображать в интерфейсе поля для конфигурирования этого микросервиса. Получить конфигурацию внутри какого-то метода микросервиса можно при помощи внедрения стандартного объекта TomoruConfig.

Конфигурация микросервиса будет для каждого робота своя

Пример описания общих данных микросервиса:

openapi: 3.0.3 info: version: 1.0.0 # Заголовок будет отображаться в списке микросервисов,  # а так же в конструкторе, поэтому рекомендуется использовать # заголовок не больше 2-3 слов в длину title: Шаблонизатор # Данная картинка будет использоваться как логотип микросервиса x-logo: https://cdn.rawgit.com/pugjs/pug-logo/eec436cee8fd9d1726d7839cbe99d1f694692c0c/SVG/pug-final-logo-_-colour-128.svg # Описание может быть любой длины # # Первая строка из описания будет использована как краткое описание, # поэтому рекомендуется делать ее максимально емкой. # # Остальные строки будут использоваться как полное описание. # В них поддерживается Markdown-форматирование, включая изображения. description: |
    Шаблонизатор, использующий синтаксис Pug
 [Pug](https://pugjs.org/api/getting-started.html) - это высокопроизводительный шаблонизатор вдохновленный шаблонизатором [Haml](http://haml.info/), позволяющий быстро верстать HTLM-страницы. # Данное поле позволяет описать конфигурацию микросервиса, # которую пользователь должен заполнить, чтоб микросервис работал правильно. # # В данном примере пользователь должен будет заполнить поле # "Язык шаблонизатора", которые будет отправлено в метод микросервиса в виде # объекта `{language: "..."}`. x-config: # Конфигурация должна быть обязательно объектом JSON Schema schema: # Tomoru поддерживает конфигурацию только в виде 1-уровнего объекта type: object properties: # Например, тут для работы микросервиса нужно обязательно указать язык language: # Также поддерживаются типы number, integer и boolean type: string # Описание делайте в несколько слов, т.к. оно будет использоваться в качестве лейбла поля description: Язык шаблонизатора # Для строкового типа можно указать варианты значения enum: - ru-RU - en-US - pt-BR # Для любого типа можно указать значение по умолчанию default: en-US required: - language

Видимость метода микросервиса в Tomoru

В описании OpenAPI может быть огромное количество путей и операций к ним, но что бы Tomoru среди всех операций, описанных в вашей OpenAPI конфигурации, понимал какие нужно ему использовать, существует несколько поддерживаемых тегов операций:

tomoru/call

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

В данный метод можно передать при необходимости любые данные запроса, включая:

tomoru/action

Методы, помеченные данным тегом, будут доступны для вызова "напрямую" из списка микросервисов. Обычно данным тегом удобно помечать служебные методы, которые должен вызывать Администратор робота, например, метод "Позвонить".

В данный метод можно передать при необходимости любые данные запроса, включая:

tomoru/bot_connected

Методы, помеченные данным тегом, будут вызываться роботом Tomoru, когда микросервис будет подключен к роботу.

В данный метод можно передать при необходимости только следующие параметры:

tomoru/bot_disconnected

Методы, помеченные данным тегом, будут вызываться роботом Tomoru, когда микросервис будет отключен от робота.

В данный метод можно передать при необходимости только следующие параметры:

tomoru/config_updated

Методы, вызываемые при обновлении конфигурации микросервиса в роботе Tomoru.

В данный метод можно передать при необходимости только следующие данные запроса:

tomoru/chat_activated

Методы, помеченные данным тегом, будут вызываться роботом Tomoru, когда робот начнет новый диалог с клиентом.

В данный метод можно передать при необходимости только следующие параметры:

tomoru/chat_deactivated

Методы, помеченные данным тегом, будут вызываться роботом Tomoru, когда робот закончит диалог с клиентом.

В данный метод можно передать при необходимости только следующие параметры:

tomoru/new_message

Методы, помеченные данным тегом, будут вызываться роботом Tomoru при каждом новом сообщение в чате.

В данный метод можно передать при необходимости только следующие параметры:

tomoru/event_status_changed

Методы, помеченные данным тегом, будут вызываться роботом Tomoru при изменении статуса события, отправленного в Tomoru.

В данный метод можно передать при необходимости только следующие параметры:

Внедрение стандартных данных и параметров Tomoru в запрос метода микросервиса

Tomoru позволяет вставлять в запрос метода микросервиса определенные стандартные данные различных объектов Tomoru. Для этого необходимо в запросе вставить OpenAPI ссылку ($ref) на определенный объект или параметр Tomoru.

В любой запрос метода микросервиса, где это разрешено, можно в поле parameters вставить ссылку на объект параметры, который будет добавлен к запросу. Так же в любой запрос метода микросервиса, где это разрешено, можно в поле requestBody.content['application/json'].schema.parameters вставить ссылку на стандартные объекты Tomoru, которые будут добавлены к запросу.

Все ссылки имеют формат https://api.tomoru.ru/openapi#/components/schemas/{ТИП_ОБЪЕКТА}.

Тэг, для которого вызван микросервис tag

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлена строка, содержащая тэг, для которого вызван микросервис.

Данное поле удобно использовать, если один и тот же путь микросервиса помечен несколькими тегами, чтоб можно было понять для какого тега был вызван метод.

Пример использования:

/call/setValue: tags: - tomoru/call - tomoru/chat_activated post: requestBody: content: application/json: schema: type: object properties: botId: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/tag'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  tag: 'tomoru/call',
  // ...
}

Уникальный идентификатор робота botId

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлена строка, содержащая ID робота, для которого вызван микросервис.

Пример использования:

/call/setValue: post: requestBody: content: application/json: schema: type: object properties: botId: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/botId'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  botId: '10ra0Z66C4oBdLykQ6kd',
  // ...
}

Уникальный идентификатор чата chatId

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлена строка, содержащая ID чата, для которого вызван микросервис.

Пример использования:

/call/setValue: post: requestBody: content: application/json: schema: type: object properties: chatId: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/chatId'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  chatId: 'p3tltHC8rfsfoaDWLoC8',
  // ...
}

Данные конфигурации микросервиса TomoruConfig

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий настройки микросервиса для робота, в контексте которого вызван метод микросервиса.

Содержит следующие поля:

  • config (объект) - Объект, содержащий конфигурацию микросервиса для текущего робота

Пример использования:

/call/setValue: post: requestBody: content: application/json: schema: type: object properties: config: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruConfig'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ...
  config: {
    // Данные конфигурации
  },
  // ...
}

Данные робота TomoruBot

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий данные робота.

Содержит следующие поля:

  • id (строка) - ID робота
  • title (строка) - Название робота

Пример использования:

/call/setValue: post: requestBody: content: application/json: schema: type: object properties: bot: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruBot'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ... bot: {
    id: '10ra0Z66C4oBdLykQ6kd',
    title: 'My mega bot',
  },
  // ...
}

Данные чата TomoruChat

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий данные чата.

Содержит следующие поля:

  • id (строка) - ID чата
  • uri (строка) - URI чата, может быть:
    • id://... - Уникальный идентификатор чата
    • tel://... - Телефонный номер чата
    • https://vk.com/... - URI чата в мессенджерах

Пример использования:

/call/setValue: post: requestBody: content: application/json: schema: type: object properties: chat: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruChat'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ... chat: {
    id: 'p3tltHC8rfsfoaDWLoC8',
    title: 'Ivan Petrov',
  },
  // ...
}

Данные интеграции, для которой создан чат TomoruChatIntegration

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий данные чата.

Содержит следующие поля:

  • id (строка) - ID интеграции чата
  • title (строка) - Название интеграции
  • type (строка) - Тип интеграции, возможные значения:
    • vk - Интеграция с Вконтакте
    • telegram - Интеграция с Telegram
    • helpdeskeddy - Интеграция с HelpDeskEddy
    • viber - Интеграция с Viber
    • webchat - Интеграция в виджетом "Веб-чат на сайт"
    • phone - Телефонная интеграция
    • bitrix24 - Интеграция с Bitrix24
    • wazzup - Интеграция с Wazzup
  • config (объект) - Конфиг интеграции чата

Пример использования:

/call/setValue: post: requestBody: content: application/json: schema: type: object properties: chatIntegration: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruChatIntegration'

Будет вызван метод: https://api.acme.com/call/setValue с телом, которое будет содержать объект:

{
  // ... chatIntegration: {
    id: '1471UsiDySF9QyWIRePl',
    title: 'Incomming phone',
    type: 'phone',
    config: { language: 'ru-RU' },
  },
  // ...
}

Сообщение чата TomoruMessage

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий текущее сообщение чата.

Может использоваться только в методах, помеченных тегом tomoru/new_message

Содержит следующие поля:

  • id (строка) - ID сообщения
  • date (строка) - Дата сообщения в формате RFC 3339, секция 5.6
  • direction (строка) - Направление сообщения. Может быть одним из значений:
    • incoming - Входящее сообщение (фраза клиента)
    • outgoing - Исходящее сообщение (ответ робота или оператора)
  • text (строка, может отсутствовать) - Текст сообщения, если сообщение содержит текст
  • attachmentUrl (строка, может отсутствовать) - URL для загрузки вложения в сообщении, если сообщение содержит вложение. URL будет действителен 30 минут с момента отправки. Используйте его только для загрузки вложения.

Пример использования:

/onNewMessage: post: tags: - tomoru/new_message requestBody: content: application/json: schema: type: object properties: message: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruMessage'

Будет вызван метод: https://api.acme.com/onNewMessage с телом, которое будет содержать объект:

{
  // ... message: {
    id: '10ra0Z66C4oBdLykQ6kd',
    date: '2020-05-07T10:16:29',
    direction: 'incoming',
    text: 'Hello!',
  }
  // ...
}

Список сообщений чата TomoruMessages

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен массив, содержащий сообщения чата.

Может использоваться только в методах, помеченных тегом tomoru/chat_deactivated

Структура элеметнов массива совпадает с TomoruMessage.

Пример использования:

/onDeactivate: post: tags: - tomoru/chat_deactivated requestBody: content: application/json: schema: type: object properties: messages: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruMessages'

Будет вызван метод: https://api.acme.com/onDeactivate с телом, которое будет содержать объект:

{
  // ... messages: [
    {
      id: '10ra0Z66C4oBdLykQ6kd',
      date: '2020-05-07T10:16:29',
      direction: 'incoming',
      text: 'Hello!',
    },
    {
      id: '20rs0Z66C4oBGLy7Q6kz',
      date: '2020-05-07T10:17:10',
      direction: 'outgoing',
      text: 'How are you?',
    },
  ]
  // ...
}

Статус события TomoruEventStatus

Если используется в теле запроса микросервиса, то в тело микросервиса будет добавлен объект, содержащий текущий статус события микросервиса.

Может использоваться только в методах, помеченных тегом tomoru/event_status_changed

Содержит следующие поля:

  • trackingId (строка) - ID отслеживания события, которое установил микросервис, вызывая событие
  • event (строка) - Название события. которое установил микросервис, вызывая событие
  • status (строка) - Новый статус события, может быть одним из:
    • sent_to_bot - Событие отправлено на обработку роботом
    • processed - Событие обработано роботом
    • rejected - Событие НЕ обработано роботом

Пример использования:

/eventChanged: post: tags: - tomoru/event_status_changed requestBody: content: application/json: schema: type: object properties: eventStatus: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruEventStatus'

Будет вызван метод: https://api.acme.com/call/eventChanged с телом, которое будет содержать объект:

{
  // ... eventStatus: {
    trackindId: '100',
    event: 'cold_call',
    status: 'sent_to_bot',
  },
  // ...
}

Результаты работы микросервисов

Каждый response пути paths, описанного в OpenAPI, будет представлен как результат выполнения метода микросервиса. Tomoru никак не ограничивает выбор статуса для ответа.

Будьте внимательны со стандартными HTTP-статусами, т.к. некоторые из них (например, 204 No Content) не предусматривают тела ответа, поэтому многие библиотеки для работы с HTTP могут не отправить в ответе данные, даже если вы их укажите.

Пример описание микросервиса при помощи OpenAPI

Для приведенного выше микросервиса описание будет выглядеть так:

openapi: 3.0.3 info: version: 1.0.0 title: Клиентская база # Рекомендуется писать развернутую документацию по сервису # для того, чтоб пользователи микросервиса могли понять зачем он нужен description: Сервис для работы с нашей внутренней клиентской базой servers: - url: https://api.acme.com paths: /client/find: get: # Рекомендуем для каждой операции указывать уникальный operationId, # для того, чтоб в будущем можно было для операции поменять путь или # метод вызова без необходимости исправлять логику работы роботов Tomoru operationId: findClient summary: Ищет клиента по имени tags: # Тег tomoru/call показывает, что данный метод должен быть доступен для # вызова роботом Tomoru. Если в вашей OpenAPI конфигурации присутствуют # ваши внутренние методы, то их помечать данным тегом не нужно - tomoru/call parameters: - in: query name: name # Для всех параметров и полей запросов желательно делать описание в # одно, два слова, т.к. это описание будет отображено в конструкторе # и длинное описание будет обрезано. Т.е. тут очень емко в 2 словах. description: Имя клиента schema: type: string required: true responses: 200: description: Клиент найден content: application/json: schema: type: object properties: id: type: integer description: ID клиента name: type: string description: Имя клиента address: type: string description: Адрес клиента phone: type: string description: Телефон клиента required: - id - name - phone 404: description: Клиент не найден /client/{id}/update: post: operationId: updateClient summary: Обновляет информацию о клиенте tags: - tomoru/call parameters: - in: path name: id description: ID клиента schema: type: integer required: true requestBody: content: application/json: schema: type: object properties: name: type: string description: Имя клиента address: type: string description: Адрес клиента phone: type: string description: Телефон клиента required: - name - phone responses: 200: description: Данные обновлены 403: description: Обновление запрещено 404: description: Клиент не найден /order/create: post: operationId: createOrder summary: Создает заказ tags: - tomoru/call requestBody: content: application/json: schema: type: object properties: client_id: type: integer description: ID клиента order_description: type: string description: Содержимое заказа required: - client_id - order_description responses: 200: description: Заказ создан content: application/json: schema: type: object properties: order_id: type: integer description: ID заказа required: - order_id 404: description: Клиент не найден

Добавление действия микросервиса

Tomoru позволяет добавлять кнопки с произвольными действиями в список микросервисов робота. Данные кнопки удобны для выполнения разовых операций Администратором робота над микросервисом. Ярким примером такого действиям может быть действие "Позвонить по списку клиентов", которое будет вызывать Администратор робота для того, чтоб обзвонить список клиентов, сохраненный в микросервисе. При нажатии на кнопку действия, Tomoru вызовет соответствующей ей метод микросервиса.

Для того, чтобы Tomoru добавило кнопку с действием в список микросервисов рядом с микросервисом, нужно создать метод и поменить его тегом tomoru/action. В действия как и в другие методы микросервиса можно добавлять стандартные данные Tomoru.

Действие должно вернуть 1 или более результатов, если будет возвращен результат с кодом отличным от 2хх, то Tomoru будет считать, что действие не выполнено.

Пример описание спецификации OpenAPI для добавления действия

Ниже приведен пример микросервиса, который добавит действие "Позвонить"

openapi: 3.0.3 info: version: 1.0.0 title: Клиентская база # Рекомендуется писать развернутую документацию по сервису # для того, чтоб пользователи микросервиса могли понять зачем он нужен description: Сервис для работы с нашей внутренней клиентской базой servers: - url: https://api.acme.com paths: /action/call: get: # Рекомендуем для каждой операции указывать уникальный operationId, # для того, чтоб в будущем можно было для операции поменять путь или # метод вызова без необходимости исправлять логику работы роботов Tomoru operationId: call # Данное поле будет отображено как лебл кнопки summary: Позвонить # Данное поле будет отображено во всплывающей подсказки для действия description: Инициирует звонок по списку всех клиентов нашей БД tags: # Тег tomoru/action показывает, что данный метод должен быть доступен в  # в качестве действия микросервиса - tomoru/action parameters: # Добавим в запрос ID робота, для которого будет вызвано действие - in: query name: botId schema: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/botId' required: true # Добавим в запрос ID чата, для которого будет вызвано действие - in: query name: chatId schema: $ref: 'https://api.tomoru.ru/openapi#/components/schemas/chatId' required: true responses: 200: description: Звонок пошел

Отправка микросервисом событий в Tomoru

Роботы Tomoru могут получать произвольные события от микросервисов. Для того, чтобы микросерис мог отправлять события в Tomoru, нужно сделать две вещи:

  1. Создать веб-хук микросервиса с тегом tomoru/subscribe, который Tomoru будет вызывать для того, чтоб подписаться на события микросервиса.
  2. Прописать OpenAPI-коллбеки в этом веб-хуке, которые будут описывать события робота.

Создание веб-хука tomoru/subscribe

Необходимо создать веб-хук с тэгом tomoru/subscribe, который будет принимать от Tomoru POST-запрос со следующими данными в формате JSON:

{
  tomoruCallbackUrl: 'https://europe-west1-tomoru-2bb77.cloudfunctions.net/microserviceEvent/{JWT_token}',
}

В JSON-теле запроса будет обязательное поле tomoruCallbackUrl, содержащее ссылку, по которой микросерис сможет отправлять свои события. Эту ссылку надо куда-то сохранить, чтоб микросервис мог ее в дальнейшем использовать. Tomoru в любой момент может вызвать данный метод с другой ссылкой, поэтому ее нужно сохранять так, чтоб микросерис мог ее заменить.

Описание OpenAPI-коллбеков

Для того, чтобы Tomoru мог понять какие именно события микросервис планирует отправлять, их нужно описать. Делается это при помощи OpenAPIv3 возможность - коллбеков. Необходимо в методе, помеченном тегом tomoru/subscribe, в поле callbacks описать все события, которые будет отсылать микросервис. Обязательное условие — это формат записи callback URL в поле callbacks - оно должно быть всегда {$request.body#/tomoruCallbackUrl}.

Все события должны отсылаться обязательно POST запросом.

На тело событий Tomoru накладывает ограничение по формату, он должен быть вида:

{
  // Имя события, которое совпадает с ключем объекта `callbacks` OpenAPI спецификации  // микросервиса event: '<ИМЯ_СОБЫТИЯ>',
  // Уникальный идентификатор события, который используется в трекенге статуса события в методах, // помеченных тегом `tomoru/event_status_changed`. См. "Отслеживание изменения статуса событий". // // Может быть любой строкой. Генерируется на стороне микросервиса. // // Не обязательно поле, если не указано, то статусы события трекаться не будут. trackingId: '<ID_СОБЫТИЯ>',
  // ID робота, в который надо отправить событие botId: '<ID_РОБОТА>',
  // URI для идентификации чата, в который нужно отправить событие chatUri: '<URI_ЧАТА>',
  data: {
    // Не обязательный объект, содержащий произвольные данные, которые будут // доставлены в Tomoru вместе с событием
  }
}

Поле event должно содержать имя события. "Имя события" - это то, как называется параметр, описывающий событие, в поле callbacks OpenAPI конфигурации.

Микросервис может отправлять события только в те роботы, в которые он добавлен. Для того, чтоб указать в какой именно чат робота надо отправить событие, нужно указать chatUri, который может быть следующего вида:

  • id://<ИД_ЧАТА> (например, id://lwfw6HpLC1kOslgPREhh) - чат будет найден по его ID. Лучше всего использовать именно поиск по ID чата, т.к. этот способ гарантирует то, что событие будет доставлено именно в тот чат, в который нужно
  • tel://<ТЕЛЕФОН_ЧАТА> (например, tel://+79999999999) - чат будет найден по номеру телефона
  • https://vk.com/<ИД_АККАУНТА> (например, https://vk.com/1) - чат будет найден по ID пользователя во вконтакте
  • tg://<ИД_АККАУНТА> (например, tg://1) - чат будет найден по ID пользователя в Telegram
  • viber://<ИД_АККАУНТА> (например, viber://1) - чат будет найден по ID пользователя в Viber

Tomoru позволяет отслаживать статус события, если передать вместе с событием его уникальный идентификатор в поле trackingId.

Отслеживание статусов событий

Если микросервису необходимо отследить жизненный цикл своих событий, то микросервис может подписаться на изменения статусов событий.

Для начала в микросервисе надо реализовать метод, который будет помечен тегом tomoru/event_status_changed. На данный метод не накладываются никакие специальные ограничения, но внутри него помимо других стандартных объектов Томору, можно использовать стандартный объект TomoruEventStatus.

Потом в каждом событии нужно задавать поле trackingId, и тогда Tomoru будет отсылать на указанный веб-хук информацию об изменении статуса события.

Пример описания OpenAPI конфигурации микросервиса, работающего с событиями

Микросервис ниже описывает метод /subscribe для получения URL веб-хука, используемого для отправки события, и два собвтия: "Холодный звонок" и "Проверка качества".

openapi: 3.0.3 info: version: 1.0.0 title: Демо микросервис description: Сервис, демонстрирующий возможности обработки событий роботом servers: - url: https://api.acme.com/demoMicroservice paths: /subscribe: post: operationId: subscribe summary: Подписывается на события tags: # Тэг, показывающий, что данный метод Tomoru должен использовать для # того, чтоб подписаться на события микросервиса - tomoru/subscribe requestBody: content: # POST-запрос https://api.acme.com/demoMicroservice/subscirbe прийдет # объект, содержащий tomoruCallbackUrl, который нужно сохранить где-то application/json: schema: type: object properties: tomoruCallbackUrl: type: string required: - tomoruCallbackUrl callbacks: # При отправке этого события в толе `event` POST-запроса должно быть 'coldCall' coldCall: # Callback URL всгде должен быть такого вида '{$request.body#/tomoruCallbackUrl}': # Все коллбеки должны вызываться только при помощи POST-запросов post: # Тут лучше использовать описание в несколько слов, чтоб событие  # хорошо выглядело в конструкторе Tomoru summary: Холодный звонок # Тут можно использовать сколь угодно длинное описание того как работает # событие description: Звонок новым клиентам requestBody: content: application/json: schema: # Для удобства можно использовать OpenAPI функцию allOf # и готовое описание обязательных полей тела события # 'https://api.tomoru.ru/openapi#/components/schemas/TomoruEvent' allOf: - $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruEvent' - type: object properties: # В свойстве data можно описать произвольный набор данных, # которые Tomoru получит вместе с событием. data: type: object properties: userName: type: string # Описание полей должно быть в несколько строк для удобства работы # с ними в констукторе Tomoru description: Имя пользователя example: Ivan required: - userName responses: 200: description: Все ок qualityControlCall: '{$request.body#/tomoruCallbackUrl}': post: summary: Проверка качества description: Звонок клиентам с целью проверки качества requestBody: content: application/json: schema: allOf: - $ref: 'https://api.tomoru.ru/openapi#/components/schemas/TomoruEvent' - type: object properties: data: type: object properties: userName: type: string description: Имя пользователя example: Ivan visitDate: type: string description: Дата визита example: 11.12.2020 11:22 required: - userName - visitDate responses: 200: description: Все ок responses: 200: description: Успешно подписались на события

Добавление микросервиса в Tomoru

Добавить микросервис в Tomoru можно при помощи утилиты командной строки @tomoru/cli. Для работы данной утилиты требуется node.js версии 10 или выше.

Установить утилиту можно так:

npm install -g @tomoru/cli

После установки утилиты, будет доступна консольная команда tomoru.

Добавлять микросервисы в робот могут только пользователи с правами администратора на робота. Для добавления микросервис в робот Tomoru нужно выполнить следующую команду:

tomoru microservice set <уникальный_ид_микросервиса> <путь_к_файлу_конфигурации> --bot-id=<уникальный_идентификатор_робота>

# Например:
tomoru microservice set my_back_api ./api.yaml --bot-id=4jTGH3iO4sWEMLC4Y148

Best Practice

Используйте "подходящие" типы HTTP-запросов

Старайтесь использовать "подходящие" типы HTTP-запросов для методов. Например, если предполагается, что метод не меняет никаких данных, и результат его при вызове с одними и теми же параметрами всегда будет одинаковый, то лучше использовать GET-запрос, т.к. Tomoru сможет закешировать результат запроса и использовать его повторно, из-за чего скорость работы робота будет выше, а нагрузка на микросервис - ниже.

Возвращайте в результатах те данные, которые описали в спецификации OpenAPI

Tomoru контролирует то, что возвращает метод микросервиса в результате своего выполнения, и, если результат работы метода, будет отличаться от того, что заявлено в спецификции, то Tomoru может отвергнуть результат работы.

Предусматривайте результат метод "Что-то пошло не так" (500 ошибка)

Всегда в любом коде может случайно закрастья ошибка, это касается и методов микросервисов. Поэтому рекомендуем предусматривать результат на 500 ошибку, чтоб ее можно было обработать в логике робота.

Давайте подробные и понятные описания для микросервиса

Давайте полное и понятное описание микросервиса (поле description в info), для того, чтоб пользователи вашего микросервиса могли понять, что он делает. Tomoru в данном поле поддерживает описание в формате Markdown (включая изображения), поэтому в описание можно использовать Markdown - форматирование.

Первая строчка из описания будет отображена в списке микросервисов рядом с названием, поэтому рекомендуется делать ее краткой, описывающей главный функционал микросервиса.

Давайте подробное описание для методов микросервиса и их результатов

Старайтесь в описании метода микросервиса (поле description в пути) объяснить, что именно будет делать метод микросервиса, как он будет вести себя при различных входящих параметрах, и какие результаты будут ожидаемыми и в каких случаях.

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

Давайте понятное название для параметров методов и результатов микросервисов (поле description параметра).

Первая строка из описания будет отображена как название параметра, поэтому делайте ее не больше 1-2 слов

Book design is the art of incorporating the content, style, format, design, and sequence of the various components of a book into a coherent whole. In the words of Jan Tschichold, "Methods and rules that cannot be improved upon have been developed over centuries. To produce perfect books, these rules must be revived and applied." The front matter, or preliminaries, is the first section of a book and typically has the fewest pages. While all pages are counted, page numbers are generally not printed, whether the pages are blank or contain content.
В теории с помощью грамотно организованного тайм-менеджмента люди успевают работать, отдыхать, заниматься любыми делами и проводить время с семьей. При этом они меньше тревожатся за сроки, потому что видят всю проделанную работу, ближайшие задачи и менее приоритетные. Поэтому вместо ощущения «Я ничего не успеваю, столько всего нужно сделать» появляется понятный план и чувство, что всё под контролем.

Техники тайм-менеджмента состоят из трех компонентов:
The best ideas come as jokes. Make your thinking as funny as possible.
The work you do whileShow more

Design creates culture. Culture shapes values. Values determine the future.

LET'S GO!
В теории с помощью грамотно организованного тайм-менеджмента люди успевают работать, отдыхать, заниматься любыми делами и проводить время с семьей. При этом они меньше тревожатся за сроки, потому что видят всю проделанную работу, ближайшие задачи и менее приоритетные. Поэтому вместо ощущения «Я ничего не успеваю, столько всего нужно сделать» появляется понятный план и чувство, что всё под контролем.

Техники тайм-менеджмента состоят из трех компонентов:
Book design is the art of incorporating the content, style, format, design, and sequence of the various components of a book into a coherent whole. In the words of Jan Tschichold, "Methods and rules that cannot be improved upon have been developed over centuries. To produce perfect books, these rules must be revived and applied." The front matter, or preliminaries, is the first section of a book and typically has the fewest pages. While all pages are counted, page numbers are generally not printed, whether the pages are blank or contain content.