Описание UseDesk API

Общее описание

API сервиса Usedesk, позволяет получить информацию о тикетах, клиентах, агентах, группах и дополнительных полях.
Формат возвращаемых данных: JSON.

Все запросы необходимо отправлять на URL: https://api.usedesk.ru/{method_name}
Например для метода /update/ticket URL для отправки запросов будет https://api.usedesk.ru/update/ticket

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

Генерация ключа

Для получения API ключа необходимо

1. Включить интеграцию API в разделе Интеграции: https://secure.usedesk.ru/settings/integration.

2. Затем перейдите в раздел Каналы https://secure.usedesk.ru/settings/channels и далее в блок «Настроить API».

3. Укажите «Название канала». Так будет называться ваш канал API.
Заполните поле «RedirectURL», на него будут приходить запросы, отмеченные чекбоксами ниже.

4. Скопируйте секретный ключ и используйте его в запросах к API.

Получить список тикетов

url: https://api.usedesk.ru/tickets

Метод возвращает тикеты компании. Возможно использование фильтров. Метод возвращает 100 записей, для смещения используется параметр offset.

Параметр Значение
fchannel Фильтр id канала
fassigned Фильтр id агента, на которого назначен тикет
fgroup Фильтр id группы, на которую назначен тикет
fstatus Фильтр id статуса
ftype Фильтр типа
fpriority Фильтр приоритета
offset Смещение
tag Строка тегов, через запятую
created_after В выдачу попадут тикеты, созданные после даты в параметре . Пример:'2016-11-25 00:00'
created_before В выдачу попадут тикеты, созданные до  даты в параметре . Пример:'2016-11-25 00:00'
updated_after В выдачу попадут тикеты, измененные после даты в параметре . Пример:'2016-11-25 00:00'
updated_before В выдачу попадут тикеты, измененные до  даты в параметре . Пример:'2016-11-25 00:00'
query Поисковая строка. Поиск осуществляется по теме тикета и содержанию во всех комментариях. Установлено ограничение на 10 запросов в минуту для запросов, содержащих, данный параметр.
field_id Идентификатор дополнительного поля, по которому будет осуществлен поиск
field_value

Значение дополниетельного поля, по которому будет осуществлен поиск. 

  • empty — для текстового и list поля по запросу отфильтровываются тикеты с незаполненным полем, для checkbox = false
  • not_empty для текстового и list полей — с заполненнными полями, для ckeckbox = true.
  • value — конкретное значение

Пример применения фильтров

     {
        'fchannel':'123',
        'fassigned': '45',
        'fgroup': '21',
        'ftype':'1'
        'updated_after':'2016-11-25 00:00';
      }

Пример запроса на php:

        try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'offset'=>0,
                'created_after' =>'2016-11-25 00:00',
                'created_before'=>'2016-11-25 15:08',
            );
            $mch_api = curl_init(); // initialize cURL connection

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/tickets');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

Пример запроса c фильтрами на php:

        try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                 'offset'=>0
                 'tags'=> 'тег1,тег2',
                 'fchannel'=>'123',
                  'fgroup'=>'2'

            );
            $mch_api = curl_init();

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/tickets');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

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

[
{
    "id": "2992803",
    "subject": "привет",
    "client_id": "15341",
    "assignee_id": "2",
    "channel_id": null,
    "group": "2",
    "last_updated_at": "2017-03-29 07:47:30",
    "channel_email": null,
    "ticket_fields": [
      {
        "id": "25",
        "name": "Жалоба",
        "value": null
      },
      {
        "id": "37",
        "name": "Причина обращений",
        "value": "39"
      }
    ],
    "tags": [
      {
        "name": "Причина обращений:ошибка"
      }
    ]
  },
]

Отдельный тикет

url: https://api.usedesk.ru/ticket

Метод возвращает информацию по тикету по его id. Принимает один параметр id тикета.

Параметр Значение
ticket_id id тикета

