API V2 | Bot.one

Получение списка диалогов

GET /v2/conversations

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

Запросы

Query параметры

Название	Тип	Обязательный	Описание	Пример
BotID	integer	Нет	Идентификатор бота	1446
PageNumber	integer	Нет	Номер страницы	1
PageCount	integer	Нет	Количество записей на странице	20
CreatedTo	string	Нет	Окончание периода фильтрации по дате создания диалога. При необходимости можно указать время и часовой пояс. Формат - ISO 8601	2023-05-01
CreatedFrom	string	Нет	Начало периода фильтрации по дате создания диалога. При необходимости можно указать время и часовой пояс. Формат - ISO 8601	2023-05-29
UpdatedFrom	string	Нет	Начало периода фильтрации по дате последнего сообщения респондента в диалоге. При необходимости можно указать время и часовой пояс. Формат - ISO 8601	2023-05-20
UpdatedTo	string	Нет	Окончание периода фильтрации по дате последнего сообщения респондента в диалоге. При необходимости можно указать время и часовой пояс. Формат - ISO 8601	2023-05-29

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

curl --location --request GET 'https://manual.bot.one/api/v2/conversations?BotID=1446&CreatedFrom=2023-05-01&CreatedTo=2023-05-29' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByvLnRlY2g6Q2F2ZTIwMTY='

Ответ

Успешный ответ

200 - Успешное выполнение запроса. В ответе вернется список диалогов.

{
    "0": {
        "id": "7eea9bb4-0e47-441b-ad39-0b7715a6978f",
        "name": "#319 Perm",
        "status": "in-process",
        "ip": "92.255.128.210",
        "location": "Perm",
        "updated": "",
        "duration": 935037,
        "source": "web"
    },
    "1": {
        "id": "2368bb59-59e9-467d-91a5-44fdaba94f30",
        "name": "#318 Meppel",
        "status": "completed",
        "ip": "37.1.220.250",
        "location": "Meppel",
        "updated": "2023-05-11T08:25:26+00:00",
        "duration": 13,
        "source": "web"
    },
    "meta": {
        "pagination": {
            "total": 9,
            "count": 9,
            "per_page": 40,
            "current_page": 1,
            "total_pages": 1,
            "links": {}
        }
    }
}

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

Название	Описание
id	Идентификатор диалога
name	Название диалога (норма диалога + город, из которого начат)
status	Статус диалога
ip	IP-адрес пользователя, который начал диалог
location	Город, из которого начат
updated	Дата и время публикации последнего сообщения в диалоге в формате ISO
duration	Длительность диалога в секундах
source	Cервис, гдe был начат диалог

Коды ошибок

Код ошибки	Наименование	Описание
400	Bad Request	Убедитесь, что все параметры запроса имеют нужный формат
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.

Получение данных диалога

GET /v2/conversation/{uuid}

Запрос позволяет получить данные диалога по его идентификатору.

Запрос

Параметры пути

Название	Тип	Обязательный	Описание	Пример
uuid	string	Да	Уникальный идентификатор диалога	f8d5a184-37dc-4055-9b4a-49c34903e813

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

curl --location --request GET 'https://manual.bot.one/api/v2/conversation/f8d5a184-37dc-4055-9b4a-49c34903e813' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByvLnRlY2g6Q2F2ZTIwMTY='

Ответ

Успешный ответ

200 - Успешное выполнение запроса. В ответе вернется объект с данными диалога.

{
  "id": "f8d5a184-37dc-4055-9b4a-49c34903e813",
  "name": "#108 Perm",
  "status": "in-process",
  "ip": "127.0.0.1",
  "location": "Perm",
  "updated": "2022-10-14T07:14:09+00:00",
  "duration": 20,
  "source": "web",
  "data": "[]"
}

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

Название	Описание
id	Идентификатор диалога
name	Название диалога (норма диалога + город, из которого начат)
status	Статус диалога
ip	IP-адрес пользователя, который начал диалог
location	Город, из которого начат
updated	Дата и время публикации последнего сообщения в диалоге в формате ISO
duration	Длительность диалога в секундах
source	Cервис, гдe был начат диалог
data	Возвращается массив данных, собранных в диалоге (ответы на вопросы бота, загруженные файлы, выполненые запросы и пр.)

