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
  • Webhook service requirements
  • Webhook request
  • The token
  • The webhook payload
  • Intent data
  • Intent static reply
  • Chatbot metadata
  • Chatbot id
  • User language
  • Project id
  • The Request metadata

Was this helpful?

  1. Resolution bot

Webhook service

PreviousQuickstartNextRich messages

Last updated 1 year ago

Was this helpful?

To use fulfillment in a production system, you should implement and deploy a webhook service. To handle fulfillment, your webhook service needs to accept JSON requests and return JSON responses as specified in this guide. The detailed processing flow for fulfillment and webhooks is described in the .

Webhook service requirements

The following requirements must be met by your webhook service:

  1. It must handle HTTPS requests. HTTP is not supported.

  2. Its URL for requests must be publicly accessible.

  3. It must handle POST requests with a JSON WebhookRequest body.

  4. It must respond to WebhookRequest requests with a JSON WebhookResponse body.

Webhook request

When an intent configured for fulfillment is matched, Tiledesk sends an HTTPS POST webhook request to your webhook service. The body of this request is a JSON object with information about the matched intent.

In addition to the end-user query, many integrations also send some information about the end-user as well. For example, an ID to uniquely identify the user.

Here is a sample request:

{
  token: 'THE-CONVERSATION-TOKEN',
  payload: {
    intent: {
      intent_display_name: 'THE-INTENT-NAME'
    },
    message: {
      text: 'THE-ORIGINAL-INTENT-STATIC-REPLY',
      request: {
        request_id: 'THE-REQUEST-ID',
        language: 'THE-END-USER-ISO-LANG'
      }
    },
    bot: {
      name: 'THE-BOT-NAME',
      _id: 'THE-BOT-UNIQUE-ID'
      project_id: 'THE-PRJECT-THIS-BOT-BELONGS-TO'
    }
    
  }
  

The token

const token = req.body.token;

While repling to the end-users may look as a synchronous action, it is not.

The webhook payload

When an intent configured for fulfillment is matched, Tiledesk sends an HTTPS POST webhook request to your webhook service. The body of this request is a JSON object with information about the matched intent. The payload property contains the most of the information needed.

let payload = req.body.payload;

Intent data

Whitin the payload you can find many information about the current detected intent, i.e. his display name:

let intent = payload.intent;
let intent_name = intent.intent_display_name;

Intent static reply

The original static text that you set to reply to the user is also embedded in the payload:

const static_text = payload.message.text;

Chatbot metadata

Chatbot metadata are sent to your webhook, so you can have enough data to take the right actions based on the selected chatbot:

let bot = payload.bot;
let bot_name = bot.name;

Chatbot id

Just two words about the chabot ID. In Tiledesk the chatbot ID is a UUID. But inside a support conversation (that is 'group' conversation, where many partecipants can be involved) the chatbot partecipant ID always has a "bot_" prefix. This prefix helps Tiledesk to immediatly recognize a chatbot among the other partecipants, taking the right actions.

If you want to play with chatbots in the conversation (using orchestration APIs) always remember to prefix the chatbot ID with "bot_" before adding it to a conversation or to recognize it in the same conversation, like in the following example:

let bot = payload.bot;
let bot_id = bot._id;
let bot_id_as_conversation_partecipant = "bot_" + bot_id;

User language

This property is the language the user is using (i.e. the browser language):

let user_lang = payload.message.request.language;

Project id

const projectId = payload.bot.id_project;

The Request metadata

const request = payload.message.request;
const requestId = payload.message.request.request_id;

To reply you use the HTTP "res" object, but using the conversation token you can send as many messages as you want back to the conversation, using .

Simply set this token in the Authorization field of the .

fulfillment overview document
Tiledesk messaging APIs
send-message API