Отправка сообщений через API

Последние изменения: 09.09.2024

Для отправки сообщений через API Sherlock Platform сначала надо авторизоваться.

Далее необходимо вызвать метод POST контроллера Message https://<sherlock_url>/API/V2/Message. Полученный токен надо передать в заголовке как Bearer Token.

Альтернативно для чата на сайт рекомендуется вызывать метод POST https://<sherlock_url>/EntryPoint/EntryMessage/ExternalChat/{UserProfileId}. Данный вариант предпочтительнее, так как лучше работает под высокой нагрузкой

В теле запроса необходимо указать параметры сообщения в формате JSON. Пример сообщения приведен ниже:

{ 
"clientId": "CE342419-3D08-4D16-B955-8C72441607BF", 
"requestId": "E13F22E6-0E15-4E04-8294-C34C9ECC0C64", 
"text": "Тестовое сообщение", 
"messageDirectionId": 2, 
"messageCategoryId": 1, 
"isImportant": false, 
"previousMessageDelay": 0, 
"previousMessageDelayType": 2, 
"isBotMessage": true,
"replyToMessageId":"30A2F42B-5D3E-4470-A5FF-00005A198398" 
}

В данном запросе необходимо указывать:

  • ClientID - идентификатор клиента в Sherlock. Если передан, то requestId можно не передавать.

  • RequestId - идентификатор диалога в Sherlock. Если передан, то ClientId не нужен.

  • Text - произвольный текст сообщения

  • MessageDirectionId - всегда 2 для исходящего сообщения

  • MessageCategoryId - 1 для текстового сообщения, 2 - для заметки (не отправляется клиенту, а просто отражается оператору в интерфейсе), 5 - для рассылки (рекомендуется использовать для уведомлений, когда не требуется активация логики очередей)

  • isImportant - всегда false

  • previousMessageDelay - всегда 0

  • previousMessageDelayType - всегда 2

  • isBotMessage - всегда true

  • replyToMessageId - идентификатор сообщения, если данное сообщение отправляется в ответ на указанное

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

{"Buttons":[
   {"Title":"💳 Оплатить",
   "Value":"PaymentStart",
   "Type":"keyboard",
   "Index":1,
   "IsNewLine":true,
   "ClickValue":"",
   "TemplatesList":"",
   "ButtonColor":"",
   "ButtonVKCategory":"",
   "ImageUrl":"",
   "SliderHeight":1
   }
]}