Пример запроса на php:


        try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'ticket_id'=>'2261648',

            );
            $mch_api = curl_init(); 

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/ticket');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

Сервер возвращает тикет, все комментарии, теги и историю изменений.

Пример ответа от сервера:

{
"ticket":{
"id":"2265179",
"status_id":"1",
"subject":"доп поля",
"client_id":"261702",
"assignee_id":"2",
"group":"0",
"last_updated_at":"2017-03-01 14:30:49",
"email":"0",
"published_at":"2017-03-01 14:30:49",
"company_id":"153561"
},
"comments":[
{
"id":"2658287",
"message":"доп поля",
"from":"client",
"user_id":null,
"client_id":"261702",
"ticket_id":"2265179",
"is_first":"0",
"delivered":"0",
"readed":"0",
"published_at":"2017-03-01 14:30:49"
}
],
"changes":[
{
"id":"213671",
"trigger_id":"1260",
"user_id":null,
"ticket_id":"2265179",
"data":[
{
"target":"assignee",
"value":"2"
}
],
"changed_at":"2017-03-01 14:30:49",
"old_status":"0",
"new_status":"0",
"company_id":"153561"
},
{
"id":"213669",
"trigger_id":null,
"user_id":null,
"ticket_id":"2265179",
"data":[
],
"changed_at":"2017-03-01 14:30:49",
"old_status":"0",
"new_status":"1",
"company_id":"153561"
}
],
"tags":[
"номер велосипеда:134",
"Овощи:помидорка"
],
"custom_fields":[
{
"id":"143",
"ticket_id":"2265179",
"ticket_field_id":"10",
"value":"134"
},
{
"id":"145",
"ticket_id":"2265179",
"ticket_field_id":"7",
"value":"1"
},
{
"id":"147",
"ticket_id":"2265179",
"ticket_field_id":"9",
"value":"9"
}
]
}

Создать тикет

url: https://api.usedesk.ru/create/ticket

Метод создает тикет для API канала. Принимает следующие параметры:

Параметр Значение
subject Тема тикета
message Сообщение тикета
client_name Имя клиента
client_email Почта клиента
client_id Не обязательный параметр, если  установлено "new_client", будет создан новый клиент
additional_id Не обязательный параметр, если нужно передать какой-либо дополнительный идентификатор
type

Принимает следующие параметры:

  • question
  • task
  • problem
  • incident
priority

Принимает следующие параметры:

  • low
  • medium
  • urgent
  • extreme
status

Принимает число, которое соответствует идентификатору статуса в системе.

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

  • 1 (открыт)
  • 2 (решен)
  • 3 (закрыт)
  • 4 (удален)
  • 5 (на удержании)
  • 6 (в ожидании)
  • 7 (спам)
  • 8 (новый)
  • 9 (рассылка)
tag Строка, которая содержит теги, разделенные запятыми.
assignee_id Идентификатор агента, на которого будет назначен запрос
group_id Идентификатор группы, на которую будет назначен запрос
client_phone В карточку клиента будет добавлен телефон, если клиент новый и передан данный параметр
field_id Строка, которая содержит идентификаторы дополнительных полей, разделенные точкой с запятой (;).
field_value

Строка, которая содержит значения дополнительных полей, разделенные точкой с запятой (;). 

Для текстовых полей значение не должно превышать 256 символов
Для чекбокс полей – true/false
Для лист полей — id варианта

channel_id Идентификатор канала, на котором будет создан запрос. Если не передан, запрос будет создан на канале, которому принадлежит токен. Тип запроса будет соответствовать типу канала


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

        {
         'subject': 'Письмо',
         'message': 'Привет!',
         'client_name': 'Иван',
         'client_email': 'superivan@gmail.com',
         'field_id': '10;12;9',
         'field_value': 'любое значение;true;93',
         'channel_id': 683
        }

Пример запроса на php:

