Webhook API Documentation

📖 Introduction#

This document will help you understand how to use the deskmy API Webhooks. Our current webhook integrations work in 3 modes: Thread Creation, Thread Message, and Company Thread.

🏠 Company Thread Webhook#

This webhook allows you to send message to your company webhook channel, that is public and available for all your users.

Your first step is to enable your webhook integration by accessing Integrations Management on your workspace settings

Once you access the webhook page and enable the webhook, you need to generate an API token.

⚙️ Getting a Token

You can generate a Bearer Token by clicking on the “Generate Token” button on the Company Webhook section. This token doesn’t expire, but you will be limited to 10 requests per minute. If you need more requests per minute, please contact us.

After getting the token, you need to set it to your request Authorization header, as a Bearer token.

Once the webhook is enabled, a new channel will show on deskmy’s channels, called “Webhook - COMPANY NAME”. This channel is public and available for all your users, and it’s where the messages sent by the webhook will be displayed. Users can not send messages to this channel, only the webhook can.

📨 Sending a message

To send a message, you need to make a POST request to the following URL (remebember to set the Authorization header):

https://api.deskmy.com/webhook/company_thread/

The request body must be a JSON object with the following fields:

{
    "message": "Hello World!"
}

The message field has a limit of 3000 characters. If you send a message with more than 3000 characters, the request will fail.

This request will send a message to your company’s webhook channel with the “Hello World” text. For now, you are only allowed to send string/text messages - but this will change in the future.

@ Thread Creation Webhook#

This webhook allows you to create new threads using external services. By creating a new thread, you also need to set a title, and send an initial message with it.

Your first step is to enable your webhook integration by accessing Integrations Management on your workspace settings

Once you access the webhook page, you need to create Webhook Integration on the Thread Webhooks sections. By clicking on the “Create” button, you will need to select the webhook type.

Select Thread Creation webhook to continue. Your new webhook will now be available on the list.

⚙️ Getting a Token

You can generate a Bearer Token by clicking on the “Details” button on the Thread Webhooks list. Once the webhook modal shows up, select Show on the token section to generate a new token. This token doesn’t expire, but you will be limited to 10 requests per minute. If you need more requests per minute, please contact us.

After getting the token, you need to set it to your request Authorization header, as a Bearer token.

📨 Creating a thread

To create a thread, you need to make a POST request to the following URL (remebember to set the Authorization header):

https://api.deskmy.com/webhook/create_thread/

The request body must be a JSON object with the following fields:

{
    "message": "Hello World!",
    "title": "A New Thread!"
}

The message field has a limit of 3000 characters. If you send a message with more than 3000 characters, the request will fail.

The title field will be the name of your new thread.

Don’t forget to select the users that will be included in the new thread on Details section of the webhook. You can also customize the sender name and avatar.

💬 Thread Message Webhook#

This webhook allows you to send message in threads using external services.

Your first step is to enable your webhook integration by accessing Integrations Management on your workspace settings

Once you access the webhook page, you need to create Webhook Integration on the Thread Webhooks sections. By clicking on the “Create” button, you will need to select the webhook type.

Select Thread Message webhook to continue. Your new webhook will now be available on the list.

⚙️ Getting a Token

You can generate a Bearer Token by clicking on the “Details” button on the Thread Webhooks list. Once the webhook modal shows up, select Show on the token section to generate a new token. This token doesn’t expire, but you will be limited to 10 requests per minute. If you need more requests per minute, please contact us.

After getting the token, you need to set it to your request Authorization header, as a Bearer token.

📨 Sending a message

To send a message, you need to make a POST request to the following URL (remebember to set the Authorization header):

https://api.deskmy.com/webhook/thread_message/

The request body must be a JSON object with the following fields:

{
    "message": "Hello World!",
}

The message field has a limit of 3000 characters. If you send a message with more than 3000 characters, the request will fail.

You need to select a thread to send your messages to. You can do that on the Details section of the webhook. You can also customize the sender name and avatar.

🎉 Thank you#

Thank you for reading this documentation. If you have any questions, please contact us!

@deskmy team