Для описания кнопки используются следующие реквизиты:

  • Title - заголовок кнопки

  • Value - значение кнопки. Передается в чат текстом при нажатии кнопки. Примечание: для перехода по кнопке к конкретному сценарию необходимо в данном реквизите указать код сценария

  • Type - тип кнопки. Возможные значения: reply - кнопка в тексте; keyboard - клавиатурная кнопка под полем ввода; openUrl - кнопка, открывающая ссылку; request_contact - кнопка запроса телефона; request_location - кнопка запроса локации. Примечание: часть каналов могут не поддерживать определенные типы кнопок. 

  • Index - порядковый номер кнопки

  • IsNewLine - если true, то кнопка отражается с новой строки

  • ClickValue - дополнительное значение, сохраняемое в контексте бота при нажатии кнопки под именем ChatButtons_Value

  • TemplatesList - список возможных текстовых строк, которые будут определяться ботом как нажатие на кнопку при отправке пользователем. Формат строки: ["начать", "привет*"], где * заменяет любую последовательность символов

  • ButtonColor - цвет кнопки в формате rgb (#112233). Применяется только для части каналов, где поддерживается цвет кнопки (сейчас - Viber)

  • ButtonVKCategory - категория кнопки в соответствии с документацией ВКонтакте

  • ImageUrl - иконка для кнопки. Применяется только для части каналов, где поддерживается цвет кнопки (сейчас - Viber)

  • SliderHeight - высота кнопки. Применяется только для части каналов, где поддерживается цвет кнопки (сейчас - Viber)

Полный пример сообщения с кнопками приведен ниже:
{ 
"clientId": "CE342419-3D08-4D16-B955-8C72441607BF", 
"requestId": "E13F22E6-0E15-4E04-8294-C34C9ECC0C64", 
"text": "Тестовое сообщение", 
"messageDirectionId": 2, 
"messageCategoryId": 1, 
"isImportant": false, 
"previousMessageDelay": 0, 
"previousMessageDelayType": 2, 
"isBotMessage": true,
"replyToMessageId":"30A2F42B-5D3E-4470-A5FF-00005A198398",
"buttonsText":"{\"Buttons\":[{\"Title\":\"💳Оплатить\",\"Value\":\"PaymentStart\",\"Type\":\"keyboard\",\"Index\":1,\"IsNewLine\":true,\"ClickValue\":\"\",\"TemplatesList\":\"\",\"ButtonColor\":\"\",\"ButtonVKCategory\":\"\",\"ImageUrl\":\"\",\"SliderHeight\":1}]}"
}

Альтернативно можно отправлять кнопки прямо в json формате:

{ 
"clientId": "CE342419-3D08-4D16-B955-8C72441607BF", 
"requestId": "E13F22E6-0E15-4E04-8294-C34C9ECC0C64", 
"text": "Тестовое сообщение", 
"messageDirectionId": 2, 
"messageCategoryId": 1, 
"isImportant": false, 
"previousMessageDelay": 0, 
"previousMessageDelayType": 2, 
"isBotMessage": true,
"replyToMessageId":"30A2F42B-5D3E-4470-A5FF-00005A198398",
"Buttons":[
   {"Title":"💳 Оплатить1",
   "Value":"PaymentStart",
   "Type":"keyboard",
   "Index":1,
   "IsNewLine":true,
   "ClickValue":"",
   "TemplatesList":"",
   "ButtonColor":"",
   "ButtonVKCategory":"",
   "ImageUrl":"",
   "SliderHeight":1
   }
]}

Логика обработки кнопок реализована следующим образом:

  1. Платформа проверяет входящее сообщение по логике в зависимости от канала. Если входящее сообщение - это кнопка, то для сообщение значение ClickValue кнопки сохраняется в ButtonsText сообщения. Сами сообщения можно получить на webhook или прочитать через API

  2. Идет обработка бот платформой - если в значении Value кнопки указан код сценария, то выполняется соответствующий сценарий

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

"fileLinks": [
 {
 "id": "bb9beb09-533c-4af6-8487-5d515c0ea4cd",
 "fileId": "24bbb7e4-09be-4b61-9db7-8f46136f6c5e",
 "objectId": "385172fe-92c8-4bcc-97c1-719560d31f1d",
 "systemDictionaryId": "35df8dfe-d88a-4992-a4d4-54040166ca25",
 "fileName": "Smile.jpg",
 "physicalName": "b6d4303e-6e54-44ea-9066-c8a69e25bc55.jpg",
 "extension": ".jpg",
 "url": "https://<sherlock_url>/API/v2/Files/bb9beb09-533c-4af6-8487-5d515c0ea4cd/Smile.jpg/Attachment",
 "attachmentTypeId": 1
 }
 ]

Файлы предварительно должны быть загружены методом POST контроллера File https://<sherlock_url>/API/v2/Files?objectId=<messageId>&systemDictionaryId=35df8dfe-d88a-4992-a4d4-54040166ca25&fileFolderType=1, где 

  • objectId - идентификатор сообщения

  • systemDictionaryId - идентификатор типа объекта, для сообщений всегда = 35df8dfe-d88a-4992-a4d4-54040166ca25

  • fileFolderType - 1 для вложений к сообщениям

Дополнительно в json сообщения может включаться реквизит ExtraText, формат которого зависит от канала:

  • Facebook - позволяет установить тег сообщения, если указан. Например: {"tag":"POST_PURCHASE_UPDATE"). Список возможных тегов описан в статье Теги сообщений

Помогла ли вам статья?