Create a ticket

Creating a ticket

POST https://secure.usedesk.com/uapi/create/ticket

Warning. If you use the server version of Usedesk, you will have a different URL of methods. Check the URL for the API with our team — support@usedesk.com.

The method creates a ticket. It accepts the following parameters:

* — required fields

Parameter	Value
api_token*	Channel API token
subject*	Subject of the ticket String (255 characters) Any characters are possible, including emoji
message*	Message String, ~64kb. Supports HTML markup If this is an internal comment private_comment = true, you can add a mention of agent [~test@gmail.com]
client_name	Client name String (255 characters)
client_email	Client email String (255 characters)
client_id	Client ID String (255 characters) Numeric identifier or string "new_client" to create a new client
company_name	Client company name String (255 characters) If specified, the system will check for a company with that name. The company is not found — we will create a new company with specified name. This company will be linked to the client from whom ticket came; Company found — the client will be attached to the found company. If the customer already has a company listed, it is reassigned to a company that has been transferred
private_comment	Create the first comment private Only accepts true
additional_id	System field that is not visible in Web interface String (255 characters) Shown only in API requests for information about the ticket
type	Ticket type String (10 characters) Possible values: question; task; problem; incident. By default: question
priority	Ticket priority String (10 characters) Possible values: low; medium; urgent; extreme. By default: medium
status	Ticket status Accepts a number that corresponds to the status identifier in the system. Possible values are indicated here. By default: 8 (new)
tag	Tags String (255 characters), which contains tags separated by commas and spaces
assignee_id	ID of the agent to which the request will be assigned within the default group Numeric ID, 32 bit if the group_id parameter is given and the agent is in this group, the assignment will be within the specified group; if an invalid ID was specified, the system will not clear the field, but will return an error.
group_id	ID of the group to which the request will be assigned Numeric ID, 32 bit
client_phone	Client phone String (255 characters) Will be added if the client is new
field_id	A string that contains the identifiers of additional fields String (255 characters), separated by a semicolon (;).
field_value	A string that contains the values of additional fields, separated by semicolons (;) For text fields the value should not exceed 255 characters For checkbox fields – true/false For the list fields – variant ID Example of a string that passes 3 values: 'anyvalue;true;93',
channel_id	ID of the channel in which the ticket will be created Numeric ID, 32 bit If not specified, or specified incorrectly, the ticket will be created in the channel to which the token belongs. The request type will correspond to the channel type
files	An array of attached files multipart/form-data
from	The side on whose behalf the first comment is created Possible values: user; client; trigger. If a user or trigger parameter is passed, the request must contain parameters with the desired identifiers — user_id or trigger_id respectively
user_id	Agent ID for the from parameter Numeric ID, 32 bit
trigger_id	The identifier of the trigger for the from parameter Numeric ID, 32 bit
client_country	Client country String (255 characters)
client_city	Client city String (255 characters)
client_address	Client address String (255 characters)
new_address	Pass if it is necessary to create an additional address
phone_type	Phone type Possible values: home mobile stationary fax other
lists	Editing nested lists An array containing parameters: id value It is important to follow the structure of nested lists. This means that to change the value of the second level field you must pass the value of the first level field
template_id	WhatsApp Business template ID (pact)
template_name	WhatsApp Business template name (Landbot, infobip)
template_variables	WhatsApp Business template variables An array of strings. Variables are substituted in the template in corresponding order
template_lang	WhatsApp Business template language By default: ru

Sample request

{
    'subject': 'New Email',
    'message': 'Hi there!',
    'client_name': 'John',
    'client_email': 'superjohny@gmail.com',
    'field_id': '10;12;9',
    'field_value': 'any_value;true;93',
    'channel_id': 683,
    'lists':[
        [
            {
                "id":"61",
                "value":"Test"
            },
            {
                "id":"62",
                "value":"Test1"
            },
            {
                "id":"63",
                "value":"Test2"
            }
        ]
    ]
}

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://secure.usedesk.com/uapi/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' => 'Julia','subject' => 'There is some attachments'),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: multipart/form-data',
    'Cookie: laravel_session=8dIFarAWQMZlGKACtWX2A1KIQ5rlysgpCh9aMJmZ'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Sample PHP request