try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'client_name' => "JON",
                'client_email' => "jon@bonjovi.com",
                'message' => "Hello World",
                'subject' => 'First msg',
                'client_id' => 'new_client',
                'type'  => 'question',
                'priority'  => 'low',
                'status'  => '3',
                'subject'  => 'POST UPDATE',
                'tag'=>'new ticket,test',
                'field_id'=> '10;12;9',
                'field_value'=> 'любое значение;true;93',
                'channel_id'=>683
            );
            $mch_api = curl_init(); // initialize cURL connection

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/create/ticket');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

При успешном запросе сервер вернет сообщение об успешном создании и id нового тикета.

Пример ответа от сервера:

 {"status":"success","ticket_id":2154861}

Обновить тикет

url: https://api.usedesk.ru/update/ticket

С помощью метода можно изменить существующий тикет. Принимает следующие параметры:

Параметр Значение
ticket_id id тикета
subject Тема тикета
message Сообщение тикета
client_id Id клиента, если установлен будет изменен клиент тикета,
group_id Id группы, на которую будет назначен тикет.
assignee_id Id юзера, который будет назначен исполнителем, если передан параметр group_id передавать не нужно
tag строка с тегами, через запятую  
priority приоритет, может содержать:  'low', 'medium', 'urgent', 'extreme'
status статус тикета, числовой параметр.  Возможные значения поля status:
Значение Статус
1 Открыт
2 Выполнен
3 Закрыт
4 Удален
5 В ожидании
6 На удержании
7 Спам
8 Новый
9 Рассылка
10 Объединен
type тип, может содержать : 'question', 'task', 'problem', 'incident'
field_id Строка, которая содержит идентификаторы дополнительных полей, разделенные точкой с запятой (;).
field_value

Строка, которая содержит значения дополнительных полей, разделенные точкой с запятой (;). 

Для текстовых полей значение не должно превышать 256 символов
Для чекбокс полей – true/false
Для лист полей — id варианта

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

     
   {
         'ticket_id': '123',
         'subject': 'Письмо',
         'message': 'Привет!',
         'client_name': 'Иван',
         'client_email': 'superivan@gmail.com',
         'field_id': '10;12;9',
         'field_value': 'любое значение;true;93'

        }

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

try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'client' => "JON",
                'email' => "jon@bonjovi.com",
                'message' => "Hello World",
                'subject' => 'First msg',
                'client_id' => 'new_client',
                'ticket_id'=>'2154827',
                'priority'  => 'medium',
                 'type'=>'task'
                'status'  => '2',
                'subject'  => 'POST UPDATE',
                'field_id'=> '10;12;9',
                'field_value'=> 'любое значение;true;93'
            );
            $mch_api = curl_init(); 

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/update/ticket');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

При успешном запросе сервер вернет сообщение об успешном создании и id тикета.

Пример ответа от сервера:

 {"status":"success","ticket_id":2154861}

Создать комментарий

url: https://api.usedesk.ru/create/comment

Метод создает комментарий внутри тикета. Принимает следующие параметры:

Параметр Значение
ticket_id id тикета
message Сообщение 
сс массив копий
bсс массив скрытых копий
user_id не обязательный параметр, если  установлено ответ будет совершен от данного юзера, иначе будет выбран первый пользователь компании
type тип комментария public/private, если не установлен комментарий будет приватным
files массив вложенных файлов. Формат: multipart/form-data
from параметр определяет автора комментария. Принимает "user", "client", "trigger". При передаче "client", автором комментария будет назначен клиент, на которого заведен тикетЕсли передается параметр отличный от "client", то в запросе должны содержаться параметры с нужными идентификаторами (user_idtrigger_id). 
trigger_id идентификатор триггера