Коды ошибок

Код ошибки	Наименование	Описание
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.
404	Not Found	Объект не найден. Проверьте, правильно ли указаны значения параметров

Создание нового диалога

GET /v2/dialog/{BotID}/create

Запрос позволяет создать новый диалог по идентификатору бота. Диалог будет создан, но не начат — то есть бот не будет публиковать сообщения.

Запрос

Параметры пути

Название	Тип	Обязательный	Описание	Пример
BotID	integer	Да	Идентификатор бота	1446

Query параметры

Название	Тип	Обязательный	Описание	Пример
variables	string	Нет	Переменные, которые можно передать в диалог (например, имя респондента, номер договора и пр)	{"name":"Dasha"}

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

curl --location -g --request GET 'https://manual.bot.one/api/v2/dialog/1446/create?variables={"name":"Dasha"}' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByvLnRlY2g6Q2F2ZTIwMTY='

Ответ

Успешный ответ

200 - Успешное выполнение запроса — возвращается уникальный идентификатор (uuid) созданного диалога.

{
    "dialogId": "ef313216-e8d9-46a9-b95e-8060058bd43f"
}

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

Название	Описание
dialogId	Уникальный идентификатор созданного диалога

Коды ошибок

Код ошибки	Наименование	Описание
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.
404	Not Found	Объект не найден. Проверьте, правильно ли указаны значения параметров

Получение файла

GET /v1/file/{fileId}

Запрос позволяет получить файл по идентификатору.

Запрос

Параметры пути

Название	Тип	Обязательный	Описание	Пример
fileId	integer	Да	Идентификатор файла	123

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

curl --location --request GET 'test.beta.bot.one/api/v1/file/123' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByYXZvLnRlY2g6Q2F2ZTIwMTY='

Ответ

Успешный ответ

200 - Успешное выполнение запроса — возвращается файл, идентификатор которого был указан в запросe.

Коды ошибок

Код ошибки	Наименование	Описание
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.
404	Not Found	Объект не найден. Проверьте, правильно ли указаны значения параметров

Создание и запуск нового диалога

POST /v2/dialog/{BotID}/create

Запрос позволяет создать новый диалог по идентификатору бота и запустить его. То есть бот сразу начнет публиковать сообщения в диалоге. Вы можете указать переменные для передачи их в диалог.

Запрос

Параметры пути

Название	Тип	Обязательный	Описание	Пример
BotID	integer	Да	Идентификатор бота	1446

Query параметры

Название	Тип	Обязательный	Описание	Пример
response	boolean	Нет	'true' — в ответе вернется идентификатор созданного диалога, 'false' — в ответе не будет возвращаться идентификатор созданного диалога	true
variables	string	Нет	Переменные, которые можно передать в диалог (например, имя респондента, номер договора и прочее)	{"name":"Dasha"}

Тело запроса

В теле запроса вы можете указать:

variables — переменные для передачи их в диалог;
response — получать в ответе id и uuid созданного диалога (true) или нет (false).

{
    "response": true,
    "variables": "{ \"name\": \"User\" }"
}

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

curl --location -g --request POST 'https://manual.bot.one/api/v2/dialog/1446/create?variables={"name":"Dasha"}&response=true' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByvLnRlY2g6Q2F2ZTIwMTY=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "response": true,
    "variables": "{ \"name\": \"User\" }"
}'

Ответ

Успешный ответ

200 - Успешное выполнение запроса. Если в теле запроса вы передали параметр 'response': true, в ответе вернется идентификатор (id) и уникальный идентификатор (uuid) созданного диалога.

{
    "dialogId": 371,
    "dialogUUID": "4c9b89a3-0fbc-4b01-9d9b-63a7b1ca4ffa"
}

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

Название	Описание
dialogId	Идентификатор созданного диалога
dialogUUID	Уникальный идентификатор созданного диалога

Коды ошибок

Код ошибки	Наименование	Описание
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.
404	Not Found	Объект не найден. Проверьте, правильно ли указаны значения параметров

Возобновление диалога

POST /v2/conversation/{uuid}/start

