Subscribing to Chat Webhooks

This article is archived has been merged into our wider document on Webhooks.

DeskDirector can call webhooks whenever a chat session is created or updated. This is a really powerful way to customize your chat workflow. The following steps assume you already have an http endpoint setup to send data to, we do not currently have a guide to help you do this. If you are comfortable with Zapier or Flow you shouldn't have a problem with following this guide.

Step 1: Head to the webhook page

This can be found in your admin console under Advanced > Developer Corner. Once in the page, enable the webhooks feature by checking the box. Once done, go to Advanced > Webhook

Step 2: Add a new webhook subscription

To create a chat webhook, click on the dropdown arrow beside "Create Webhook" then select Add Chat Webhook . Provide the information needed to setup the chat webhook like Description, Receiver URL and select which chat event you want for the webhook.

Step 3: Test your webhook

Create a chat session and verify that the payload is reaching your endpoint. To check what the payload should look like, see here.

What can I do with this?

Some ideas:

  • Send an email to a manager whenever a chat session is abandoned by a user
    • Alternatively you could create a ticket inside your PSA to make sure someone follows up
  • Send an email to your technicians if a chat session remains in the 'handled' status for more than 1 hour. It's unlikely that a chat session is ongoing for more than an hour, so this is a good reminder for your technicians to close their chat sessions and create tickets.
Chat Webhook Payload

The payload will contain a list of events. Each event represent one of chat sessions change. Below are explaination for some of properties.

You can use website such as https://webhook.site to test out webhook payload. Then use either Zapier or other automation tool to trigger notification.

By using Zapier, you can broadcast to Microsoft Teams, Slacks etc.

  • status:
    • created, - session been created
    • handled, - session been handled by one of technician
    • missed, - user left session without been answered
    • callback, - user left session and setup callback info
    • completed - session been closed
  • pastStatus: a list of past status.
  • type:
    • request - chat request from end user. (portal)
    • push - push chat, which initialized by technician from TECH
  • reference: If the chat is regarding to a ticket, type will be ticket and id will be ticket id.
  • creator: User who created this chat session. it can be member or contact.
  • targetUsers: Chat invitation list. When invite other user, they will be inside target users list first, if they accept, it will move under users list.
  • users: Who is inside this chat session.
  • partitions: All the users who have ever been entered this chat session.
[
	{
		"msp": "dd",
		"id": "1586985009-627B",
		"name": "Test",
		"type": "request",
		"status": "handled",
		"pastStatus": ["created", "handled"],
		"report": {
			"creatorWaited": null,
			"handledDateTime": null,
			"chatDuration": null
		},
		"reference": {
			"type": "ticket",
			"id": "22282"
		},
		"creator": {
			"entityId": 106,
			"name": "Jason He",
			"userId": "dd~c~106",
			"company": {
				"entityId": 19348,
				"name": "DeskDirector",
				"identifier": "DeskDirectorLtd"
			}
		},
		"callback": null,
		"targetUsers": [],
		"closeRecord": null,
		"users": [
			{
				"entityId": 106,
				"name": "Jason He",
				"userId": "dd~c~106",
				"company": {
					"entityId": 19348,
					"name": "DeskDirector",
					"identifier": "DeskDirectorLtd"
				}
			}
		],
		"participants": [
			{
				"entityId": 106,
				"name": "Jason He",
				"userId": "dd~c~106",
				"company": {
					"entityId": 19348,
					"name": "DeskDirector",
					"identifier": "DeskDirectorLtd"
				}
			}
		],
		"lastMessageId": null,
		"createdDateTime": "2020-04-15T21:10:09.5895683Z",
		"lastModifiedDateTime": "2020-04-15T21:12:00.9897216Z",
		"meta": {
			"canAccess": true
		}
	}
]

How did we do?

Contact