Пример запроса на php:

 try{
            $data = array(
                'api_token'=> 'ba82c31d43b286e43e0e5489fb522ec57dc4c3fd',
                'message' => "New message text",
                'user_id'=>'545',
                 'ticket_id'=>'2152490',
                'type'  => 'public',
            );
            $mch_api = curl_init();

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/update/coment');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

При успешном запросе сервер вернет сообщение об успешном создании и id комментария.

Пример ответа от сервера:

 {"status":"success","comment_id":2154861}

Пример создания комментария с вложенным файлом:

  $file_name_with_full_path = realpath('../1480538622583f39fe53d18_logo.png');
  $cFile = curl_file_create($file_name_with_full_path);

Если запрос составляется через CURL важно указать полный путь до файла на сервере

  $file_name_with_full_path = realpath('../1480538622583f39fe53d18_logo.png');
            $cFile = curl_file_create($file_name_with_full_path);
            $data = array(
                'api_token'=> 'ba82c31d43b286e43e0e5489fb522ec57dc4c3fd',
                'message' => "New message text",
                'user_id'=>'545',
                'ticket_id'=>'2154814',
                'type'  => 'public',
                'files[]'=>$cFile
            );
            $mch_api = curl_init(); // initialize cURL connection

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/update/coment');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);

Получить список клиентов

url: https://api.usedesk.ru/clients

Метод возвращает клиентов компании. Метод возвращает 100 записей, для смещения используется параметр offset.

Параметр Значение
api_token токен
created_after в выдачу попадут клиенты, созданные после даты в параметре . Пример:'2016-11-25 00:00'
created_before в выдачу попадут клиенты, созданные до  даты в параметре . Пример:'2016-11-25 00:00'
offset смещение
query поисковая строка. Поиск осуществляется по имени, адресу, телефону клиента.

 

Пример запроса на php:

        
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'offset'=>0,
                'created_after' =>'2016-11-25 00:00',
                'created_before'=>'2016-11-25 15:08',
            );
            $mch_api = curl_init();
            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/clients');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);
            $result = curl_exec($mch_api);

Пример ответа от сервера:

 

[
{
"client":{
"id":35373,
"name":"Usedesk"
},
"emails":[
{
"id":33356,
"email":"support@usedesk.ru"
}
]
}
]

Отдельный клиент

url: https://api.usedesk.ru/client

Метод возвращает информацию о клиенте компании по id. Принимает один параметр- id клиента

Параметр Значение
client_id id тикета

Пример запроса на php:

            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'ticket_id'=>'2261648',
            );
            $mch_api = curl_init(); 

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/client');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);
            $result = curl_exec($mch_api);

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

[
{
"client":{
"id":35373,
"name":"Usedesk",
"avatar":null,
"position":null,
"note":null,
"company_id":153909,
"zendesk_id":null,
"spammer":0,
"vip":1,
"client_company_id":null,
"created_at":"2016-05-26 16:10:31",
"emails":[
{
"id":33356,
"email":"support@usedesk.ru",
"client_id":35373,
"fullcontact":0
}
]
},
"emails":[
null
]
}
]

Обновить клиента

url: https://api.usedesk.ru/update/clients

Метод позволяет редактировать информацию о клиенте.

Параметр Значение
api_token Токен
client_id Обязательный параметр. Идентификатор клиента
name Новое имя клиента
emails Массив с почтовыми адресами
note Текст заметки
is_new_note Если параметр установлен в false или отсутствует, позволяет продолжить текст заметки
phone Телефон пользователя
avatar Файл, содержащий, изображение. Формат: multipart/form-data
status Статус клиента - vip, spammer
merge_id Идентификатор клиента, с которым будет объединен пользователь с идентификатором client_id

 

Пример запроса на php:

        
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'client_id'=>1234,
                'name' =>'Jon',
                'emails'=>['test@gmail.com'],
            );
            $mch_api = curl_init();
            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/update/client');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);
            $result = curl_exec($mch_api);

Получить список тегов

url: https://api.usedesk.ru/tags

Метод возвращает список тегов компании.  Метод возвращает 100 записей, для смещения используется параметр offset.

api_token токен
offset смещение
query поисковая строка. Поиск осуществляется по тексту тега.

Пример запроса на php:

            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'offset'=>0,
            );
            $mch_api = curl_init(); // initialize cURL connection

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/tags');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);
            $result = curl_exec($mch_api);

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

