Отправка и получение сообщений¶

Управление пользователями¶

Получение данных пользователя¶

Для получения данных пользователя необходимо вызвать GET /api/customers/{customerId}, передавая данные авторизации в заголовке.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя. Можно получить из коллбэков. Path-параметр.
needLastMessageSendTime	boolean	Если true, в ответе появится параметр с датой и временем отправки последнего сообщения от данного пользователя.

Пример запроса¶

curl -X GET "https://chat.devinotele.com/api/customers/145345" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Параметры ответа¶

Параметр	Тип данных	Описание
id	integer	ID пользователя, который можно получить из коллбэков.
externalId	string	ID пользователя из канала, который инициировал переписку.
creationDateTime	string	Дата создания пользователя.
lastMessageSendTime	string	Дата и временя отправки последнего сообщения от данного пользователя.
channelProfileId	integer	ID канала чата.
additionalInfo	object	Дополнительная информация о пользователе, автоматически полученная через канал общения. В зависимости от канала общения, эта информация будет отличаться.
agentAdditionalInfo	object	Дополнительная информация о пользователе, которую вручную добавил агент. В личном кабинете из данного объекта отображаются только три поля: ○ `phone` - номер телефона пользователя. ○ `email` - email пользователя. ○ `note` - внутренний комментарий от агента.
externalAdditionalInfo	object	Дополнительная информация о пользователе, которую можно добавить через отдельный метод. Рекомендуется использовать этот объект для загрузки данных из CRM-систем.
tags	array[object]	Список объектов тэга, прикрепленных к пользователю. Каждый объект содержит в себе параметры: ○ `id` - ID тэга. ○ `name` - название тэга.
navigationHistory	array	Список ссылок, по которым пользователь перешел в чат с агентом.
title	string	Заголовок диалога. Содержит ID пользователя.
avatarUrl	string	Ссылка на аватар пользователя.

Пример ответа¶

{
  "result": {
    "id": 123393,
    "externalId": "71112223344",
    "creationDateTime": "2023-09-01T08:07:35.761839",
    "lastMessageSendTime": "2023-09-01T08:10:04",
    "channelProfileId": 10064,
    "additionalInfo": {
      "name": "John",
      "phone": "71112223344"
    },
    "agentAdditionalInfo": {
      "phone": "71112223344",
      "email": "john@devino",
      "agentNote": "Customer"
    },
    "tags": [
      {
        "id": 141,
        "name": "Customer Support"
      }
    ],
    "navigationHistory": [
        "http://localhost:8090/"
    ],
    "title": "#123393 John"
  }
}

Обновление данных пользователя¶

Для добавления дополнительных данных пользователя необходимо вызвать PUT /api/customers/{customerId}, передавая данные авторизации в заголовке и данные пользователя в теле запроса.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя. Можно получить из коллбэков. Path-параметр.
externalAdditionalInfo	object	Дополнительная информация о пользователе. Рекомендуется использовать этот объект для загрузки данных из CRM-систем.

Пример запроса¶

{
  "externalAdditionalInfo": {
    "country": "Russian Federation",
    "city": "Moscow",
    "category": "Sport"
  }
}

Параметры ответа¶

Параметр	Тип данных	Описание
id	integer	ID пользователя, который можно получить из коллбэков.
externalId	string	ID пользователя из канала, который инициировал переписку.
creationDateTime	string	Дата создания пользователя.
channelProfileId	integer	ID канала чата.
additionalInfo	object	Дополнительная информация о пользователе, автоматически полученная через канал общения. В зависимости от канала общения, эта информация будет отличаться.
agentAdditionalInfo	object	Дополнительная информация о пользователе, которую вручную добавил агент. В личном кабинете из данного объекта отображаются только три поля: ○ `phone` - номер телефона пользователя. ○ `email` - email пользователя. ○ `note` - внутренний комментарий от агента.
externalAdditionalInfo	object	Дополнительная информация о пользователе, которую можно добавить через отдельный метод. Рекомендуется использовать этот объект для загрузки данных из CRM-систем.
tags	array[object]	Список объектов тэга, прикрепленных к пользователю. Каждый объект содержит в себе параметры: ○ `id` - ID тэга. ○ `name` - название тэга.
navigationHistory	array	Список ссылок, по которым пользователь перешел в чат с агентом.
title	string	Заголовок диалога. Содержит ID пользователя.
avatarUrl	string	Ссылка на аватар пользователя.

