Через API можно осуществлять управление системой, а также получать доступ к NLU, если вам необходимо подключать свой текстовый канал к ZIAX.
Метод работы с NLU:
Данный метод позволяет отправлять конкретному агенту текст от пользователя и получать в ответе текст, который нужно вернуть человеку, а также извлеченные параметры, которые подверглись нормализации. Текст ответа будет возвращен от агента из вкладки API в ответной фразе интента.
URL для запроса(Метод POST):
https://example.ru/channel/api/{id_agent}
Вместо example.ru используйте ваше доменное имя или IP адрес.
{id_agent} - идентификатор агента. Его можно посмотреть либо в адресной строке, либо в настройках агента.
Формат запросов:
Headers:
Сontent-type: text/json
Authorization: {API KEY}
{API KEY} - Ключ авторизации агента. Его можно найти в настроках агента в разделе ZIAXFLOW (см. скриншот)
Тело запроса:
{"speech":"ТЕКСТ ПОЛЬЗОВАТЕЛЯ","session_id":"УНИКАЛЬНЫЙ ID СЕССИИ","time_zone":"+3"}
Ответ:
{"sessionId":"УНИКАЛЬНЫЙ ID СЕССИИ",
"speech":"ОТВЕТНАЯ ФРАЗА РОБОТА",
"parameters":{
"date":"16.01.2020",
"date.original":"16.01.2020",
"date.receive":"16.01.2020",
}
}
В случае, если во время диалога параметры не были извлечены, значение parameters остается пустым.
Методы API личного кабинета:
С помощью данных методов можно управлять настройками личного кабинета и совершать действия от пользователя личного кабинета. Доступ осуществляется на основании прав пользователей. У каждого пользователя есть свой ключ для доступа к АПИ, который можно посмотреть в настройках пользователя.
URL для API версия 1:
https://example.ru/userapi/v1/
Авторизация:
Можно добавлять ключ пользователя в хедер, либо в GET параметр.
Пример ключа в Хедере:
“Authorization: Bearer YOUR_API_TOKEN_HERE”
Пример ключа в GET параметре:
curl -k https://example.ru/userapi/v1/test?api_token=YOUR_API_TOKEN_HERE
МЕТОД -> ПРОВЕРКА КЛЮЧА АВТОРИЗАЦИИ:
Метод: GET
URL: /userapi/v1/test
CURL пример:
curl -k https://ipaddr/userapi/v1/test?api_token=YOUR_API_TOKEN_HERE
ОТВЕТ:
Auth successful. Email: test@test.ru
МЕТОД -> СОЗДАНИЕ ЗАДАНИЯ АВТОИНФОРМИРОВАНИЯ:
Метод: POST
Обязательный хедер: "Content-Type: application/json"
URL: /userapi/v1/autocall/create
CURL пример:
curl -k -X POST -H "Content-Type: application/json" https://ipaddr/userapi/v1/autocall/create?api_token=YOUR_API_TOKEN_HERE
ТЕЛО ЗАПРОСА:
{
"numbers": [
{
"num": "79990000000",
"timezone": "+3",
"fio": "роман",
"id_client": "CL66575675",
"tag1": "tag1",
"tag6": "tag6",
"tag15": "tag15"
},
{
"num": "79993331177"
}
],
"settings": {
"name": "test",
"sip": "1",
"bot_id": "9",
"autostart": "0",
"all_time": "0",
"time": {
"Monday": {
"start": "09:00",
"end": "20:00"
},
"Tuesday": {
"start": "09:00",
"end": "20:00"
}
},
"lines": "6",
"attempts": "6",
"interval": "60"
}
}
В параметре “numbers” у каждого обязательный параметр - “num”. Если не указан “timezone”, то подставляется “+3”, если не указан “id_client”, то в качестве “id_client” проставляется номер клиента. Должен быть хотя бы 1 номер, все необязательные поля могут отсутствовать, тогда они не добавятся в задачу на прозвон. Поля tag1 - tag15 могут присутствовать, максимальное количество “tagN” - 15 (начинается с 1)
В параметре "settings" обязательные параметры все, кроме "time", если параметр "all_time" = “1”
autostart - если указать “1”, то задание сразу запустится, если “0”, то присвоится статус “Создано”
all_time - если стоит “1”, то звонки будут идти в любое время, если “0”, то необходимо обязательно указывать параметр time, где мы задаем интервалы, в которые можно звонить.
sip - ID SIP учетной записи для исходящих звонков
id_client - если он не указан то подставляется номер телефона
bot_id - ID внешнего канала из меню “ВНЕШНИЕ КАНАЛЫ”, необходимо указывать тот внешний канал, который обрабатывает voip канал.
ОТВЕТ:
{
"status": "success",
"id_job": "87",
}
МЕТОД -> ЗАПРОС СТАТУСА И НАСТРОЕК ЗАДАНИЯ АВТОИНФОРМИРОВАНИЯ:
Метод: GET
URL: /userapi/v1/autocall/{id_job}
CURL пример:
curl -k https://ipaddr/userapi/v1/autocall/14?api_token=YOUR_API_TOKEN_HERE
id_job - ID задания
ОТВЕТ:
{"status":"success",
"data":{
"id":14,
"settings":{"name":"test",
"sip":1,
"bot_id":9,
"status":2,
"time":{
"Monday":{"start":"00:00","end":"23:59","check":"on"},
"Tuesday":{"start":"00:00","end":"23:59","check":"on"},
"Wednesday":{"start":"00:00","end":"23:59","check":"on"},
"Thursday":{"start":"00:00","end":"23:59","check":"on"},
"Friday":{"start":"00:00","end":"23:59","check":"on"},
"Saturday":{"start":"00:00","end":"23:59","check":"on"},
"Sunday":{"start":"00:00","end":"23:59","check":"on"}},
"lines":6,
"attempts":6,
"interval":60
}
}
}
МЕТОД -> ЗАПРОС СТАТУСА КЛИЕНТА В ЗАДАНИИ АВТОИНФОРМИРОВАНИЯ:
Метод: GET
URL: /userapi/v1/autocall/{id_job}/{id_client}
CURL пример:
curl -k https://ipaddr/userapi/v1/autocall/5/79998883322?api_token=YOUR_API_TOKEN_HERE
id_job - ID задания
id_client - ID клиента
ОТВЕТ:
{"status":"success",
"data":{
"job_id":15,
"timezone":"+3",
"fio":"",
"id_client":"79998883322",
"next_call_date":"1970-01-01 00:00:00",
"attempts":0,
"status":0,
"busy":0
}
}
МЕТОД -> ОТПРАВКА ИСХОДЯЩЕГО ТЕКСТОВОГО СООБЩЕНИЯ:
Этот метод используется для того, чтобы отправлять исходящие сообщения в текстовых каналах
Метод: POST
URL: /userapi/v1/bot/message
CURL пример:
curl -i -X POST \
-H "Content-Type:application/json" \
-H "Authorization:Bearer your_user_api_key_here" \
-d \
'{"channel_id":"30","user_id":"123123123","text":"тестовое сообщение"}'
'https://example.ru/userapi/v1/bot/message'
channel_id - ID канала
user_id - ID пользователя телеграм (в системе Ziax user_id можно найти в истории агента в созданном чате бота и нужного пользователя)
ОТВЕТ:
{"status":"success"
}
МЕТОД -> СКАЧИВАНИЕ АУДИОЗАПИСИ ПО ID ДИАЛОГА
Этот метод используется для того, чтобы скачать аудиозапись разговора с роботом. Если авторизация пройдена успешно и файл существует, то сразу начнется скачивание
Метод: GET
URL: /userapi/v1/get_record_voip
Пример URL для скачивания файла:
https://example.ru/userapi/v1/get_record_voip?api_token=token_example&chat_id=1665998272.2
api_token - токен пользователя системы который имеет доступ к агенту запись разговора которого мы собираемся скачивать
chat_id - ID диалога
id_job -> settings -> status - 1-создано, 2-запущено, 3-остановлено, 4- закончено
МЕТОД -> ЗАПРОС ВНЕШНИХ КАНАЛОВ:
Метод: GET
URL: /userapi/v1/bot/
CURL пример:
curl -k https://ipaddr/userapi/v1/bot/?api_token=YOUR_API_TOKEN_HERE
ОТВЕТ:
{"status":"success",
"data":[
{"id":9,"name":"bot 1","channel":0},
{"id":11,"name":"bot 2","channel":5},
{"id":12,"name":"bot 3","channel":4},
{"id":13,"name":"bot 4","channel":9}
]
}
id - ID внешнего канала в системе
name - название внешнего канала в системе
channel - ID типа внешнего канала
СПИСОК ID ВНЕШНИХ КАНАЛОВ:
1 - Telegram
2 - Api
3 - Vk
4 - Viber
5 - Яндекс Алиса
6 - WebWidget
7 - LiveTex
8 - Webim
9 - RTU-Text
10 - VoIP
МЕТОД -> ЗАПРОС ВНЕШНИХ КАНАЛОВ ПО ТИПУ КАНАЛА:
Метод: GET
URL: /userapi/v1/bot/{channel}
CURL пример:
curl -k https://ipaddr/userapi/v1/bot/1?api_token=YOUR_API_TOKEN_HERE
ОТВЕТ:
{"status":"success",
"data":[
{"id":9,"name":"bot 1","channel":1}
]
}
Следует учесть, что при запросе API выводится список всех каналов, т.к. API имеет доступ на любой внешний канал
next_call_date - время следующего звонка
status - статус звонка, совершенного по указанному номеру: 0-не было звонка, 1-не успешно, 2-успешно, 3-не звонить
attempts - количество совершенных попыток дозвона
busy - совершается ли звонок по этому номеру в данный момент: 0-нет, 1-идет
МЕТОД -> ЗАПРОС SIP АККАУНТОВ:
Метод: GET
URL: /userapi/v1/sip/
CURL пример:
curl -k https://ipaddr/userapi/v1/sip/?api_token=YOUR_API_TOKEN_HERE
ОТВЕТ:
{"status":"success",
"data":[
{"id":1,"name":"221"}
]
}
МЕТОД -> ЗАПРОС СПИСКА ДИАЛОГОВ В ИСТОРИИ АГЕНТА:
Метод: POST
URL: /userapi/v1/history/search
CURL пример:
curl -i -X POST \
-H "Authorization:Bearer YOUR_API_TOKEN_HERE" \
-H "Content-Type:application/json" \
-d \
'{"agent_id":3, "from":"2020-12-10 00:00:00", "to":"2020-12-23 23:59:59"}' \
'https://ipaddr/userapi/v1/history/search'
ПАРАМЕТРЫ ЗАПРОСА
agent_id - идентификатор агента
from - дата и время начала диалога
to - дата и время окончания диалога
ОТВЕТ:
{
"status":"success",
"data":[
{
"chat_id":"1608629540.2",
"date_time":"22.12.2020 12:32:22",
"phone":"205",
"duration":86,
"redirect":""
"successfully": 1,
"status": "success"
},
{
"chat_id":"1608629588.8",
"date_time":"23.12.2020 12:00:00",
"phone":"205",
"duration":8,
"redirect":"201"
"successfully": 0,
"status": "интент не найден"
}
]
}
ПАРАМЕТРЫ ОТВЕТА
date_time - дата и время начала диалога
phone - номер клиента, если есть
duration - продолжительность диалога, если есть
redirect - перевод звонка, если есть
successfully - успешность диалога, 0 - неуспешный, 1 - успешный
status - ошибки в диалоге, success - ошибок не было или будет написано название ошибки
МЕТОД -> ЗАПРОС ДИАЛОГА В ИСТОРИИ АГЕНТА:
Метод: POST
URL: /userapi/v1/history/show
CURL пример:
curl -i -X POST \
-H "Authorization:Bearer YOUR_API_TOKEN_HERE" \
-H "Content-Type:application/json" \
-d \
'{"chat_id":"1608629540.2"}' \
'https://ipaddr/userapi/v1/history/show'
ПАРАМЕТРЫ ЗАПРОСА
chat_id - идентификатор диалога. Если в ID есть символ "\", то его нужно обязательно отправлять в экранированном виде.
ОТВЕТ:
{
"status": "success",
"data": {
"date_time": "05.08.2022 07:11:28",
"phone": "205",
"duration": 25,
"redirect": "301",
"successfully": 0,
"status": "success",
"history": [
{
"datetime": "05.08.2022 07:11:28",
"user": "start",
"intent_id": null,
"intent_name": ""
},
{
"datetime": "05.08.2022 07:11:28",
"agent": "Скажи 123. твой номер 205.",
"intent_id": 3317,
"intent_name": "Default Welcome Intent"
},
{
"datetime": "05.08.2022 07:11:37",
"user": "123",
"intent_id": null,
"intent_name": ""
},
{
"datetime": "05.08.2022 07:11:37",
"agent": "скажи еще раз 123",
"intent_id": 3319,
"intent_name": "123 START"
},
{
"datetime": "05.08.2022 07:11:43",
"user": "123",
"intent_id": null,
"intent_name": ""
},
{
"datetime": "05.08.2022 07:11:43",
"agent": "контекст 123",
"intent_id": 3321,
"intent_name": "контекст 123"
},
{
"datetime": "05.08.2022 07:11:52",
"user": "Оператора",
"intent_id": null,
"intent_name": ""
},
{
"datetime": "05.08.2022 07:11:52",
"agent": "оператор",
"intent_id": 3322,
"intent_name": "оператор"
}
],
}
}
ПАРАМЕТРЫ ОТВЕТА
date_time - дата и время начала диалога
user - текст сообщения от человека
agent - текст ответа от агента
phone - номер клиента, если есть
duration - продолжительность диалога, если есть
redirect - перевод звонка, если есть
successfully - успешность диалога (0-неудачный; 1-успешный)
status - ошибка распознавания
intent_id - ID интента
intent_name - название интента
