Requests from Usedesk (Webhooks)

Warning

If you use the on-premise Usedesk version on your own server, then the URL of your methods will be different. Specify the URL to work with API by contacting our support team - support@usedesk.ru

To enable requests, check the checkboxes, for which requests should arrive, on the API settings page (Channels → API).

Usedesk will send you requests to the address specified when configuring the API channel at the "Redirect url” field.


If you enable the "JSON request" - the request will come at json-format with the appropriate headers.

Setting "send to UTF-8" removes character conversions, for example, at comments.

Types of requests

1. Create a ticket.
2. Create a comment.
3. Change a ticket.
4. User rating.

Create a ticket

ParameterValue 

secret

API chennel's token

id

ticket id
status_id

ticket's status id

List of possible statuses:

  • 1 (open)
  • 2 (completed)
  • 3 (closed)
  • 4 (deleted)
  • 5 (on hold)
  • 6 (pending)
  • 7 (spam)
  • 8 (new)
  • 9 (mailing)


subject

Ticket subject

client_idclient's ID
assignee_idid of the executor (agent)
groupexecuter's id of the group
last_updated_atlast ticket modification date
channel_idchannel id
emailclien't mail adress (from which he wrote)
published_atticket's creation date
company_idcompany's id (account) which the webhook came
additional_idadditional ticket ID
messagetext of the client's message
custom_fields

List of fields and their values. Sent only when at least one of the fields is additional.

Contains parameters:

  • id - add id. fields
  • name - name of add. fields
  • value - additional value. fields
  • custom_blocks

custom_blocks

List of additional system blocks, which contains parameters:

  • name - the name of the block
  • url - url of the block
  • secret_key - secret token of the block
Example of a response from server
{
	"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
	"ticket":{
		"id":"2261907",
		"status_id":"1",
		"subject":"First msg",
		"client_id":"242630",
		"assignee_id":null,
		"group":"0",
		"last_updated_at":"2016-12-17 14:07:33",
		"email":"jon@bonjovi.com",
		"published_at":"2016-12-17 14:07:33",
		"company_id":"153561",
		"additional_id":"123Ca344",
		"custom_fields":[
			{
				"id":54,
				"name":"new item 2",
				"value":null
			}
		],
		"custom_blocks":[
			{
				"name":"Test",
				"url":"test",
				"secret_key":"dsf4354f=-213sdfasdsa"
			}
		]
	}
}

Change a ticket

When a ticket is changed, the system sends a webhook that contains:

ParameterValue 

secret

api channel's token

id

id of the ticket's changing event
trigger_id

id rule that changed the request
If "null" means the request was changed by the user

user_id

id of the user who changed the request
If "null" means the request changed the rule

ticket_idticket's id
data

The array of changes that were applied to the ticket contains the parameters:

  • target - which field was changed
  • value - what value the field was changed to
  • old_value - from what value the field was changed
changed_at

date of change

old_statusid of the previous ticket status
new_statusid of the new ticket status
company_idid of the company (account) from which the webhook came
custom_fields

List of fields and their values. Sent only when at least one of the fields is additional.

Contains parameters:

  • id - add id. fields
  • name - name of add. fields
  • value - additional value. fields
  • custom_blocks
custom_blocks

List of additional system blocks, which contains parameters:

  • name - the name of the block
  • url - url of the block
  • secret_key - secret token of the block
client

Client information. Contains parameters:

  • id 
  • name – name
  • avatar – avatar
  • note – note
  • emails – email address
  • phones - phone
  • additional_ids – additional ID
Example of a response from server
{
	"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
	"custom_fields":[
		{
			"id":54,
			"name":"new item 2",
			"value":null
		}
	],
	"custom_blocks":[
		{
			"name":"Test",
			"url":"test",
			"secret_key":"dsf4354f=-213sdfasdsa"
		}
	],
	"trigger":{
		"id":"204232",
		"trigger_id":null,
		"user_id":"2",
		"ticket_id":"2261907",
		"data":[
			{
				"target":"subject",
				"value":"POST UPDATE"
			},
			{
				"target":"status_id",
				"value":"2"
			},
			{
				"target":"priority",
				"value":"medium"
			},
			{
				"target":"type",
				"value":"task"
			}
		],
		"changed_at":"2016-12-17 14:11:53",
		"old_status":"1",
		"new_status":"2",
		"company_id":"153561"
	}
}

Create a comment

When you write a comment in a ticket, the system sends a webhook that contains:

ParameterValue

secret

api channel's token
idcomment's id 
messagethe text of the message that was sent
type
  • Message type:
    private - internal
    public - public
from

the messages author

  • user - agent
  • client - client

Important: if a message is sent via a trigger (bot), a new message webhook will not be sent. A webhook will be sent to update the request.

user_id

