LeadFlip

Webhooks

How to set Webhooks

In order to make your bot smarter and useful, you need it to interact with your backend systems and third-party services. We provide a Webhook service that is hassle-free and give you maximum flexibility in feeding back responses and information.

Webhook Block

webhook config screen
Webhook Configuration screen

When you select “Do Webhook Call” as action type you are given a bunch of options.

Waiting Message This message will be passed to the user while we are doing a webhook call in the background. In our home site we are using “I’m signing you up, please wait” as waiting message.

Error Message This message will only be passed to the user if webhook call times out or it returns a malformed response. We will also send you an email to bot owner.

Call Type We support GET, POST, PUT, DELETE types.

Webhook URL This is where you put in target URL. You can use any information via @sign. Like https://yourdomain.com/[email protected]&[email protected]

We will talk about authentication types and JSON structure in next posts.

Please note that webhook calls will time out in 5 minutes and an error message will be passed on to the user.

Supported Authentication Types

We wanted to give you flexibility on how you choose to protect your APIs from unauthorized access. If you need another authentication scheme supported, please contact us and we will take a look.

Basic Authentication

Basic Authentication keeps your APIs secure via user – password pair. Simply feed this information while setting up your webhook blocks and you are done!

Key Authentication

Key Authentication depends on a single secret key passed along call header. Kong API Manager has a plugin to support this authentication type.

key authentication settings
Key Authentication Settings

OAuth2

Coming very soon.

Getting Started

We are using JSON objects to transfer information between our engine & your webhook. JSON is a pretty standard data structure, supported by a wide range of front-end technologies.

Request JSON

A sample request looks like this

{
  "bot_id": "E2LGaPoIISHvzDre",
  "block_id": "5817c67d312a91041b6aac7d",
  "user_information": {
    "name": "sender_name",
    "profile_picture": "profile_picture url"
  },
  "information": [
    {
      "label": "name",
      "value": "item value"
    }
  ]
}

Please note that user_information is an object but information is an array containing objects with label & value entities. You might wonder why we took this route. The answer is future-compatibility! We expect to supply more information like sentiment scores in future.

Response JSON

A sample response JSON is given below.

{
	"response": {
		"type": "send_message", 
		"message" : "response message to user"
	},
	"information": [
	{
		"label" :  "information label",
		"value" : "information value"
	}
	{
		"label" :  "information label",
		"value" : "information value"
	}
	...
	]
}

Right now we support three response types:

Message

"response": {
	"type": "send_message", 
	"message" : "response message to user"
},
	

Quick Reply

"response": {
	"type": "send_quickreply", 
	"message" : "response message to user",
	"quick_reply_buttons: ["button 1","button 2"] // max 10
},

Generic Template (FB Cards)

fb cards are supported by our widget

 

"response": {
    "type": "send_card", 
    "elements": [{
        "title_text": "Card Title",
        "subtitle_text": "Subtitle Text",
        "image_url": "https://leadflip.ai/assets/Frontend/images/leadflip_text_logo_small.png",
        "buttons": [ 
        {
          "type":"web_url",
          "url":"https://leadflip.ai",
          "title":"View Website"
        }},
       ...
       ]
   ...
  ]
},

Generic Template Buttons

Our webhooks are complaint with these Facebook buttons:

  • URL
  • Postback
  • Call
  • Share

We are including JSON structure for each button here for convenience. You can find detailed information on Facebook Button Documentation

URL Button

{
"type":"web_url",
"url":"https://leadflip.ai",
"title":"Link to Website",
"webview_height_ratio": "full", //compact,tall or full
"messenger_extensions": true, 
"fallback_url": "https://leadflip.ai"
}

Postback Button

{
"type": "postback",
"title": "Bookmark Item",
"payload: "Bookmark Item"
}

Call Button

{
"type": "phone_number",
"title": "Call Support",
"payload: "+16504426866"
}

Share Button

{
"type":"element_share"
}

Some restrictions are applied to make it Facebook compliant:

  • You can send over 10 elements maximum
  • Each element can have 3 buttons maximum
  • Title field is required

All response types are supported by WebWidget & FB Messenger. More response types like video, etc coming soon!