[
{
"ticket_tag_id":130,
"tag_company_id":153909,
"name":"tag1",
"ticket_count":2
},
{
"ticket_tag_id":374,
"tag_company_id":153909,
"name":"example",
"ticket_count":25
}
]

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

url: https://api.usedesk.ru/users

Метод возвращает список агентов компании с группами. Возможно использование фильтров.

Параметр Значение
user_type

Тип или роль пользователя:

  • admin
  • employee
  • support
group_id id группы, а которой состоит агент
query строка, по которой осуществляется поиск
user_id id агента, если передано данное поле будет возвращена информация об одном агенте

Пример применения фильтров

     {
        'group_id':'123',
        'query': 'Ivan',
        'user_type': 'admin',
      }

Пример запроса на php:

        try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'group_id'=> 123,
                'query' =>'Ivan',
                'user_type'=>'admin',
            );
            $mch_api = curl_init(); // initialize cURL connection

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/users');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

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

[
  {
    "id": "558",
    "name": "Agent Name",
    "email": "agent@gmail.com",
    "position": "",
    "role": "admin",
    "phone": null,
    "groups": [
      {
        "id": "123",
        "name": "группа",
        "company_id": "153561",
        "deleted": "0",
        "deleted_at": "0000-00-00 00:00:00",
        "pivot": {
          "user_id": "558",
          "user_group_id": "413"
        }
      },
      {
        "id": "354",
        "name": "Группа 2",
        "company_id": "153561",
        "deleted": "0",
        "deleted_at": "0000-00-00 00:00:00",
        "pivot": {
          "user_id": "558",
          "user_group_id": "354"
        }
      },
      {
        "id": "127",
        "name": "Группа 4",
        "company_id": "153561",
        "deleted": "0",
        "deleted_at": "0000-00-00 00:00:00",
        "pivot": {
          "user_id": "558",
          "user_group_id": "127"
        }
      },
      {
        "id": "415",
        "name": "группа тест 3",
        "company_id": "153561",
        "deleted": "0",
        "deleted_at": "0000-00-00 00:00:00",
        "pivot": {
          "user_id": "558",
          "user_group_id": "415"
        }
      }
    ]
  }
]

Создать агента

url: https://api.usedesk.ru/create/user

Метод создает агента. Принимает следующие параметры:

Параметр Значение
name Обязательный параметр. Имя агента
email Обязательный параметр. Email агента
role

Строка вида:

  • admin
  • employee
  • support 

Если не передан, будет установлено значение по умолчанию - "employee"

password Пароль для входа
group Обязательный параметр. Группа по умолчанию, при создании агент будет добавлен в данную группу
phone Не обязательный параметр. Телефон агента


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

        {
         'name': 'Agent Name',
         'email': 'agentemail@gmail.com',
         'role': 'admin',
         'password': 'qwerty123',
         'group': '123',
         'phone': '89156743287',
        }

Пример запроса на php:

try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'name' => 'Agent Name',
                'email' => 'agentemail@gmail.com',
                'role' => 'admin',
                'password' => 'qwerty123',
                'group' => '123',
                'phone'  => '89156743287'
            );
            $mch_api = curl_init();
            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/create/user');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

При успешном запросе сервер вернет сообщение об успешном создании и id нового агента.

Пример ответа от сервера:

 {"status":"success","user_id":2154861}

Обновить агента

url: https://api.usedesk.ru/update/user

Метод создает агента. Принимает следующие параметры:

Параметр Значение
name Имя агента
email Email агента
role

Строка вида:

  • admin
  • employee
  • support 

 

group Группа по умолчанию
phone Телефон агента


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

        {
         'name': 'Agent Name',
         'email': 'agentemail@gmail.com',
         'role': 'admin'
         'group': '123',
         'phone': '89156743287',
        }

Пример запроса на php:

