Запросы

Created by Василий
Last updated: Sep 14, 2022 by Ничволод Антон

Внимание

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

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

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

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

Список запросов

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

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

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

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

ПараметрОписание
api_token*Токен API канала
fchannel

Фильтрация по id канала

Можно передать несколько значений через запятую

fassigned

Фильтрация по assignee_id (id исполнителя) и group_id (id группы агентов). 

Можно передать как по одному, так и массивом.

Возможные варианты использования:

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

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

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

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

ftype

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

  • question — вопрос
  • task — задача
  • problem — проблема
  • incident — инцидент
fpriority

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

  • low — низкий
  • medium — средний
  • urgent — высокий
  • extreme — экстремальный 
accessible_for_agent_id

Фильтрация по id агента

Учитывает права сотрудника. Не принимает значение null.

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

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

Смещение

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

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

tag

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

Можно передать несколько значений через запятую с пробелом. Не принимает значение null

Пример использования: 

"tag": "тег1, тег2, тег3"

created_after

Фильтрация по дате и времени создания

В выдачу попадут запросы, созданные после указанной даты (включительно)

Пример использования:

"created_after": "2022-01-01 00:00"

created_before

Фильтрация по дате и времени создания

В выдачу попадут запросы, созданные до указанной даты (включительно)

Пример использования:

"created_before": "2022-12-31 23:59"

updated_after

Фильтрация по дате и времени изменения

В выдачу попадут запросы, измененные после указанной даты (включительно)

Пример использования:

"updated_after": "2022-01-01 00:00"

updated_before

Фильтрация по дате и времени изменения

В выдачу попадут запросы, измененные до указанной даты (включительно)

Пример использования:

"updated_before": "2022-01-01 00:00"

query

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

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

Для запросов, содержащих, данный параметр, установлено ограничение на 10 запросов в минуту 

client_id

Фильтрация по id клиента

fields

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

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

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

Дополнительные варианты использования:

  • empty — при указании данного значения система отфильтрует все запросы, в которых есть хотя бы одно не заполненное поле.
    Для полей с типом checkbox "не заполнено" — это значение  "0" или пустое значение " ";
  • not_empty — при указании данного значения система отфильтрует все запросы, в которых есть хотя бы одно заполненное поле.
    Для полей с типом checkbox "заполнено" это значение - "1";
  • 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

"properties": ["sla"]

Возможные параметры в ответе:

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

Если SLA не заданы в запросе, то SLA не возвращается в ответе


Пример применения фильтров
{
	"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"
	},
]

Отдельный запрос

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

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

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

ПараметрОписание
api_token*Токен API канала
ticket_id*Идентификатор запроса
accessible_for_agent_id

Фильтрация по id агента

Учитывает права сотрудника.

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

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

Передача времени до наступления SLA

"properties": ["sla"]

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

Если SLA не заданы в запросе, то SLA не возвращается в ответе


Пример запроса
$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",
}

Создать запрос

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

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

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

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

Тема запроса

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

Поддерживаются любые символы, в том числе эмодзи

message*

Сообщение в запросе

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

Если это внутренний комментарий private_comment = true, то можете добавить упоминание сотрудника: [~test@gmail.com]

client_name

Имя клиента

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

client_email

Почта клиента

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

client_id

Идентификатор клиента

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

Числовой идентификатор или строка "new_client" для создания нового клиента

company_name

Имя компании

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

Если указано, то система проверит наличие компании с таким именем.

  • Компания не найдена — создается новая компания с таким именем. Эта компания привязывается к клиенту, от которого пришло обращение;
  • Компания найдена — клиент привязывается к найденой компании.

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

private_comment

Создание первого комментарий приватным

Принимает только значение true

additional_id

Системное поле, которое не видно в карточке

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

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

type

Тип запроса

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

Возможные значения:

  • question — вопрос;
  • task — задача;
  • problem — проблема;
  • incident — инцидент.

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