$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'=> 'any_value;true;93',
    'channel_id'=>683
);
$mch_api = curl_init(); // initialize cURL connection
curl_setopt($mch_api, CURLOPT_URL, 'https://secure.usedesk.com/uapi/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;

If the request is successful, the server will return a message about the successful creation and the id of the new request.

Sample response

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

Example of a request to send a message to the WhatsApp channel

In order for the client to receive the message on WhatsApp, consider the mandatory parameters from and user_id.

A new client in the system will be created if:

Parameter	Value
client_id	"new_client" or not used at all
client_phone	"79123456789" and it's not in the system

A new phone number will be added to the current client if:

Parameter	Value
client_id	Client ID is specified: "27747627"
client_phone	"79123456789" and it's not in the system

A new number will NOT be added to the current client if:

Parameter	Value
client_id	Client ID is specified: "27747627"
client_phone	"79123456789" and it exists in the system

If you use only the client_id parameter, the message will be sent to the first phone number specified in the system.

Sample request

{
    'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
    'message' => "Hello",
    'subject' => 'First msg',
    'channel_id' => '20054',
    'from'=>'user',
    'user_id'=> '2156',
    'client_phone'=> '79254697403',
    'client_id'=>'27747627'
}

If the request is successful, the server will return a message about successful creation, the ID of the new ticket, as well as the status of the request:

Sample response

{
    "status": "success",
    "ticket_id": 30745888,
    "message_status": "delivered"
}

A webhook request will be sent to check the sending status of the message. To do this in the Usedesk API channel specify the address to which the request will be sent.

An example of a webhook being sent

{ "message_status": {"delivery_status": "DELIVERED", "comment_id": 3551632, "extras": {"ticket_id": 1231234}}}

Sending a WhatsApp Business template

To start a dialog by sending a template, you need to pass the template data in the API request parameters:

Example of a request to send a WhatsApp Business template (pact)

{
    "api_token": "aff11f252956fcb0248f3a55cc92eb1234567890",
    "channel_id": 123,
    "from": "user",
    "client_phone": "79511234567",
    "template_id": 8094,
    "template_variables": ["John","18:00","London"]
}

Example of a request to send a WhatsApp Business template (Landbot, infobip)

{
    "api_token": "aff11f252956fcb0248f3a55cc92eb1234567890",
    "channel_id": 123,
    "from": "user",
    "client_phone": "79511234567",
    "template_name": "Main",
    "template_variables": ["Valeria"]
}

Example of a request to send a message to a Viber (c2d) channel

A new client in the system will be created if:

Parameter	Value
client_id	"new_client" or not used at all
client_phone	"79123456789" and it's not in the system

A new phone number will be added to the current client if:

Parameter	Value
client_id	Client ID is specified: "27747627"
client_phone	"79123456789" and it's not in the system

A new number will NOT be added to the current client if:

Parameter	Value
client_id	Client ID is specified: "27747627"
client_phone	"79123456789" and it exists in the system

If you use only the client_id parameter, the message will be sent to the first phone number specified in the system.

Sample request

    'api_token'=> 'e1987847345873068075215644cb53dd555de4',
    'message' => "Hello",
    'subject' => 'First msg',
    'channel_id' => '20054',
    'client_phone'=> '79254697403',
    'client_id'=>'27747627'

If the request is successful, the server will return a message about the successful creation, ID of the new request, as well as the ID of the created chat:

Server response example

{
    "status": "success",
    "ticket_id": 30745888,
    "chat_id": "5754"
}

Example of a request to send a message to a Telegram personal (pact) channel

To send a message, use client_phone if you want to send a message by phone number or username if you want to send a message by nickname.

When sending a message by nickname, you can use two spelling formats — "ivanov" and "@ivanov".

If both username and client_phone are specified, the message will be sent by username.

A new client in the system will be created if:

Parameter	Value
client_id*	"new_client" or not used at all
client_phone	"79123456789" and it's not in the system

Or:

Parameter	Value
client_id*	"new_client" or not used at all
username	"ivanov" and it's not in the system

A new phone number will be added to the current client if:

Parameter	Value
client_id*	Client ID is specified: "27747627"
client_phone	"79123456789" and it's not in the system

A new nickname will be added to the current client if:

Parameter	Value
client_id*	Client ID is specified: "27747627"
username	"ivanov" and it's not in the system

A new number will NOT be added to the current client if:

Parameter	Value
client_id*	Client ID is specified: "27747627"
client_phone	"79123456789" and it exists in the system

A new nickname will NOT be added to the current client if:

Parameter	Value
client_id*	Client ID is specified: "27747627"
username	"ivanov" and it exists in the system

If the request is successful, the server will return a message about the successful creation of a new ticket, as well as the status of sending the request:

Server response example

{

"status": "success",

"ticket_id": 30745888,

"message_status": "delivered"

}

Server response parameters

Parameter	Description
status	Request execution status success failed
comment_id	Comment ID

Categories

Create a ticket

Creating a ticket

Example of a request to send a message to the WhatsApp channel

Sending a WhatsApp Business template

Example of a request to send a message to a Viber (c2d) channel

Example of a request to send a message to a Telegram personal (pact) channel

Server response parameters

Was the article helpful?

Thanks for the feedback!

Advise how to improve the article

Thanks for the feedback!