Запрос позволяет возобновить диалог и перевести его в статус 'В процессе'.

Запрос

Параметры пути

Название	Тип	Обязательный	Описание	Пример
uuid	string	Да	Уникальный идентификатор диалога	42c8c8fb-357a-4795-b39c-cc9af1c8a82b

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

curl --location --request POST 'https://manual.bot.one/api/v2/conversation/ef313216-e8d9-46a9-b95e-8060058bd43f/start' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByvLnRlY2g6Q2F2ZTIwMTY='

Ответ

Успешный ответ

204 - Успешное выполнение запроса. Диалог был продолжен и получил статус 'В процессе'.

Коды ошибок

Код ошибки	Наименование	Описание
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.
404	Not Found	Объект не найден. Проверьте, правильно ли указаны значения параметров

Остановка диалога и перевод на оператора

POST /v2/conversation/{uuid}/stop

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

Запрос

Параметры пути

Название	Тип	Обязательный	Описание	Пример
uuid	string	Да	Уникальный идентификатор диалога	ef313216-e8d9-46a9-b95e-8060058bd43f

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

curl --location --request POST 'https://manual.bot.one/api/v2/conversation/ef313216-e8d9-46a9-b95e-8060058bd43f/stop' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByvLnRlY2g6Q2F2ZTIwMTY='

Ответ

Успешный ответ

204 - Успешное выполнение запроса. Диалог был остановлен и получил статус 'Оператор'.

Диалог остановлен и получил статус Оператор

Коды ошибок

Код ошибки	Наименование	Описание
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.
404	Not Found	Объект не найден. Проверьте, правильно ли указаны значения параметров

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

POST /v2/conversation/{uuid}/send

Запрос позволяет отправить сообщение от лица оператора в конкретный диалог.

Запрос

Параметры пути

Название	Тип	Обязательный	Описание	Пример
uuid	string	Да	Уникальный идентификатор диалога	ef313216-e8d9-46a9-b95e-8060058bd43f

Тело запроса

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

{
  "body": "Привет, я оператор."
}

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

Название	Описание
body	Сообщение, которое было отправлено в диалог

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

curl --location --request POST 'https://manual.bot.one/api/v2/conversation/ef313216-e8d9-46a9-b95e-8060058bd43f/send' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByYXZvLnRlY2g6Q2F2ZTIwMTY=' \
--header 'Content-Type: application/json' \
--data-raw '{
  "body": "Привет, я оператор."
}'

Ответ

Успешный ответ

204 - Успешное выполнение запроса. Сообщение отправлено в диалог.

Коды ошибок

Код ошибки	Наименование	Описание
400	Bad Request	Убедитесь, что все параметры запроса имеют нужный формат
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.
404	Not Found	Объект не найден. Проверьте, правильно ли указаны значения параметров

Перевод диалога на другого бота

POST /v2/conversation/{uuid}/command

Запрос позволяет перевести диалог на другой бот.

Запрос

Параметры пути

Название	Тип	Обязательный	Описание	Пример
uuid	string	Да	Уникальный идентификатор диалога	ef313216-e8d9-46a9-b95e-8060058bd43f

Тело запроса

В теле запроса нужно прописать команду (goto) и идентификатор бота. Обязательный параметр.

{
  "body": "goto 698"
}

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

curl --location --request POST 'https://manual.bot.one/api/v2/conversation/ef313216-e8d9-46a9-b95e-8060058bd43f/command' \
--header 'Authorization: Basic ZC5keW1icnlsb3ZhQHByvLnRlY2g6Q2F2ZTIwMTY=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "body": "goto 698"
}'

Ответ

Успешный ответ

200 - Успешное выполнение запроса.

{
    "message": "Goto command complete"
}

Коды ошибок

Код ошибки	Наименование	Описание
400	Bad Request	Убедитесь, что все параметры запроса имеют нужный формат
401	Unauthorized	Проверьте логин и пароль для авторизации в системе
403	Forbidden	Проблема с подключением к инстансу или диалогу. Это может быть связано с невалидным токеном, блокировкой инстанса, остановкой сервиса, удалением или завершением диалога и пр.
404	Not Found	Объект не найден. Проверьте, правильно ли указаны значения параметров