Tiledesk Developer Hub
WebsiteCommunityTutorialsGet started
  • Introduction
  • Community
  • Ask for Support
  • Public Roadmap and Changelog
  • Tutorials
  • Widget
    • Widget SDK
    • Javascript API: Methods
    • Javascript API: Attributes
    • Javascript API: Listeners/Events
    • Widget Authentication
    • Widget Angular integration
    • Widget React integration
    • Widget for Android with WebView
    • Widget for iOS with WKWebView
    • Widget for Flutter with WebView
    • Widget for React with WebView
    • Widget for Wix Website platform
    • Tutorials
      • Hide widget
      • Show/Hide widget programmatically
      • Force widget loading without user interaction
      • Mobile positioning
      • Custom size (width/height)
      • Installing widget on selected pages
    • Conversation Embedded Apps
      • Payment App Tutorial
      • Prechat form App Tutorial
    • Advanced
      • Preset the Widget on a specific Department
      • Authentication Flow
      • Widget protocol specs
      • Prechat Form JSON specs
      • Prevent multiple conversations
      • Old versions
        • Web SDK v4
  • External Chatbot
    • Introduction
    • Hello World tutorial
    • Chatbot to Human handoff
    • Send Text Buttons
    • Advanced Tutorials
      • Introduction
      • Tutorial 1 - Dialogflow as external chatbot
      • Tutorial 2 - Buttons and images
      • Tutorial 3 - Automatic human handoff with fallback intent
      • Tutorial 4 - Explicit Human handoff with user intent
      • Tutorial 5 - Gracefully handling operating hours during handoff
      • Generate Dialogflow Google Credentials file
    • Rasa tutorials
      • Rasa Tutorial 1 - Rasa as external chatbot
  • Resolution bot
    • Introduction
    • Quickstart
    • Webhook service
    • Rich messages
    • Tutorials
      • Chatbot chooser (multilanguage)
      • Department chooser
      • Order info (webhook)
  • APIs
    • REST APIs
      • Introduction
      • Authentication
      • Requests
      • Leads
      • Messages
      • Activities
      • Projects
      • Team
      • User
      • Analytics
      • Canned responses
      • Tags
      • Events
      • Jwt
      • Labels
      • Images
      • Files
      • Segments
      • Chatbots
      • Knowledge Bases
        • Knowledge Base
        • Contents
        • Question & Answer
      • Management Api
        • Departments
        • Groups
    • NodeJS SDK
    • Webhooks
      • Subscriptions
    • Conversation Messages APIs tips
    • Realtime API
    • JWT Authentication
      • JWT Custom authentication Tutorial
    • Tutorials
      • REST API
        • Sending and receiving messages with Tiledesk APIs
        • PHP Tiledesk REST API example
        • Import multiple messages into Tiledesk using REST APIs from third party app
      • Webhooks
        • Custom Request assignment
        • Request transcript on close
  • Apps
    • Build Custom App - Quick start
    • External Channels integration flow diagram
    • Telegram integration tutorial
  • Dashboard & AgentChat SDK
    • Dashboard SDK
    • Agent Chat SDK
  • Architecture
    • Architecture overview
    • Components list
    • Bot Design diagram
    • Multi Channel Message Flow
  • Installation
    • Installation
    • Running Tiledesk using Docker Compose
    • Running Tiledesk with Kubernetes using Helm
    • Choosing Hardware
  • Configuration
    • Chat21 channel configuration
    • Email parameters and templates configuration
    • Configure the logging system
Powered by GitBook
On this page
  • Introduction
  • Use cases
  • Getting started
  • Prerequisites
  • RESTHooks
  • Webhook format
  • Webhook Models
  • Webhook events
  • Webhook Notification object
  • Security - Signed Notifications
  • Debugging a webhook

Was this helpful?

  1. APIs

Webhooks

PreviousNodeJS SDKNextSubscriptions

Last updated 1 year ago

Was this helpful?

Introduction

Webhooks are a powerful resource that you can use to automate your use cases and improve your productivity.

Unlike the API resources, which represent static data that you can create, update and retrieve as needed, webhooks represent dynamic resources. You can configure them to automatically notify you when for example a new request occurs.

Use cases

Typical use case for webhook integration is connecting Tiledesk to external CRM, marketing automation tools or data analytics platforms.

Follow this tutorial if you’re developing a Tiledesk integration that reacts to internal Tiledesk events, such as new incoming chat or queued visitor.

For instance if you’re integrating a marketing automation tool, you could add a new contact every time a Tiledesk visitor starts a chat.

Getting started

To use this tool you need to have basic knowledge about webhooks and Tiledesk authorization protocol.

This tutorial is will not be helpful for integration that pulls data on demand (not in reaction to some Tiledesk event). If you just want to pull Tiledesk reports on user request, you’d rather just use .

Prerequisites

You’ll need a Tiledesk Account. Sign up to the to create a new account.

RESTHooks

Tiledesk can send notifications when some particular action is performed. Such a notification is called a webhook – it’s just a simple HTTP request that Tiledesk sends to your server when a particular event occurs.

To use RestHook you can:

  • Create a New Subscription using Dashoboard UI. Go to Settings > Project Settings > Developer (tab) and click on Manage WebHook button.

Each Subscription consists of the following properties:

  • event – determines when the webhook is sent to your web server.

  • target – address of your web server the webhook will be sent to.

Webhook format

Each webhook is a HTTP POST request made to the URL that you provide. The request’s POST body contains webhook information in JSON format.

