Webhook
Dlg Messaging Platform can feed many events and situations related to your bot to webhook that you create on your own servers. In this way, you can get the status of all messages you send to your users through your bot and the responses your users have written to these messages and you can take different actions according to these events. The platform will forward these events and conditions to your webhook by making a POST request.
How to Configure WebHook?#
You can only configure your bot by entering the following configuration parameters in the server.conf file of the dialog-server application.
| Configuration | Description |
|---|---|
| botUserName | The username of your Webbot. This should be the username information entered by admin when creating the bot. |
| id | This information is passed back to your webhook. In this way, if you have more than one webbot in the system and all meet the same webhook with this id you can distinguish. If you wish, you can provide a single webhook id for all your webbots. It all depends on the webhook you develop. |
| url | URL address of your Webhook. The Dlg Platform will send requests to this url. |
| app_secret | Used to validate requests from the DLG platform. With the app secret value that you specify, Dlg Platform creates the SHA1 HMAC of each message it sends to you and adds this value as "X-Signature" to the header of the request. You can verify incoming requests by checking the HMAC. |
| verify_token | Using this information, your webhook will validate the Dlg Platform, but its development has not yet completed. |
| subscribed_webhook_events | The Dlg Platform only transmits events that you subscribe to. You can define these events to the system with this parameter. You can enter at least one or all of the values of "MessageDeliveries", "MessageReads", "MessageEchoes" as an array, and subscribe to events. |
Webhook Events#
Below are the types of events you can get from the Dlg Platform. Different and new events will be added later. All of the events or subscribed events will be forward to your webhook by the platform.
| Webhook Event | Description |
|---|---|
| MessageEchoes | When you subscribe to this event, you can receive information that messages are sent to the recipient |
| MessageDeliveries | If you subscribe to this event, you can receive the message ids information that has been strictly received by the recipients via your webbot. |
| MessageReads | If you subscribe to this event, you can receive the message ids information that has been read by the recipients via your webbot. |
| Messages | When users write to you, they are delivered to your webhook via your webhook. To receive these messages, you must subscribe to this event. |
Event Format#
All webhook events are delivered to your webhook in the following format. In this format, your webhook id information, sender bot id, receiver id number, customer number, event forwarding time are included in each event type. The content of the event varies by event type. In another matter, the DLG platform collects a maximum of 10 events and transmits them at once, instead of sending each event to your system one by one. Of course, if 10 events have not accumulated within 5 seconds, it will forward the events that have occurred so far to your webhook. All events are sent in the entry array object.
Here is an example event format.
The meaning of the parameters of the above json object is as follows.
| Parameter | Type | Description |
|---|---|---|
| object | String | By default, this field will return to you as "dialog". |
| entry | Array<entry> | This field is the array where events are passed. One or more event objects will be sent to you. You can receive at least one and up to 10 events from each entry. |
entry#
| Parameter | Type | Description |
|---|---|---|
| id | String | The ID information you gave during the configuration for your Webbot is sent back to you through this field. |
| time | Number | The sent time of the event to your webhook by the Dlg Platform (epoch milliseconds) |
| messaging | Array<messaging> | An array containing each event information. For future reference, this is designed as an array, but will only be passed to you with one object. Therefore, you can take the first element and use it. |
messaging#
| Parameter | Type | Description |
|---|---|---|
| sender | <sender> | Webbot's information |
| recipient | <recipient> | Recipient's information |
| timestamp | Number | Event time (epoch miliseconds) |
| Event Datası | Event Data | The event content is different for each event. |
sender#
| Parameter | Type | Description |
|---|---|---|
| id | String | It is the unique id information of Webbot on the Dlg platform. |
recipient#
| Parameter | Type | Description |
|---|---|---|
| appCustomerId | String | The customer number of the user to whom the message was delivered. |
| id | String | The unique id information of the user on the DLG platform to which the message is delivered. |
Event Data#
MessageEchoes
Message Echo event is the event that occurs when the message is sent to the user via the bot. This event indicates to the user that the message was sent. This does not mean that the event has been delivered to the user.
The content of the sample MessageEcho is as follows.
| Parameter | Type | Description |
|---|---|---|
| app_id | String | It is the unique id information of Webbot on the Dlg platform. |
| is_echo | Boolean | Default returns true. |
| mid | String | id of the message |
Below is an example entry for the MessageEcho event.
MessageDeliveries
The Message Deliveries event is the event that occurs when message or messages are delivered to recipient via the bot. When this event is forwarded to your webhook, all messages with IDs in the event have been delivered to the user.
Sample delivery content is as follows.
| Parameter | Type | Description |
|---|---|---|
| mids | Array[String] | An array containing the message ids of messages forwarded to the user. All message ids in this array are delivered to the user. |
| watermark | Number | The time of the delivery event (epoch milliseconds). All messages before this time in this parameter have been delivered. |
Below is an example entry for the MessageDeliveries event.
MessageReads
This event is forwarded to your webhook when the user reads the messages.
Example read content is as follows.
| Parameter | Type | Description |
|---|---|---|
| mids | Array[String] | An array containing the message ids that the user read. All message ids in this array have been read by the user. |
| watermark | Number | The time of the read event (epoch milliseconds). All messages before this time in this parameter have been read. |
Below is an example entry for the MessageReads event.
Messages
When the user responds to your webbot, this event will send the user message to your webhook.
Example message content is as follows.
If the user has pressed one of the buttons of a template message containing the button you sent, the sample message content will be as follows.
| Parameter | Type | Description |
|---|---|---|
| mid | String | The id of the last message delivered to the user. The user has replied to this message. |
| text | String | This is the content of the user's response. If the user has typed text to you, you will receive the text directly from the user. If the user has sent a message such as OTP (mobile confirmation code), generictemplate, buttontemplate or quickreply type to the user and pressed the buttons of this message, you will get a reply to the message as [[messageId-92]: Hello ". In this way, you can detect which message the user has pushed, and take the necessary actions for the relevant message id. |
Below is an example entry for the Messages event.
Some Sample Event Requests#
- When a message is forwarded to the user by the bot, the MessageEchoes and MessageDeliveries event are normally forwarded to the webhook as follows.
- Another example is that the user can receive messages via webbot and read them instantly while the chat screen is open. In this case you will get an event content like the one below.
- You can send messages to multiple users at the same time. In the sample event request below, webbot sent a message to customer numbers 70021 and 70022 at approximately same times and a message was sent to customer 70021 but not yet to customer 70022.
- Another example is to send messages to the user, but the user read the messages sent to him after a while. In this case, only the reading events will be as follows when the user reads the messages. As it can be seen from the content below, the user has read the message id messageId-103, messageId-104 and messageId-105.