Chat Webhook reference

This tutorial will help you build your own integration with BotHelp. You can configure BotHelp to be immediately notified about particular events. Such a notification is called a webhook – it’s just a simple HTTPS POST request that BotHelp sends to your server when a particular event occurs. 

Setting up the webhooks

At the moment a BotHelp account may have only one webhook which subscribed by default on two events: user_profile_viewed and conversation_closed. A webhook subscription can be configured in the "Webhooks" section of your dashboard. Only admins can add, edit or delete webhooks. We support HTTPS subscription URLs to protect notifications.

Clicking «Add webhook» will show a form for creating the webhook. Enter the webhook URL, save it and we will automatically generate a token for this webhook. Webhook with specified URL and generated token would be shown in the list of webhooks on the page.

Token is required for creating a signature of request, Each callback will contain a signature on the JSON passed to the callback. The signature is HMAC with SHA256 that will use the generated token as the key and the JSON as the value. The result will be passed as HTTP Header X-Wh-Sign so the receiver can determine the origin of the message.

Webhook format

Each webhook is a HTTPS POST request made to the URL that you provide in the Integrations section of your account. The request's POST body contains webhook information in JSON format.

Each webhook contains the following properties:

• event – tells you the event that triggered the webhook. Possible values: user_profile_viewed, conversation_closed.

• event_timestamp – time of the event that triggered the callback.

• additional information – information related to a specific event type. Please read the Webhook event types section below.

When your server receives a webhook from BotHelp, it should respond with HTTP 200 status code. Otherwise, BotHelp will retry sending the webhook to your service for a number of times unless it receives the correct HTTP 200 status code (Soon).

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

Webhook events types

ConversationClosed event

This event type is sent each time when the conversation with your customer is closed by an operator. The example of request's POST body of this event is:

{
"event": "conversation_closed",
"event_timestamp": 1400857494,
"conversation": {
"type": "conversation",
"id": "147",
"started_at": 1400850973,
"ended_at": 1400857494
},
"user": {
"type": "user",
"id": "123123",
"nick": "Mister Ivan",
"email": "i.ivanov@gmail.com",
"phone": "+1123456789 ext. 923",
"name": "Ivan Ivanov",
"channel_type": "viber",
"channel_user_id": "asddasdasd==",
"channel_id": "bothelp",
"last_contact_at": 1397574667,
"first_contact_at": 1397574667,
"conversations_count": 179,
"avatar": "https://example.org/128Wash.jpg",
"custom_fields": {
"paid_subscriber": true,
"monthly_spend": 155.5,
"team_mates": 1
}
},
"assignee": {
"type": "agent", // or "team" if this conversation was assigned to the team
"id": "25",
"email": "wash@hello.io", // or "" if operator is not real. This field is absent if this conversation was assigned to the team
"name": "Dmitry"
},
"authors": [ //operators involved in the current conversation
{
"type": "agent",
"id": "2",
"email": "",
"name": "Vkontakte Page"
},
{
"type": "agent",
"id": "4",
"email": "",
"name": "Facebook Page"
},
{
"type": "agent",
"id": "25",
"email": "wash@hello.io",
"name": "Dmitry"
}
],
"messages": [
{
"author": {
"type": "user",
"id": "123123"
},
"id": "344",
"type": "text",
"text": "Hello",
"timestamp": 1358937653
},
{
"author": {
"type": "user",
"id": "123123"
},
"id": "417",
"type": "document",
"data": {
"link": 'http://example.com/document.pdf',
"name": 'SimpleDocument.pdf',
"size": 24123
},
"timestamp": 1358937661
},
{
"author": {
"type": "agent",
"id": "25"
},
"id": "420",
"type": "image",
"data": "http://example.org/image.jpg",
"timestamp": 1358937661
},
{
"author": {
"type": "agent",
"id": "25"
},
"id": "425",
"type": "sticker",
"data": "http://example.org/sticker1.png",
"timestamp": 1358937661
},
{
"author": {
"type": "agent",
"id": "25"
},
"id": "450",
"type": "video",
"data": "http://example.org/video1.mp4",
"timestamp": 1358937661
},
{
"author": {
"type": "user",
"id": "123123"
},
"id": "457",
"type": "location",
"data": {
"longitude": 25.0123323,
"latitude": 50.1748532
},
"timestamp": 1358937661
},
{
"author": {
"type": "user",
"id": "123123"
},
"id": "460",
"type": "contact",
"data": {
"name": "Ivan I.",
"phone_number": "+123321123"
},
"timestamp": 1358937661
}
]
}

If you have any questions, feel free to ask us at the chat.