try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
                'name' => 'Agent Name',
                'email' => 'agentemail@gmail.com',
                'role' => 'admin',
                'group' => '123',
                'phone'  => '89156743287'
            );
            $mch_api = curl_init();
            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/update/user');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

Пример ответа от сервера:

 {"status":"success","user_id":2154861}

Получить список дополнительных полей

url: https://api.usedesk.ru/ticket/fields

Метод возвращает все дополнительные поля компании.

Пример запроса на php:

        try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
            );
            $mch_api = curl_init(); // initialize cURL connection

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/ticket/fields');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

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

[
{
"custom_field":{
"id":"1",
"company_id":"153561",
"ticket_field_type_id":"2",
"name":"Сложность",
"value":null,
"required":"1",
"add_tag":"1",
"add_filter":"1",
"sort":"0",
"active":"1",
"hidden":"0",
"api":"0",
"deleted":"0"
},
"field_options":[
{
"id":"1",
"ticket_field_id":"1",
"value":"Сложно"
},
{
"id":"2",
"ticket_field_id":"1",
"value":"Очень сложно"
},
{
"id":"3",
"ticket_field_id":"1",
"value":"Анриал"
}
]
}
]

Получить список групп агентов

url: https://api.usedesk.ru/groups

Метод возвращает список групп и агентов, состоящих в них.

Пример запроса на php:

        try{
            $data = array(
                'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
             
            );
            $mch_api = curl_init();

            curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/groups');
            curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
            curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
            curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
            curl_setopt($mch_api, CURLOPT_POST, true);
            curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);

            $result = curl_exec($mch_api);
            return $result;
        }
        catch(Exception $e){

        }

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

[
  {
    "id": "354",
    "name": "Группа 2",
    "company_id": "153561",
    "deleted": "0",
    "deleted_at": "0000-00-00 00:00:00",
    "users": [
      {
        "id": "568",
        "name": "agent1",
        "email": "agent1@usedesk.ru",
        "position": "",
        "role": "admin",
        "phone": null,
        "pivot": {
          "user_group_id": "354",
          "user_id": "568"
        }
      },
      {
        "id": "558",
        "name": "Agent2",
        "email": "agent2@gmail.com",
        "position": "",
        "role": "employee",
        "phone": null,
        "pivot": {
          "user_group_id": "354",
          "user_id": "558"
        }
      }
    ]
  },
]

Запросы от UseDesk (Webhooks)

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

Виды запросов:

  1. Создание тикета.
  2. Создания комментария.
  3. Изменение тикета.
  4. Оценка пользователя.

Примеры ответов от сервера.

Создание тикета:

{
"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
"ticket":{
"id":"2261907",
"status_id":"1",
"subject":"First msg",
"client_id":"242630",
"assignee_id":null,
"group":"0",
"last_updated_at":"2016-12-17 14:07:33",
"email":"jon@bonjovi.com",
"published_at":"2016-12-17 14:07:33",
"company_id":"153561",
"additional_id":123Ca344
}
}

Изменение тикета:

{
"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
"trigger":{
"id":"204232",
"trigger_id":null,
"user_id":"2",
"ticket_id":"2261907",
"data":[
{
"target":"subject",
"value":"POST UPDATE"
},
{
"target":"status_id",
"value":"2"
},
{
"target":"priority",
"value":"medium"
},
{
"target":"type",
"value":"task"
}
],
"changed_at":"2016-12-17 14:11:53",
"old_status":"1",
"new_status":"2",
"company_id":"153561"
}
}

Cоздание комментария:

{
"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
"comment":{
"id":"2652657",
"message":"New message text",
"from":"user",
"user_id":"545",
"client_id":null,
"ticket_id":"2261907",
"is_first":"0",
"delivered":"0",
"readed":"0",
"published_at":"2016-12-17 14:14:37"
}
}

Оценка:

{
"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
"csi":{
"id":"2652657",
"comment":"New message text",
"user_id":"545",
"client_id":123213,
"ticket_id":"2261907",
"rating":"3",
"created_at":"2016-12-17 14:14:37"
}
}