Пример ответа¶

{
  "result": {
    "id": 123392,
    "externalId": "71118223344",
    "creationDateTime": "2023-09-01T08:04:25.156238",
    "channelProfileId": 10064,
    "additionalInfo": {
      "name": "John",
      "phone": "71118223344"
    },
    "agentAdditionalInfo": {
      "name": "John",
      "lastName": "Smith",
      "age": "37"
    },
    "externalAdditionalInfo": {
      "country": "Russian Federation",
      "city": "Moscow",
      "category": "Sport"
    },
    "title": "#123392 John"
  }
}

Управление диалогами¶

Назначение агента¶

Для назначения агента на чат с пользователем необходимо вызвать PUT /api/customers/{customerId}/agent, передавая данные авторизации в заголовке и данные агента в теле запроса.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя, с которым будет общаться агент. Можно получить из коллбэков. Path-параметр.
agentId	integer	ID агента.

Пример запроса¶

curl -X PUT "https://chat.devinotele.com/api/customers/137972/agent" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" \
  -H "Content-Type: application/json" -d "{ \"agentId\": 31642}"

Параметры ответа¶

Параметр	Тип данных	Описание
id	integer	ID пользователя, который можно получить из коллбэков.
externalId	string	ID пользователя из канала, который инициировал переписку.
creationDateTime	string	Дата создания пользователя.
channelProfileId	integer	ID канала чата.
additionalInfo	object	Дополнительная информация о пользователе, автоматически полученная через канал общения. В зависимости от канала общения, эта информация будет отличаться.
title	string	Заголовок диалога. Содержит ID пользователя.

Пример ответа¶

{
  "result": {
    "id": 137972,
    "externalId": "71112223344",
    "creationDateTime": "2023-10-24T11:06:54.609322",
    "channelProfileId": 10064,
    "additionalInfo": {
      "name": "abonent",
      "phone": "71112223344"
    },
    "title": "#137972 abonent"
  }
}

Назначение группы¶

Для назначения группы агентов на чат с пользователем необходимо вызвать PUT /api/customers/{customerId}/team, передавая данные авторизации в заголовке и данные группы в теле запроса.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя, с которым будет общаться агент из назначенной группы. Можно получить из коллбэков. Path-параметр.
teamId	integer	ID группы.

Пример запроса¶

curl -X PUT "https://chat.devinotele.com/api/customers/137972/agent" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" \
  -H "Content-Type: application/json" -d "{ \"teamId\": 31642}"

Параметры ответа¶

Параметр	Тип данных	Описание
id	integer	ID пользователя, который можно получить из коллбэков.
externalId	string	ID пользователя из канала, который инициировал переписку.
creationDateTime	string	Дата создания пользователя.
channelProfileId	integer	ID канала чата.
additionalInfo	object	Дополнительная информация о пользователе, автоматически полученная через канал общения. В зависимости от канала общения, эта информация будет отличаться.
title	string	Заголовок диалога. Содержит ID пользователя.

Пример ответа¶

{
  "result": {
    "id": 137972,
    "externalId": "71112223344",
    "creationDateTime": "2023-10-24T11:06:54.609322",
    "channelProfileId": 10064,
    "additionalInfo": {
      "name": "abonent",
      "phone": "71112223344"
    },
    "title": "#137972 abonent"
  }
}

Назначение тэгов¶

Для назначения тэгов на чат с пользователем необходимо вызвать PUT /api/customers/{customerId}/tag, передавая данные авторизации в заголовке и данные тэга в теле запроса.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя, на которого назначаются тэги. Можно получить из коллбэков. Path-параметр.
tagIds	array	Массив ID тэгов.

Пример запроса¶

curl -X PUT "https://chat.devinotele.com/api/customers/137972/tag" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" \
  -H "Content-Type: application/json" -d "{ \"tagIds\": [ 141, 167 ]}"

Параметры ответа¶

При успешной авторизации сервис возвращает параметр result в значении null и HTTP-статус 200.

Сбор счетчика непрочитанных сообщений¶

Для сброса счетчика непрочитанных сообщений в чате с пользователем необходимо вызвать PATCH /api/customers/{customerId}, передавая данные авторизации в заголовке.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя. Можно получить из коллбэков. Path-параметр.

Пример запроса¶

curl -X PATCH "https://chat.devinotele.com/api/customers/137972" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Параметры ответа¶

При успешной авторизации сервис возвращает параметр result в значении null и HTTP-статус 200.

Закрытие чата¶

Для закрытия чата с пользователем необходимо вызвать PUT /api/customers/{customerId}/conversation, передавая данные авторизации в заголовке.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя. Можно получить из коллбэков. Path-параметр.

Пример запроса¶

curl -X PUT "https://chat.devinotele.com/api/customers/137972/conversation" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Параметры ответа¶

При успешной авторизации сервис возвращает параметр result в значении null и HTTP-статус 200.

Отправка сообщений¶

Важно

На каждое отправленное и полученное сообщение бизнес-чат отправляет коллбэки по настроенному при интеграции URL-адресу. Для дополнительной информации обратитесь к менеджеру компании или в техническую поддержку.

Для отправки сообщения клиенту необходимо вызвать POST /api/message/send, передавая данные авторизации в заголовке и данные сообщения в теле запроса.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя, которому нужно отправить сообщение.
textAndAttachments	object	Данные текста и файлов, прикрепленных к сообщению.
businessChatSpecific	object	Объекты, принадлежащие бизнес-чату.

TextAndAttachments¶

Параметр	Тип данных	Описание
body	string	Текст сообщения.
attachmentIds	array[object]	ID файлов, прикрепленных к сообщению. Файлы загружаются через отдельный метод.

BusinessChatSpecific¶

Параметр	Тип данных	Описание
replies	array[object]	Объекты кнопок быстрого ответа на сообщение в чате.
buttons	array[object]	Объекты всех остальных кнопок (например, для текстовых команд или перехода по URL) в чате.

Replies¶

Параметр	Тип данных	Описание
text	string	Текст кнопки быстрого ответа.
rowIndex	integer	Порядковый номер ряда, в котором будет расположена кнопка быстрого ответа.
columnIndex	integer	Порядковый номер колонки, в которой будет расположена кнопка быстрого ответа.
type	string	Тип кнопки быстрого ответа. Возможное значение: ○ `post` - используется для кнопки без ссылки, которая отправляет текстовую команду в чат. ○ `external` - переход по ссылке по кнопке. Используется для каналов `VK` и `VIBER`. ○ `share_phone` - поделиться номером телефона. Используется для каналов `TELEGRAM` и `VIBER`.

Buttons¶

Параметр	Тип данных	Описание
text	string	Текст кнопки.
url	string	URL/deep link для перехода при нажатии на кнопку.
rowIndex	integer	Порядковый номер ряда, в котором будет расположена кнопка.
columnIndex	integer	Порядковый номер колонки, в которой будет расположена кнопка.
type	string	Тип кнопки. Возможные значения: ○ `post` - используется для кнопки без ссылки, которая отправляет текстовую команду в чат. ○ `external` - переход по ссылке по кнопке. Используется для каналов `VK` и `VIBER`. ○ `share_phone` - поделиться номером телефона. Используется для каналов `TELEGRAM` и `VIBER`.</p

Пример запроса¶

{
  "customerId": 103234,
  "textAndAttachments": {
    "attachmentIds": [
      "4b0589c8-b3f8-4da9-9637-94271bf3d8c2"
    ],
    "body": "Hello",
  "businessChatSpecific": {
    "buttons": [
        {
          "text": "Button",
          "url": "http://url.com",
          "rowIndex": 1,
          "columnIndex": 1,
          "type": "external"
        }
      ]
    }
  }
}

Параметры ответа¶

При успешной авторизации сервис возвращает параметр result в значении null и HTTP-статус 200.

Получение сообщений¶

Получение количества непрочитанных сообщений¶

Важно

На каждое отправленное и полученное сообщение бизнес-чат отправляет коллбэки по настроенному при интеграции URL-адресу. Для дополнительной информации обратитесь к менеджеру компании или в техническую поддержку.

Для получения количества непрочитанных сообщений во всех чатах с пользователями необходимо вызвать GET /api/extended-customers/unread_messages, передавая данные авторизации в заголовке.

Данный запрос не имеет дополнительных параметров.

Пример запроса¶

curl -X GET "https://chat.devinotele.com/api/extended-customers/unread_messages" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Параметры ответа¶

Параметр	Тип данных	Описание
id	integer	ID чата с пользователем, который совпадает с ID этого пользователя.
state	string	Статус чата с пользователем.
unreadMessagesCount	integer	Количество непрочитанных сообщений в диалоге.

Пример ответа¶

{
  "result": [
    {
      "id": 61716,
      "state": "NEW",
      "unreadMessagesCount": 1
    },
    {
      "id": 63677,
      "state": "NEW",
      "unreadMessagesCount": 1
    },
    {
      "id": 67425,
      "state": "NEW",
      "unreadMessagesCount": 1
    }
  ]
}

Получение всех сообщений в переписке¶

Важно

На каждое отправленное и полученное сообщение бизнес-чат отправляет коллбэки по настроенному при интеграции URL-адресу. Для дополнительной информации обратитесь к менеджеру компании или в техническую поддержку.

Для получения всех сообщений в чате с одним пользователем необходимо вызвать GET /api/customers/{customerId}/messages, передавая данные авторизации в заголовке.

Параметры запроса¶

Параметр	Тип данных	Описание
customerId	integer	ID пользователя. Можно получить из коллбэков. Path-параметр.

Пример запроса¶

curl -X GET "https://chat.devinotele.com/api/customers/137972/messages" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Параметры ответа¶

Параметр	Тип данных	Описание
id	integer	ID сообщения.
externalMessageId	string	ID пользователя из канала, который инициировал переписку.
conversationId	integer	ID чата с пользователем, который совпадает с ID этого пользователя.
agentId	integer	ID агента.
sendTime	string	Дата и время отправки сообщения.
direction	string	Тип сообщения по направлению: ○ `INCOMING` - входящее сообщение. ○ `OUTCOMING` - исходящее сообщение.
messageType	string	Тип сообщения по содержанию.
messageStatus	string	Статус сообщения.
textAndAttachments	object	Содержание сообщения.
messageInfo	object	Дополнительная информация о пользователе, которую можно добавить через отдельный метод.
reassignData	object	Данный параметр возвращается только если агент перенаправил чат на группу, и его взял другой агент. Объект содержит параметры нового агента.

TextAndAttachments¶

Параметр	Тип данных	Описание
body	string	Текст сообщения.
attachmentInfos	array[object]	Параметры файлов, прикрепленных к сообщению.

AttachmentInfo¶

Параметр	Тип данных	Описание
fileId	string	ID прикрепленного файла.
fileName	string	Название файла.
contentLength	string	Размер файла.
contentType	string	Тип файла.
publicUrl	string	Ссылка на файл, которая формируется при загрузке файла в чат.

ReassignData¶

Параметр	Тип данных	Описание
agentId	integer	ID агента, который взял чат с пользователем после первого агента.
state	string	Статус чата с пользователем.
date	string	Дата начала диалога с агентом, на которого перенаправили чат.

Пример ответа¶

{
  [
    {
      "id": "b33201af-7a95-4bc6-9ad7-d4f6f6bf8255",
      "externalMessageId": "3775657893675832064",
      "conversationId": 276909,
      "sendTime": "2023-10-24T10:56:44",
      "direction": "INCOMING",
      "messageType": "TEXT_AND_ATTACHMENTS",
      "messageStatus": "SEND",
      "textAndAttachments": {
        "body": "this is incoming message",
        "attachmentInfos": []
      },
      "messageInfo": {}
    },
    {
      "id": "6d805c25-1d27-4680-8360-c7b93a66fcc9",
      "externalMessageId": "1693320772815",
      "conversationId": 252284,
      "sendTime": "2023-08-29T14:52:52.815",
      "direction": "OUTCOMING",
      "agentId": "3",
      "messageType": "TEXT_AND_ATTACHMENTS",
      "messageStatus": "DELIVERED",
      "textAndAttachments": {
        "attachmentInfos": [
          {
            "fileId": "4b0589c8-b3f8-4da9-9637-94271bf3d8c2",
            "fileName": "44fd39f0-77d3-4c88-9583-4511c993c3f9.jpeg",
            "contentLength": "89021",
            "contentType": "image/jpeg",
            "publicUrl": "http://minio:9000/business-chat//businessChat/attachments/4b0589c8-b3f8-4da9-9637-94271bf3d8c2.jpeg"
          }
        ]
      },
      "messageInfo": {}
    },
    {
      "id": "7b9a2c09-cdbf-47b3-bc85-9ee8976f9384",
      "conversationId": 276909,
      "sendTime": "2023-10-31T06:32:52.355911",
      "direction": "INCOMING",
      "messageType": "CLOSE_SYSTEM_MESSAGE",
      "messageInfo": {},
      "reassignData": {
        "agentId": "31642",
        "state": "CLOSED_BY_AGENT",
        "date": "2023-10-31T06:32:52.293049"
      }
    }
  ]
}

Возможные статусы¶

Статусы чатов¶

Статус	Описание
`NEW`	Новый чат, агент еще не назначен.
`IN_PROGRESS`	Чат с пользователем открыт, идет диалог с агентом.
`CLOSED_BY_CUSTOMER`	Пользователь закрыл чат.
`CLOSED_AFTER_CHANNEL_PROFILE_CLOSE`	Чат закрыт автоматически при закрытии канала.
`CLOSED_BY_REASSIGNING`	Чат закрыт, агент перенаправил чат на группу.
`CLOSED_BY_AGENT`	Чат закрыт, диалог окончил агент.
`CLOSED_BY_TIMEOUT`	Чат закрыт, так как время диалога истекло.
`CSI`	Чат с пользователем открыт, идет опрос пользователя.
`CLOSED_BY_CSI`	Чат закрыт, опрос пользователя окончен.

Статусы сообщений¶

Статус	Описание
`SEND`	Сообщение отправлено в чат.
`DELIVERED`	Сообщение доставлено в чат.
`SEEN`	Пользователь прочитал сообщение.
`FAILED`	Ошибка доставки сообщения.

Типы сообщений¶

Тип	Описание
`TEXT_AND_ATTACHMENTS`	Текст и прикрепленные файлы.
`TEXT`	Сообщение, содержащее текст.
`ATTACHMENTS`	Сообщение в виде прикрепленных файлов.
`HINT`	Используется при автоответе.
`REASSIGN_SYSTEM_MESSAGE`	Системное сообщение: агент перенаправил чат на группу.
`CLOSE_SYSTEM_MESSAGE`	Системное сообщение: чат закрыт.
`UNSUPPORTED_CONTENT`	Контент сообщения не поддерживается.
`MESSAGE_STATUS_CHANGE`	Статус сообщения изменен.