Тикеты

Created by Василий

Внимание

Если вы используете коробочную версию Юздеска на собственном сервере, то URL методов у вас будет отличаться. Уточните URL для работы с API у поддержки — support@usedesk.ru.

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

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

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

Список тикетов

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

Ограничения: 

70 запросов в минуту с одного IP адреса.

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

Некоторые параметры не принимают значение null

* обязательные поля 

ПараметрЗначение
api_token*Токен api канала
fchannel

Фильтрация по id канала. Несколько значений передавайте через запятую

fassigned

Фильтрация по assignee_id и group_id, значения которых можно передать массивом или по одному.

Существуют следующие кейсы поведения:

  1. Возможность указать в параметре assignee_id айди агента и в параметре group_id айди группы - тогда система отдает все тикеты, в которых в качестве Исполнителя указан агент в рамках определенной группы
  2. Возможность не указывать параметр group_id и указать в параметре assignee_id айди агента - тогда система отдает все тикеты, в которых в качестве Исполнителя указан агент, без учета в рамках какой группы он добавлен
  3. Возможность указывать параметр assignee_id = unassinged – тогда система отдает все тикеты, в которых в качестве Исполнителя указана группа
  4. Возможность указывать параметр assignee_id = unassinged и указать в параметре group_id = unassinged – тогда система отдает все тикеты, в которых в качестве Исполнителя указано "Нет исполнителя"

Deprecated (версия 1.0) не рекомендуем использовать устаревшие способы поведения:

  1. Возможность указать строкой id агента
  2. Возможность указать id группы+id агента для уточнения в рамках какой группы указан исполнитель: {ID группы}_{ID агента}
fgroupФильтрация по id группы
fstatus

Фильтрация по id статуса

  • 1 (открыт)
  • 2 (выполнен)
  • 3 (закрыт)
  • 4 (удален)
  • 5 (на удержании)
  • 6 (в ожидании)
  • 7 (спам)
  • 8 (новый)
  • 9 (рассылка)
ftype

Фильтрация по типу

  • question
  • task
  • problem
  • incident
fpriority

Фильтрация по приоритету

  • low
  • medium
  • urgent
  • extreme
accessible_for_agent_id

Фильтрация по id агента, учитывает права сотрудника.

Сервер возвращает переменную rights:

  • write - если есть доступ работы с тикетом в текущем канале;
  • read - если есть доступ просмотра тикета в текущем канале.

не принимает значение null

offsetСмещение. 

Смещение на 1, покажет следующие 100 записей

не принимает значение null

tag

Фильтрация по значению тега. Если значений несколько передавать значения необходимо через запятую c пробелом:

"tag" : "1,4,23"

не принимает значение null

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 запросов в минуту для запросов, содержащих, данный параметр.

не принимает значение null

client_idId клиента, если указать система пришлет список тикетов конкретного клиента
fields

Фильтрация по идентификатору и значению дополнительного поля. 

Массив содержит параметры:

  • id - айди дополнительного поля;
  • value - значение дополнительного поля

а) empty - при указании данного значения система отфильтрует все запросы, в которых есть хотя бы одно не заполненное поле. Для полей с типом checkbox "не заполнено" это значение - 0 или пустое значение " "

b) not_empty - при указании данного значения система отфильтрует все запросы, в которых есть хотя бы одно заполненное поле. Для полей с типом checkbox "заполнено" это значение - 1

c) value - при указании значения система отфильтрует все запросы, в которых в любом из дополнительных полей будет выбрано данное значение. Можно указать только одно значение

Deprecated (версия 1.0) не рекомендуем использовать устаревшие способы поведения:

field_id – Фильтрация по идентификатору дополнительного поля. При указании значения система отфильтрует все запросы, в которых данное поле будет заполнено. Можно указать только одно значение.

field_value – Фильтрация по значению дополнительного поля. 

  • empty - при указании данного значения система отфильтрует все запросы, в которых есть хотя бы одно не заполненное поле
    • Для полей с типом checkbox "не заполнено" это значение - false
  • not_empty - при указании данного значения система отфильтрует все запросы, в которых есть хотя бы одно заполненное поле.
    • Для полей с типом checkbox "заполнено" это значение - true
  • value - при указании значения система отфильтрует все запросы, в которых в любом из дополнительных полей будет выбрано данное значение.
    • Можно указать только одно значение