{
   "hook":{
      "_id":"5c4f1c2e081bde0016cd61d4",
      "updatedAt":"2019-01-28T15:13:50.807Z",
      "createdAt":"2019-01-28T15:13:50.807Z",
      "target":"https://webhook.site/xyzxyz",
      "event":"request.close",
      "id_project":"5ad5bd52c975820014ba9234",
      "createdBy":"5aaa99024c3b110014b478f0",
      "__v":0
   },
   "timestamp":1549035233858,
   "payload":{
      "_id":"5c542239721b190016a50538",
      "request_id":"support-group-LXcdORkb1Kp21ucGNEH",
      "requester_id":"5beda319507c7500150b1b80",
      "first_text":"hello",
      "department":"5b8eb4955ca4d300141fb2cc",
      "sourcePage":"http://localhost:4200/#/login",
      "id_project":"5ad5bd52c975820014ba9234",
       ...
   }
}

Each webhook request contains the following properties:

  • hook – return the subscription object that triggered the webhook.

  • payload – It contains the data of the webhook.

When your server receives a webhook from Tiledesk, it should respond with HTTP 200 response. Otherwise, Tiledesk will retry sending the webhook to your service for a number of times unless it receives the correct HTTP 200 response.

Note: Tiledesk webhooks are sent with Content-Type: application/json header, so please make sure that your service can handle such requests.

Webhook Models

Webhook events

The following Events are available and you can be notified when an action relating to that event occurs.

Event
Description
Model

request.create

Subscribe to requests creations

request.update

Subscribe to request being updated

request.close

Subscribe to request being closed

message.create

Subscribe to messages creations (sent and receive)

message.create.request.channel.CHANNEL_NAME

Subscribe to messages created (sent and receive) from a specific channel. Ex: message.create.request.channel.telegram for Telegram

lead.create

Subscribes to leads creations

faq.create

Subscribes to faq creations

faq.update

Subscribes to faq being updated

faq.delete

Subscribes to faq being deleted

faqbot.create

Subscribes to bot creations

faqbot.update

Subscribes to bot being updated

faqbot.delete

Subscribes to bot being deleted

department.create

Subscribes to department creations

department.update

Subscribes to department being updated

department.delete

Subscribes to department being deleted

project_user.invite

Subscribes to teammate project invitation

project_user.update

Subscribes to teammate being updated

project_user.delete

Subscribes to teammate project leave

group.create

Subscribes to group creations

group.update

Subscribes to group being updated

group.delete

Subscribes to group being deleted

event.emit

Subscribes to event emitting

event.emit.EVENT_NAME

Subscribes to a specific event emitting. Example: event.emit.typing.start to subscribe to typing indicator events.

operator.select

Custom

Webhook Notification object

A notification object contains the following fields:

  • Hook attribute

  • Payload attribute

Hook Attribute

Hook attribute contains the subscription object that triggered the webhook.

Attribute
Type
Description

_id

string

The Tiledesk defined id representing the subscription.

createdAt

timestamp

The timestamp the subscription was created.

updatedAt

timestamp

The timestamp the subscription was updated

target

string

The subscription target url

event

string

Corresponds to an event, eg 'lead.create', 'request.create'

Payload

Payload is the data associated with the notification. To understand the payload object you must consider the model column of the Webhook Events table.

Security - Signed Notifications

Each webhook notification is signed by Tiledesk via an x-hook-secret header. This header contains the webhook secret, randomically generated at the first creation (using UI or REST API) of the webhook subscription. We do this so that you can verify the notification came from Tiledesk, comparing the value x-hook-secret header with the secret value obtained during the first creation.

Debugging a webhook

In most cases, the response comes from the third-party service that receives the webhook's request, not Tiledesk itself. You typically need to work with this service to fix errors.

You can use the numeric code in the response status to diagnose issues. These response status codes are standard across HTTP requests. For a list of the standard HTTP response status codes and their meaning, see HTTP response status codes in the MDN web docs.

Note: If a service uses custom HTTP response status codes, you may need to consult their documentation.

Webhook requests have a 10-second timeout. A "Failed: 504 Gateway Timeout" response status indicates a service didn't respond to a webhook's request within this timeout period. The timeout period is not adjustable.

Tiledesk uses RestHook patterns. REST Hooks itself is not a specification, it is a collection of patterns that treat webhooks like subscriptions. These subscriptions are manipulated via a REST API just like any other resource. More info about Rest Hook .

image

.

Subscribes synchronously to the assignment of the conversation to a specific agent or bot. Before Tiledesk assigns a conversation to an operator (agent or bot) you can create a custom endpoint that receive the webhook call and dynamically select the operator based on your custom logic (for example: skills, operating hours, etc..). The webhook sends the following payload: 1) the agents array 2) the available agents array 3) the suggested operator selected by Tiledesk engine if routing is "assigned", while if "pooled" an empty array 4) the department model 5) the project model 6) the id of the operator selected in the previeous assignment 7) the conversation in the previeous assignment. Attention only one subscription per project is supported. Find an example

If a webhook isn't working correctly, failed invocations will be visible using .

REST API
Tiledesk Dashboard
here
Get the subscriptions logs REST API
Faq
Faq
Faq
here
Message
Message
Lead
Create a New Subscription using REST API
Event
Event
Request
Request
Request
Team
Team
Team
Bot
Bot
Bot
Department
Department
Department
Group
Group
Group