Категории

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

Содержание


Создание запроса

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

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

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

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

Параметр Значение
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"

}


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

Парметр Описание
status Статус выполнения запроса
  • success — успешный запрос
  • failed — неуспешный запрос
comment_id ID комментария