priority

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

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

Возможные значения:

  • low — низкий;
  • medium — средний;
  • urgent — высокий;
  • extreme — экстремальный. 

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

status

Статус запроса

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

Возможные значения указаны тут.

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

tag

Теги

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

assignee_id

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

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

  • если передан параметр group_id и агент есть в этой группе, то назначение будет в рамках указанной группы;
  • если был указан неверный id система не очистит поле, а вернет ошибку.
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 — правило.

Если передается параметр user или trigger, то в запросе должны содержаться параметры с нужными идентификаторами — user_id или trigger_id соответственно

user_id

Идентификатор агента для параметра from

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

trigger_id

Идентификатор правила для параметра from

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

client_country

Страна клиента

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

client_city

Город клиента

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

client_address

Адрес клиента

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

new_addressПередается, если требуется создать дополнительный адрес
phone_type

Тип телефона при сохранении

Возможные значения:

  • home
  • mobile
  • stationary
  • fax
  • other
lists

Редактирование вложенных списков

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

  • id — id поля;
  • value — значение поля.

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

template_id

Идентификатор шаблона WhatsApp Business (pact)

template_name
Название шаблона WhatsApp Business (Landbot, infobip)
template_variables

Переменные шаблона WhatsApp Business

Массив строк. Переменные подставляются в шаблон по порядку

template_lang

Язык шаблона WhatsApp Business

Значение по умолчанию: ru

Пример запроса
{
	'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"79123456789" и его нет в системе


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

ПараметрЗначение
client_idУказан id клиента: "27747627"
client_phone"79123456789" и его нет в системе


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

ПараметрЗначение
client_idУказан id клиента: "27747627"
client_phone"79123456789" и уже есть в системе


Если использовать только параметр 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"
}


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

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

Отправка шаблона WhatsApp Business

Для того, чтобы начать диалог с отправки шаблона, нужно передать в параметрах запроса к API данные шаблона:

Пример запроса для отправки шаблона WhatsApp Business (pact)
{
	"api_token": "aff11f252956fcb0248f3a55cc92eb1234567890",
	"channel_id": 123,
	"from": "user",
	"client_phone": "79511234567",
	"template_id": 8094,
	"template_variables": ["Иван","18:00","Маяковская"]
}
Пример запроса для отправки шаблона WhatsApp Business (Landbot, infobip)
{
	"api_token": "aff11f252956fcb0248f3a55cc92eb1234567890",
	"channel_id": 123,
	"from": "user",
	"client_phone": "79511234567",
	"template_name": "Main",
	"template_variables": ["Валерий"]
}


Пример запроса для отправки сообщения в канал Viber (c2d)

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

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

"new_client" или не используется вовсе

client_phone"79123456789" и его нет в системе


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

ПараметрЗначение
client_idУказан id клиента: "27747627"
client_phone"79123456789" и его нет в системе


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

ПараметрЗначение
client_idУказан id клиента: "27747627"
client_phone"79123456789" и уже есть в системе


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


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

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

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

Пример запроса для отправки сообщения в канал Telegram personal (pact)

Для отправки сообщения нужно использовать client_phone, если сообщение нужно отправить по номеру телефона или username, если нужно отправить сообщение по нику.

При отправке сообщения по нику можно использовать два формата написания — "ivanov" и "@ivanov"

Если указаны и username, и client_phone, то сообщение отправится по username.


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

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

"new_client" или не используется вовсе

client_phone"79123456789" и его нет в системе

Или:

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

"new_client" или не используется вовсе

username"ivanov" и его нет в системе


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

ПараметрЗначение
client_idУказан id клиента: "27747627"
client_phone"79123456789" и его нет в системе


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

ПараметрЗначение
client_idУказан id клиента: "27747627"
username"ivanov" и его нет в системе


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

ПараметрЗначение
client_idУказан id клиента: "27747627"
client_phone"79123456789" и уже есть в системе


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