sort

Параметр сортировки, по которому можно сортировать список тикетов: id, status_id, client_id, assignee_id, group, last_updated_at, published_at

По умолчанию: id

order

Порядок сортировки тикетов:

  • asc - по возрастанию
  • desc - по убыванию

По умолчанию: desc

properties

передает в ответ от сервера дату и время SLA по каждому параметру, если они заданы в запросах:

  • время первого ответа (first_reply)
  • время следующего ответа (next_reply)​
  • время до выполнения​ (close)


Пример применения фильтров
{
	'fchannel':'123',
    'properties': ["sla"]
    'fassigned': 
    [
       {
            'assignee_id' : 17063,
            'group_id' : 6216
       },
       {
            'assignee_id' : 15023,
            'group_id' : 8294
       } 
    ]
    'fields': 
    [
        {'id': 4704,
         'value": 1
        },
        {'id': 2410,
         'value": 'empty'
        },
        {'id': 3570,
         'value": 'test'
        },
        {'id': 4267,
         'value': 'empty'
        }
    'fgroup': '21',
    'ftype':'1',
    'accessible_for_agent_id':'6339',
    'updated_after':'2016-11-25 00:00'
}


Пример запроса на 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(); // 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;


Пример запроса c фильтрами на php:
$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;
Пример ответа от сервера
[
	{
    	"id": 2992803,
    	"subject": "привет",
    	"client_id": 15341,
		"client_name": "Лащук Василий",
    	"assignee_id": 2,
    	"channel_id": null,
    	"group": 2,
        "created_at": "2019-05-16 11:31:23"
    	"last_updated_at": "2017-03-29 07:47:30",
    	"channel_email": null,
        "active_sla": [
            {
            "type": "close",
            "date": "2021-04-29 10:35:04"
            },
            {
            "type": "first_reply",
            "date": "2021-04-28 18:01:08"
            }
        ],
        	"ticket_fields": [
			{
        		"id": 25,
        		"name": "Жалоба",
        		"value": null
			},
      		{
        		"id": 37,
        		"name": "Причина обращений",
        		"value": "39"
			}
    	],
    	"tags": [
			{
        		"name": "Важный"
			},
			{
        		"name": "Холодный"
			}
		],
        "status": 2,
        "priority": "medium",
        "type": "question",
        "last_comment": "У меня появилась ошибка",
        "remind_at": null,
        "rights": "read"
	},
]

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

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

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

* обязательные поля 

ПараметрЗначение
api_token*Токен api канала
ticket_id*id тикета
accessible_for_agent_id

Фильтрация по id агента, учитывает права сотрудника.

Сервер возвращает переменную rights:

  • write - если есть доступ работы с тикетом в текущем канале;
  • read - если есть доступ просмотра тикета в текущем канале.
properties

передает в ответ от сервера дату и время SLA по каждому параметру, если они заданы в запросах:

  • время первого ответа (first_reply)
  • время следующего ответа (next_reply)​
  • время до выполнения​ (close)

Пример запроса
$data = array(
		'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
		'accessible_for_agent_id'=>'6339',
        '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;

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

Пример ответа от сервера
{
	"ticket":{
		"id": 2265179,
		"status_id": 1,
		"priority": "medium",
		"type": "problem",
		"subject": "Ошибка с доп полями",
		"client_id": 261702,
		"assignee_id": 2,
		"group": 0,
		"last_updated_at": "2017-03-01 14:30:49",
		"email": "vlasch@gmail.com",
		"published_at": "2017-03-01 14:30:49",
		"company_id": 153561,
    	"channel_id": 22
    	"additional_id": "32"
		"client_name": "Лащук Василий",
        "active_sla": [
            {
            "type": "close",
            "date": "2021-04-29 10:35:04"
            },
            {
            "type": "first_reply",
            "date": "2021-04-28 18:01:08"
            }
         ],
	    "comments":[
		   {
			"id": 2658287,
			"message": "доп поля",
			"from": "client",
            "type": "public",
			"user_id": null,
			"client_id": 261702,
			"client_name": "Василий Лащук",
			"ticket_id": 2265179,
			"is_first": 0,
			"delivered": 0,
			"readed": 0,
			"published_at": "2017-03-01 14:30:49",
			"file": 129169,
			"files": [
				{
                    "name": "44029855d283e98131fc.jpg",
                    "type": "image/jpeg",
                    "file": "https://devsecure.usedesk.ru/files/153561/3403684/get-url-comment-files/YmxwdGVHcFRkMVp4VjFoNFVVcEZVVEY2YzA4elp6MDlPanEybDlWVkhNNU1vTS8zWWliNzZqeEY="
 				}
			]
            "bcc": [
			        "shy@usedesk.ru",
                    "test@usedesk.ru"
			]
            "cc": [
                    "shy123@usedesk.ru",
                    "test123@usedesk.ru"
			]
		}
	],
	"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": 2,
			"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": [
		"Важный",
		"Холодный лид"
	],
	"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"
		}
	]
            "rights": "write",
}

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

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

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

* обязательные поля 

ПараметрЗначение
api_token*Токен api канала
subject*Тема тикета. Строка (255 символов). Поддерживаются любые символы, в том числе эмодзи
message*

Сообщение тикета. Строка ~64kb. Поддерживается HTML разметка

  • Если это внутренний комментарий (private_comment = true), то можете добавить упоминание сотрудника [~test@gmail.com]
client_nameИмя клиента. Строка (255 символов)
client_emailПочта клиента. Строка (255 символов)
client_idНеобязательный параметр, если  установлено "new_client", будет создан новый клиент. Числовой идентификатор либо строка "new_client" для нового клиента
company_name

Необязательный параметр, если указан, то система проверит нет ли компании с таким именем

Если такой компании нет - создается новая компания с таким именем и привязывается к клиенту по которому пришло обращение

Если такая компания есть - клиент привязывается к этой компании

Если у клиента есть компания - клиент перепривязывается к той что была передана

private_comment

true. Необязательный параметр для создания приватного комментария. 

additional_id

Системное поле которое не видно в карточке. Отдается в запросах получения информации о тикете.

Необязательный параметр

Строка (255 символов)

type

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

  • question
  • task
  • problem
  • incident

По умолчанию: question

Строка (10 символов)

priority

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

  • low
  • medium
  • urgent
  • extreme

По умолчанию: medium

Строка (10 символов)

status

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

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

  • 1 (открыт)
  • 2 (выполнен)
  • 3 (закрыт)
  • 4 (удален)
  • 5 (на удержании)
  • 6 (в ожидании)
  • 7 (спам)
  • 8 (новый)
  • 9 (рассылка)
  • 10 (объединен)

По умолчанию: 8 (новый)

Числовое значение 

tag

Строка, которая содержит теги, разделенные запятыми с пробелом.

assignee_id

Идентификатор агента, на которого будет назначен запрос в рамках группы по умолчанию.

  • если передан параметр group_id и агент есть в этой группе, то назначение будет в рамках указанной группы
  • если был указан неверный id система не очистит поле, а вернет ошибку

Числовой идентификатор. 32 бита.

group_id

Идентификатор группы, на которую будет назначен запрос. Числовой идентификатор. 32 бита

client_phoneВ карточку клиента будет добавлен телефон, если клиент новый и передан данный параметр. Строка (255 символов)
field_idСтрока, которая содержит идентификаторы дополнительных полей, разделенные точкой с запятой (;). Строка (255 символов)
field_value

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

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

Пример строки в которой передаются 3 значения:  'любое значение;true;93',

channel_idИдентификатор канала, на котором будет создан запрос. Если не передан, запрос будет создан на канале, которому принадлежит токен. Тип запроса будет соответствовать типу канала. 32 бита.
filesМассив вложенных файлов. Формат: multipart/form-data
fromПараметр определяет автора комментария. Принимает "user","client", "trigger". При передаче "client", автором комментария будет назначен клиент, на которого заведен тикет. Если передается параметр отличный от "client", то в запросе должны содержаться параметры с нужными идентификаторами (user_id, trigger_id). 
user_idИдентификатор агента для параметра from
trigger_idИдентификатор правила для параметра from
client_countryСтрана клиента
client_cityГород клиента
client_addressАдрес клиента
new_addressПередается, если требуется создать дополнительный адрес. 
phone_typeТип телефона при сохранении. Принимает значения  home,mobile,stationary,fax,other
lists

Для редактирования вложенных списков. Массив содержащий параметры:

  • id - айди поля
  • value - значение поля

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

Пример запроса
{
	'subject': 'Письмо',
	'message': 'Привет!',
	'client_name': 'Иван',
	'client_email': 'superivan@gmail.com',
	'field_id': '10;12;9',
	'field_value': 'любое значение;true;93',
	'channel_id': 683,
	'lists':[
		[
			{
				"id":"61",
				"value":"Тест"
			},
			{
				"id":"62",
				"value":"Тест1"
			},
			{
				"id":"63",
				"value":"Тест2"
			}
		]
	]
}
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.usedesk.ru/create/ticket',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('files[]'=> new CURLFILE('/Users/ylia.kh/Downloads/IMG_20201109_140523.jpg'),'api_token' => 'ed22e2c09c1567629ea2a912907e60c6027ddf5d','message' => 'Юлечка','subject' => 'Вложения тестим'),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: multipart/form-data',
    'Cookie: laravel_session=8dIFarAWQMZlGKACtWX2A1KIQ5rlysgpCh9aMJmZ'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
Пример запроса на PHP
$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;

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

Пример ответа от сервера
{
	"status": "success",
	"ticket_id": 2154861
}

Пример запроса для отправки сообщения в канал WhatsApp

Чтобы клиент получил сообщение в WhatsApp, учитывайте обязательные параметры from и user_id.

Новый клиент в системе создается, если:

  • 'client_id' => 'new_client' или не используется вовсе;
  • 'client_phone'=> '79254697403' и его нет в системе

К текущему клиенту добавляется новый номер телефона, если:

  • 'client_id' => '27747627';
  • 'client_phone'=> '79254697403' и его нет в системе

К текущему клиенту НЕ добавляется новый номер, если:

  • 'client_id' => '27747627' или не используется вовсе;
  • 'client_phone'=> '79254697403' и уже есть в системе

Если использовать только параметр client_id, то сообщение будет отправлено на первый номер телефона, указанный в системе.

Пример запроса
    'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
	'message' => "Hello",
	'subject' => 'First msg',
	'channel_id' => '20054',
	'from'=>'user',
	'user_id'=> '2156',
	'client_phone'=> '79254697403',
	'client_id'=>'27747627'

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

Пример ответа от сервера
{
    "status": "success",
    "ticket_id": 30745888,
    "message_status": "delivered"
}

Для проверки статуса отправки сообщения в WhatsApp будет отправлен запрос на вебхук. Для этого в API-канале Юздеска укажите адрес на который отправится запрос

Пример отправляемого запроса на вебхук
{ "message_status": {"delivery_status": "DELIVERED", "comment_id": 3551632, "extras": {"ticket_id": 1231234}}}

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

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

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

* обязательные поля 

ПараметрЗначение
api_token*Токен api канала
ticket_id*id тикета
subjectТема тикета
client_idId клиента, если установлен будет изменен клиент тикета,
group_id

Id группы, на которую будет назначен тикет

assignee_id

Id юзера, который будет назначен исполнителем

  • если передан параметр group_id и агент есть в этой группе, то назначение будет в рамках указанной группы
  • если был указан неверный id система не очистит поле, а вернет ошибку
  • если в group_id  и assignee_id передан "null", назначение будет "Не назначено"
user_idId юзера от лица которого будут произведены изменения
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 варианта или значение поля

lists

Для редактирования вложенных списков. Массив содержащий параметры:

  • id - айди поля
  • value - значение поля

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

Для очистки поля используйте пустое значение или "null"

Пример запроса
{
	'ticket_id': '123',
	'subject': 'Письмо',
	'field_id': '10;12;9',
	'field_value': 'любое значение;true;93',
	'lists': [
		[ 
			{
				"id": 1347,
				"value": "1"
			}, 
			{
				"id": 1348,
				"value": "22"
			}
 		]
 	]
}
Пример запроса на PHP
$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;

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

Пример ответа от сервера
{
	"status":"success"
}

Асинхронное создание тикета

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

Метод асинхронного создания тикета. Информация о созданном тикете приходит на webhook, заданный в API канале. Принимает следующие параметры:

* обязательные поля

ПараметрЗначение
api_token*Токен api канала
subject*Тема тикета. Строка (255 символов). Поддерживаются любые символы, в том числе эмодзи
message*Сообщение тикета. Строка ~64kb. Поддерживается HTML разметка
client_nameИмя клиента. Строка (255 символов)
client_emailПочта клиента. Строка (255 символов)
client_idНеобязательный параметр, если  установлено "new_client", будет создан новый клиент. Числовой идентификатор либо строка "new_client" для нового клиента
additional_id

Системное поле которое не видно в карточке. Отдается в запросах получения информации о тикете.

Необязательный параметр

Строка (255 символов)

type

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

  • question
  • task
  • problem
  • incident

По умолчанию: question

Строка (10 символов)

priority

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

  • low
  • medium
  • urgent
  • extreme

По умолчанию: medium

Строка (10 символов)

status

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

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

  • 1 (открыт)
  • 2 (выполнен)
  • 3 (закрыт)
  • 4 (удален)
  • 5 (на удержании)
  • 6 (в ожидании)
  • 7 (спам)
  • 8 (новый)
  • 9 (рассылка)
  • 10 (объединен)

По умолчанию: 8 (новый)

Числовое значение 

tagСтрока, которая содержит теги, разделенные запятыми.
assignee_idИдентификатор агента, на которого будет назначен запрос. Числовой идентификатор. 32 бита
group_idИдентификатор группы, на которую будет назначен запрос. Числовой идентификатор. 32 бита
client_phoneВ карточку клиента будет добавлен телефон, если клиент новый и передан данный параметр. Строка (255 символов)
field_idСтрока, которая содержит идентификаторы дополнительных полей, разделенные точкой с запятой (;). Строка (255 символов)
field_value

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

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

Пример строки в которой передаются 3 значения:  'любое значение;true;93',

channel_idИдентификатор канала, на котором будет создан запрос. Если не передан, запрос будет создан на канале, которому принадлежит токен. Тип запроса будет соответствовать типу канала. 32 бита.
filesМассив вложенных файлов. Формат: multipart/form-data
Пример запроса
{
	'subject': 'Письмо',
	'message': 'Привет!',
	'client_name': 'Иван',
	'client_email': 'superivan@gmail.com',
	'field_id': '10;12;9',
	'field_value': 'любое значение;true;93',
	'channel_id': 683
}
Пример запроса на PHP
$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;
Пример ответа от сервера
{
	"status":"success"
}

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

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

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

* обязательные поля 

ПараметрЗначение
api_token*Токен api канала
ticket_id*id тикета
message*

Сообщение 

  • Если это внутренний комментарий, то можете добавить упоминание сотрудника [~test@gmail.com]
ссМассив копий
bссМассив скрытых копий
user_idНеобязательный параметр, если  установлено ответ будет совершен от данного юзера, иначе будет выбран первый пользователь компании
typeТип комментария public/private, если не установлен комментарий будет приватным
filesМассив вложенных файлов. Формат: multipart/form-data
from

Параметр определяет автора комментария. Принимает "user","client", "trigger". При передаче "client", автором комментария будет назначен клиент, на которого заведен тикет. Если передается параметр отличный от "client", то в запросе должны содержаться параметры с нужными идентификаторами (user_id, trigger_id). 

Если user_id не указан, то комментарий будет создан от лица бота

trigger_id

Идентификатор триггера.

ВАЖНО: В данный момент вне зависимости от того какой выбран триггер - комментарий будет создан от лица Бота

Пример запроса
{
	"api_token": "ed22e2c09c1567629ea2a912907e60c6027ddf58",
	"ticket_id": "37344609",
	"message": "комментарий",
    "type": "public",
    "bcc": [
                "random@e.mail",
                "random2@e.mail",
                "random3@e.mail"
            ],
    "cc": [
                "random4@e.mail",
                "random5@e.mail",
                "random6@e.mail"
            ]
}
Пример запроса на PHP
$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/create/comment');
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;

При успешном запросе сервер вернет сообщение об успешном создании и 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 важно указать полный путь до файла на сервере

Пример запроса на PHP
$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/create/comment');
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;

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

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

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

* обязательные поля 

api_token*Токен api канала
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);
return $result;
Пример ответа от сервера
[
	{
		"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
	}
]