Справочник статусов

Возможные статусы в системе
Значение Статус
1 Открыт
2 Выполнен
3 Закрыт
4 Удален
5 В ожидании
6 На удержании
7 Спам
8 Новый
9 Рассылка
10 Объединен

Ошибки

Список ошибок:

Код Значение
111 server error, ошибка на сервере
112 invalid token, в запросе передан не правильный токен
113 invalid ticket_id, передан не верный Id тикета, либо отсутствует доступ для данной компании/токена
114 invalid message, не передан текст сообщения, либо текст не содержит символов
115 access error, ошибка доступа
116 tags must be a string, теги переданы в неверном формате
117 invalid user_id, не корректное значение id пользователя
118 invalid group_id не корректное значение id группы
119 invalid client_id, не корректное значение id клиента
120 file size is too large, размер файла превышает 15 мб
121 request limits, превышен лимит запросов

Дополнительные блоки

  1. Формат отправляемых данных: json
  2. Структура отправляемы данных:
    {
      "ticket_id": 2252750,
      "subject": "Hello!",
      "client_id": 151869,
      "channel_type": "email",
      "channel_id": 492,
      "from_email": test@gmail.ru,
      "client_data": {
        "name": "Иванов Иван",
        "emails": [
          "test@gmail.ru",
          "test_work@gmail.ru"
        ],
        "phones": [
          {
            "type": "home",
            "phone": "+1 111 111-11-11 #111"
          },
          {
            "type": "mobile",
            "phone": "+2 222 222-22-22 #222"
          }
        ],
        "social_services": [
          {
            "type": "facebook",
            "url": "https://facebook.com/123124124124124214",
            "uid": null
          }
        ],
        "addresses": [
          {
            "country": "Россия",
            "city": "Москва",
            "address": "улица 3, дом 4",
            "type": "home"
          }
        ],
        "messengers": [
          {
            "type": "telegram",
            "id": "1234"
          }
        ],
        "sites": [
          "http://site.ru"
        ],
        "company": "Ритм"
      }
    }
  3. Параметр Значение
    ticket_id id запроса в UseDesk
    subject тема запроса
    client_id id клиента в UseDesk
    channel_type тип канала, на который пришел запрос
    channel_id id канала в UseDesk
    from_email если запрос пришел из канала с типом email
    from_id id, если запрос пришел из другой системы
    client_data массив с имеющимися в UseDesk данными клиента
    Параметр Значение
    name имя клиента
    emails массив с электронными адресами клиента
    phones массив с телефонами клиента
    Параметр Значение
    type тип телефона ('home','mobile','stationary','fax','other')
    phone номер телефона
    social_services список аккаунтов клиента в соц.сетях
    Параметр Значение
    type вид соц.сети ('twitter','facebook','vk','ok','instagram','youtube','gplus','other')
    url адрес клиента в соц.сети
    addresses физические адреса клиента
    Параметр Значение
    country страна
    city город
    address адрес
    type тип ('home','work','postal')
    messengers мессенджеры клиента
    Параметр Значение
    type тип ('imessage','skype','whatsapp','gtalk','telegram','other','jivo')
    id  идентификатор клиента в мессенджере
    sites список сайтов клиент
    company компания клиента
  4. Формат ожидаемого ответа: json
  5. Структура ожидаемого ответа:

    "html": "Какой-то HTML"
    }
  6. Секретный ключ, если указан, добавляется в url запроса:  https://site.com/?secret_key=$key, где $key - секретный ключ
  7. По умолчанию ответ будет оформлен в соответствии со стилями UseDesk, есть поддержка bootstrap. Так же ответ может содержать свои стили, добавленные в html.
  8. Таймаут ответа — 60 секунд. Над каждым динамическим блоком есть кнопка "обновить", которая повторяет запрос и перезагружает данные в блок.

Вопросы?

Если у вас возникли вопросы по использованию API — пишите. Разберемся, поможем.

support@usedesk.ru