Webhook reference

This tutorial will help you build your own integration with WhatsHelp. You can configure WhatsHelp to be immediately notified about particular events. Such a notification is called a  webhook – it’s just a simple HTTPS POST request that WhatsHelp sends to your server when a particular event occurs. To know more about how webhooks may be used, please have a look at this article  How to integrate WhatsHelp with CRM or HelpDesk.

Setting up the webhooks

At the moment a WhatsHelp 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_viewedconversation_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 WhatsHelp, it should respond with  HTTP 200 status code. Otherwise, WhatsHelp will retry sending the webhook to your service for a number of times unless it receives the correct HTTP 200 status code (Soon).

Note: WhatsHelp 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": "whatshelp",
    "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
    }
  ]
}

UserProfileViewed event

This event type is sent each time when the profile ot the user is viewed by an operator. The example of request's POST body of this event is:

{
  "event": "user_profile_viewed",
  "event_timestamp": 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": "whatshelp",
    "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
    }
  },
}

The distinctive feature of this event type is that your server has to respond to this request in the following format:

{
  "fields": [ //Array of
    {
      "name": %field name%, //must be string
      "value": %field value% //muste be string or number
    }
  ]
}
	

Example:

{   
  "fields": [
     {
       "name": "Age",
       "value": 36
    },
    {
       "name": "Position",
       "value": "CMO user"
    },
    {
       "name": "Website",
       "value": "http://example.com" //Would be the link to example.com with example.com as a link text
    },
    {
       "name": "Last deal",
       "value": "[link_text|http://example.com]" //Would be the link to example.com with lint_text as a link text
    }
 ]
}

Received field would be shown in the user profile in WhatsHelp (see   How to integrate WhatsHelp with CRM or HelpDesk). If your server does not respond in this format, his response will be ignored.

If you have any questions, feel free to ask us at  hello@whatshelp.io.

Still need help? Contact Us Contact Us