id of the user who wrote the message


If "null" means the comment was written by the client

client_id

id of the client who wrote the message


If "null" means the comment was written by the user

ticket_idid of the ticket in which the comment was written
is_first

1 - if the comment is the first in the ticket
0 - if the comment is not the first in the ticket

deliveredwhether the message has been delivered (not implemented)
readedwhether the message has been read (not implemented)
published_atсomment creation date
custom_fields

list of fields and their values. Contains parameters:

  • id - add id. fields
  • name - name of add. fields
  • value - additional value. fields
client

Client information. Contains parameters:

  • id 
  • name – name
  • avatar – avatar
  • note – note
  • emails – email address
  • phones - phone
  • additional_ids – additional ID
Example of a response from server
{
	"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
	"comment":{
		"id":"2652657",
		"message":"New message text",
		"from":"user",
		"user_id":"545",
		"client_id":null,
		"ticket_id":"2261907",
		"is_first":"0",
		"delivered":"0",
		"readed":"0",
		"published_at":"2016-12-17 14:14:37"
	}
}

Rating

When receiving a rate in a ticket, the system sends a webhook that contains:

ParameterValue

secret

api channel's token
idid оценки
client_idclient's id
ticket_idticket's id
rating

The rating is given by the client:

1 - poor
2 - normal
3 - good

company_idid of the company (account) from which the webhook came
ticket_comment_idrating's comment id
commentcomment to the rating
created_atdate the rating was created
updated_atrating update date
user_idid of the request executor
Example of a response from server
{
	"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
	"csi":{
		"id":"2652657",
		"comment":"New message text",
		"user_id":"545",
		"client_id":123213,
		"ticket_id":"2261907",
		"rating":"3",
		"created_at":"2016-12-17 14:14:37"
	}
}

Chat actions

After creating the chat, Usedesk will send requests to the address specified when configuring the API channel at the "Redirect url” field.

To enable chat related requests, check the corresponding checkboxes (requests should arrive for those that were checked) at the widget's settings page (Channels → Chat channel → "Request Settings" section). It can be:

1. A new chat: the request indicates the creation of a new chat, about the first message at it.
2. All chat messages: the request indicates the creation of all subsequent messages in the chat.
3. Chat resume: the request indicates that the chat was reopened by a new message if the chat was finished before.

All requests are based on the same request body with the "chat_id" reference parameter. If "chat_id" has already been created with one of the requests, then new messages and the resumption of chat work in the necessary chat, based on the reference parameter.

При входящем/исходящем сообщении в чате система отправляет вебхук который содержит:

ParameterValue

chat_id

chat id
textmessage text
client_idclient id 
client

Client information. Contains parameters:

  • id 
  • name – name
  • avatar – avatar
  • note – note
  • emails – email address
  • phones - phone
  • additional_ids – additional ID
from

A message was written on behalf of:

  • user - agent
  • client - client

Important: if a message is sent via a rule (bot), a new message webhook will not be sent. A webhook will be sent to update the request.

platform

The type of channel from which the chat was created.

Possible types: usedesk_tg - telegram

secretAPI channel's token 
idticket's id
status_id

ticket status id


List of possible statuses:
1 (open)
2 (completed)
3 (closed)
4 (deleted)
5 (on hold)
6 (pending)
7 (spam)
8 (new)
9 (mailing)

subject

ticket subject

client_idclient's id 
assignee_idid executor (agent)
groupid of the executor's group 
last_updated_atdate of the last ticket changes
channel_idchannel's id 
emailclient's e-mail address (from which he wrote)
published_atdate of ticket creation
company_idCompany (account) id from where the webhook came from
additional_idadditional ticket ID
messagethe text of the first request message
custom_fields

List of fields and their values. Sent only when at least one of the additional  fields.
Contains parameters:

  • id - additional fields id
  • name - name of additional field
  • value - value of the additional field
custom_blocks

List of add. system blocks, which contains parameters:

  • name - the name of the block
  • url - url of the block
  • secret_key - secret token of the block
state

if  the chat status changes

  • new - new
  • reopened - reopened
  • closed - closed

If the chat status has not changed - "null"

Example of a response from server
{
	"chat_id": "1962066", 
	"text": "hi", 
	"client_id": "4476034", 
	"from": "client", 
	"platform": "",
	"secret": "***", 
	"ticket": 
	{
		"id":"10264808",
		"status_id":"8",
		"subject":"Cashew is a nut",
		"client_id":"4367802",
		"assignee_id":null,
		"group":null,
		"last_updated_at":"2018-05-11 14:17:12",
		"channel_id":"4242",
		"email":null,
		"published_at":"2018-05-11 14:17:12",
		"company_id":"155568",
		"additional_id":"",
		"message":"This is unbelievable."
	}
}