ПараметрЗначение
client_idУказан id клиента: "27747627"
username"ivanov" и уже есть в системе

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

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

Обновить запрос

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

С помощью метода можно изменить существующий запрос

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

ПараметрЗначение
api_token*Токен API канала
ticket_id*id запроса
subjectТема запроса
client_id

id клиента

Если установлен, то запрос привяжется к указанному клиенту

group_id

id группы

Если указан, то запрос будет назначен на указанную группу

assignee_id

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

Варианты использования:

  • Передан group_id и агент есть в этой группе — назначение будет в рамках указанной группы
  • Указан неверный id  — система вернет ошибку
  • если в group_id и assignee_id передан null — назначение будет "Не назначено"
user_idid юзера от лица которого будут произведены изменения
tag

Теги

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

priority

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

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

Возможные значения:

  • low — низкий;
  • medium — средний;
  • urgent — высокий;
  • extreme — экстремальный. 

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

status

Статус запроса

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

Возможные значения указаны тут

type

Тип запроса

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

Возможные значения:

  • question — вопрос;
  • task — задача;
  • problem — проблема;
  • incident — инцидент.
field_id

Строка, которая содержит идентификаторы дополнительных полей

Строка (255 символов), разделяются точкой с запятой (;)

field_value

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

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

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

lists

Редактирование вложенных списков

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

  • id — 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"
}

Асинхронное создание запроса

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

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

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

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

Тема запроса

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

Поддерживаются любые символы, в том числе эмодзи

message*

Сообщение запроса

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

Если это внутренний комментарий private_comment = true, то можете добавить упоминание сотрудника: [~test@gmail.com]

client_name

Имя клиента

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

client_email

Почта клиента

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

client_id

Идентификатор клиента

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

Числовой идентификатор или строка "new_client" для создания нового клиента

additional_id

Системное поле, которое не видно в карточке

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

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

type

Тип запроса

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

Возможные значения:

  • question — вопрос;
  • task — задача;
  • problem — проблема;
  • incident — инцидент.

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

priority

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

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

Возможные значения:

  • low — низкий;
  • medium — средний;
  • urgent — высокий;
  • extreme — экстремальный. 

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

status

Статус запроса

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

Возможные значения указаны тут.

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

tag

Теги

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

assignee_id

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

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

  • если передан параметр group_id и агент есть в этой группе, то назначение будет в рамках указанной группы;
  • если был указан неверный id система не очистит поле, а вернет ошибку.
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"
}

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

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

Метод создает комментарий внутри запроса

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

ПараметрЗначение
api_token*Токен API канала
ticket_id*id запроса
message*

Сообщение 

Если это внутренний комментарий private_comment = true, то можете добавить упоминание сотрудника: [~test@gmail.com]

ссМассив копий
bссМассив скрытых копий
user_id

id юзера от лица которого будут произведены изменения

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

type

Тип комментария

  • public — публичный;
  • private — приватный.

Если не установлен, то комментарий будет приватным

files

Массив вложенных файлов

multipart/form-data

from

Сторона, от лица которой создается комментарий

Возможные значения:

  • user — агент;
  • client — клиент;
  • trigger — правило.

Если передается параметр user или trigger, то в запросе должны содержаться параметры с нужными идентификаторами — user_id или trigger_id соответственно

trigger_id

Идентификатор правила для параметра from

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

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

template_id


Идентификатор шаблона WhatsApp Business (pact)
template_nameНазвание шаблона WhatsApp Business (Landbot, infobip)
template_variables

Переменные шаблона WhatsApp Business

Массив строк. Переменные подставляются в шаблон по порядку

template_lang

Язык шаблона WhatsApp Business

Значение по умолчанию: ru

Пример запроса
{
	"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;

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

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

Метод возвращает список тегов.

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

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

api_token*Токен API канала
offset

Смещение

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

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

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
	}
]