Acquire
  • Home
  • Chatbots
  • Webhooks for Chatbots

Webhooks for Chatbots



Customize the flow of your bot conversations with webhooks. Acquire’s webhooks are universal, meaning that agents and bots may share dynamic data. This tutorial will walk you through setting up a webhook and connecting it to a chatbot.

In this article

  • Creating a Webhook
  • Connecting a Webhook to a Chatbot
  • Types of Webhooks
    • Special Webhooks
    • Setting a Fallback Response
  • Webhook Examples

This article covers concepts such as JSON, webhooks, Custom Attributes, and Chatbots. It’s recommended for advanced users. 

Creating a Webhook in Acquire

Once you’ve created a webhook on a testing site (such as webhook.site or pipedream) or in your system, you’ll need to create a reference to it in Acquire. To create a new webhook, go to Settings > For Developers > Webhooks and click on the ‘Create Webhook’ button.


3zk0ZP84f0U7G1sEpKw995NNpUU4cmAxrI6O-oiqEx0__5AUxzUJ-BOG_H3mhm28LLBMsZb5Rm7YvhhBYDDLd-YFdw6BHvUC6WNcdOa0i68gNdL7_d5S7sfrnS4WQcK375uLJfCE

Provide a new name for your webhook in the ‘Webhook Name’ field. Then, select Inbound in the ‘Webhook Flow’ section. Learn more about the different types of webhooks below:

  • Inbound - collects information from outside sources to be displayed within Acquire. Works with chatbots.
  • Outbound - collects information from within Acquire to be displayed in outside sources.

Next, set your format, status, and security preferences as well as an email address. Should your webhook fail, a notification will be sent to the email address provided.


Y4HOdBdM5r5CyV2OzfcQD_vxo3LzT1ukJ1iknqufwysDTTmHKJoavUweKcMQiJptWIm0tG0fAz_gzCp-JxemrKBn_uTI-qcruz9KCg82sGBWIGGJtVtZ2ciQKn2A4qfld9sXR1Wt

Paste the webhook URL. Once pasted, you’ll see a list of the available variables. 


ecbijG0r4UzXAbTUGeftAIhrngvTQQs7umWwPHVr4pQxazFN3wHSLsofRRJirwqDP9_nBmFNQ7RWVQzbh8m7Wz-pPvkCoIOjA61HVAKd3_i6up8jjgcXalb8whSuyewciZAgv8cD

The “Available Variables” section will list variables if system identifies the variables from the URL response, if it does not list any variables you can add your own variable

To add custom variable names, click on the ‘Add more variables’ option. 

(You'll need to do this when using more than one special webhook).

Then, press on ‘Create’.

Your inbound webhook is now ready!

Connecting a Webhook to a Chatbot

All webhooks work with Sequence Bots. A few work with the Conversational Bot. We recommend using webhooks in Sequence Bots to create a predictable experience. 

Sequence Bot

To use a webhook in a Sequence Bot, go to Chatbots > Sequence Bot. Create a new sequence or edit an existing one.

In the bot flow page, select a node to edit it and then click on the webhooks button in the toolbar. A drop-down menu of your webhook variables will appear.

Screen-Shot-2021-05-18-at-12-27-53-PM-b3ab83d8be818d2e3169bad5.png

Finally, press ‘Save Branch’. Your Sequence Bot will display the webhook information when it is triggered.

Note: Webhooks may not behave properly if you use them in the initial message and turn the bot greeting ‘on’. We recommend disabling Bot Greetings when using webhooks and using them after the initial message.

To turn off greetings for all Sequence Bots, go to Chatbots > Configuration and disable ‘Allow Greeting in Widget Pop-up’.


y_RCyXuHwtSPZ7gO7Sn1MhE-AhAYPH3dDwwXCODTIL7AbYkVKxtypMJOB_vK3H2W-b7RoufV0anAZDfPgZrr9hweWUbxwrW9NR2e8_IctXKMxBbVVbd-7JIABKQtuOLT7EPNmKcv

To turn off the greeting for a specific bot, look in the top-right corner (next to the publishing toggle) of the workflow and switch the greeting to off. 


rlllSd_QgdnaX5wpzEtEJIghp235diTynxHuXyV6jItrl9Pd3e8CJxL5fy9zUgNwYiLKrrkPf5Fq2I7liL6vbOeIssx1pu4aopU8KWpH_THQ27Mz1khgEj_bYqWAS2o308s6BvPI

Conversational Bot

To have a Conversational Bot display a webhook response, go to your Conversational Bot group in Chatbots > Conversational Bot. Create a new question by clicking on the ‘Add New Question’ button, or edit an existing one.

Write your question (and variations) in the ‘Add Question’ field.

In the Answer type section, select ‘Formatted Answer’ and then click on the webhook button in the toolbar. Scroll down to the ‘Webhook’ list and select the webhook.


D4Uy6Ka153fsLCVtB60kQcSUqtRyX4x-4xXgeDlH8c0oYqPnZR-5jw9IljXW7P2af1SbhwdZRAXl8VwteKUtUSu9u2LCOaOfQ3Rr-8I48lr6OWBHJLbBRV-t_STuqZ-mFbWpCUDa

Your Conversational Bot will now give a dynamic response to customers.


uZMAexUk7a_GOnOzdHZCl9L6nJ6y19dUcRkreeTAgY8r0E3g5UEX6zsxa4urrMTlAHE-waTEKpFQQyoeWvM_QJ0sMKEMIdbMC3se08nEvJhbTE0ytEDQ_OYmMb-FQJwfahuvGgkU

Types of Webhooks

Webhooks are categorized into two groups: string-based and special webhooks.

String 

Works with: Conversational Bot and Sequence Bot

String webhooks are text-based responses that may be combined with text already in your bot. Format your webhook response in a key-value pair. For example:

{"account_balance":"$36,000"}

In the Sequence Bot example below, the sentence ‘Your Account Balance is {{account_balance}}’ is used to show a customer what their bank account balance is.


jc5DM1C6VKikGlC74UxmcjbqZegrllQeFI1FMjyqVrYa7MUqTisRX0MMcUAhKjNLS9TLPggnTCDehVNrdNSwHu68iK8P1OuGutbm2a3L5d-U2yjfWeoYtmVXWpTjvth0E3csLQDz

When a customer reaches the ‘Account Balance’ part of the sequence, the webhook displays their account information.


--P0z5OHVNjRZyjorr2QVnwmoNnhcZ7KQViJKPAKgPBQFQDV_0yv3fZdcvtioGr2hUMNocbhTcN9yGt1ugfm7siCmx7TPbNAVc66XWvkH9q_MOftKH-VUhGi_9aQu5hdxiWPHBJx

Special Webhooks 

A special webhook uses a reserved phrase and performs a specific function. To use more than one special webhook, you should customize the webhook’s variable name in Settings > For Developers > Webhooks. There are four special webhooks: 

  • replaceWholeResponse
  • carouselResponse
  • browseCarouselResponse
  • gotoBranch

When using these webhooks with text (strings), the text will disappear. For best results, use special webhooks independently, and do not include any texts (string) in the same field.

A Good Example would be :


0Tn6DWESrWBmOq6dsvViY6WCMudKFSfJWrWigWsFFfM_AY8WhrKQXjqchEbJeAQc0YU1PdzeG61TQP2QK9nkHSkKfrf10sQbmCORN67jv6CeUfoXgMWoqCU01QX7nxmw1cuSdjxh

A Bad Example would be :


SaDQS7C0yE-2quNNmKz_M374PunzbsMx5DpYfZcClVh4GBAWw7f7Ka0YNRVOGtClXzXuYLe4ErA-EDFTBb-YEH-UwoKq19QadOma0fK1N8DL23K1Ed8-giVntb3ZVY6HNhi2JMPq

To use text with a special webhook, create another field for the webhook.


Replace Whole Response

Works with: Conversational Bot and Sequence Bot

This webhook replaces the whole response. The JSON object must contain the key "replaceWholeResponse". Use this webhook to show fallback or error messages. Format your webhook in a key-value pair:

{{"replaceWholeResponse":"Sorry, your account balance is `zero`, please deposit some money in it. Thanks."}}

In the following example, the original text ‘Your account balance is {{replaceWholeResponse}}’ will be replaced with the webhook response.


jUCvaBgbR-h-MmOdchs-UPNpzm7WzJqzB4aXBGAGbXE4GfpisYU0tqpPgQlDohSbqogY1PtrlfDhBbxlgNvIln6EsIwy7agfJHSUyCb3dW5ubHF6qADeJ0a1tkDeWiMELNiH1TK7

The customer will only see the webhook response.


TRfwK8k7mmI6mtndiZebVMhtQ_lUmfd5Ac4HFzuDXoPfo8xVPDXtGWwVjGGcN3-68-wyQxW_O8xVqMQhSnuRfpCYHFQJ-P_tTPV6pL29eKG7foL0BzXBcN4UWKkTpAR3LyfMefxk

List Based

List-based webhooks allow you to provide multiple choice responses to your visitors. They may be implemented through carousels and browse-carousels.

Note: For a great user experience, we recommend showing only four responses at a time. 
Carousel Type

Works with: Sequence Bot

Carousel cards contain an image, a title, and description. Format the carousel webhook response with the following key-value pair:

{"carouselResponse":"<Stringify Carousel JSON>”}

Make sure you use the key ‘carouselResponse’. Modify the Carousel JSON as per your use case. For example, a Carousel JSON object may be formatted in the following way:

  

{"carouselResponse": {"id":"carousel_card","design":{"title":"cards", "subtitle":"desc","items":[{"Item_id":1,"title":"<Title here>","desc":"<Description Here>", "imgUrl":"<URL Image Link Here>"}]}}}

To set up a carousel in a Sequence Bot, create a Custom Attribute to save a visitor’s response. Create Custom Attributes in Settings > Account Settings > Custom Attributes. You may validate user inputs for the Custom Attributes using existing validation types, or you may set up custom RegEx.

Note: Why validate user responses? Visitors may still type whatever they want in the widget, which may lead to unexpected results for your Sequence Bot.

 

eC7RWNPY4YWvnb4TfL0UjGsvkIGYD3Ql3DVbrGZFZO4Q_IZR8BguWGaQWyJn_jgDogX0gmqKsE_woZeJsN9Iu4r6KG7aMbOD0i63XFaTCbgtyDc1viRt-NtBXJKAZZVN46cMNV-O

After creating a Custom Attribute, go to Chatbots > Sequence Bot and create a new sequence.

Add your carousel webhook to the sequence. Then, use the ‘Add another action’ button and select ‘Add Visitor Attribute’. Choose the Custom Attribute that will record the visitor’s response. 


Finally, add another action to reply to the customer with the Custom Attribute. In the following example, the customer's choice is held in the Custom Attribute {{remark}}.


AfgS6QXeasCkMoOePYiuwgdEBmoRcL9ZAMNo7hShf_A7i7CSBFlBfTSmfR0xsCekxjp8P7ixFNwcfDH47LjeEvJB4SarTzXkOa3_HoTeQby58QG4DDWwXHAUrxm3WZswh890Ap9q

The bot will display the customer’s choice in the widget.


KhaksNU482mu9L3MAt11aEaJD0b3zj1bzP-0ln0BxtxqqzfKWqaFG3eQM1OJRIVPn4DPVvFdrEniujxGJ10WQwtR9e_YkRIDG0tM2LSxnj5rNlDZeEb_yCpAJ_as1o5hmIDlUdGr

See the gif to get an idea of the flow: 


0bmfgoQy6l7SmFxGeG4av5ILy4dS1hsF-YozZWV7XVb6oA-M5rQZgP1AmbD9f1Jom5_hFd-enHrxZrx7ziylknPMspO5MrawwEyrr6wH--cyQsPKvAXImtelFcNVN3Ct18Em_F7Z

Users will only be able to click on one card at a time.

Browse Carousel Type

Works with: Sequence Bot

Browse Carousel cards have a slightly different design and functionality. They may contain an image, a title, a description, a link, and a footer. Be sure to use the key ‘browseCarouselResponse’ like the example below:

{"browseCarouselResponse":"<Stringify Browse Carousel JSON>”}

Modify the Browse Carousel JSON to suit your use case:


{"browseCarouselResponse": {"id": "browse_carousel_card","design": {"items": [{"title": "<Item Title Here>","desc": "<Item Description Here>","footer": "<Item Footer Here>","openUrl": "<Website link here>","imgUrl": "<Image URL Here>"}]}}}

The card the visitor chooses will redirect them to the openUrl link.

To save your webhook variable, go to Settings > For Developers > Webhooks and press ‘Create New Webhook’.

Paste the webhook name, an email address, and the endpoint. Select ‘Inbound’ and press ‘Refresh Variables’. If the variable does not display, click on ‘Add more variables’ and give the webhook a name.

To use the webhook, go to Chatbots > Sequence Bot and create a new sequence.

In this sequence, a welcome is followed by a browse carousel response. The browse carousel response has been given the custom name {{card}}.


kdAEUSTofO1Im13COOz-Fq4wdwYBdh8JqR35zK_yW_35X2WKnSsQPIY2D5J8vm-UqM-Cor4IS-lt0eXsoZr4CRKOT_wOS-5-82u64HngUnWUJiXz9yBtvHKRxqvE3LZP6G3o0U6t


The webhook will display cards. Once the visitor clicks on the card, they will be redirected to a different site. Note that the text surrounding the webhook will not display. 


v3CKxxrdfTVulGNxrmo2JLAdzrmb02Js9bPYDiRTHN05CHBxw-VTfqNeVTczIbFwctNcHZ5gS8SBMhLmzY16GR9_iTixrruPgF_QQoPQtMAZwE-k3zmGmbbqr24P4FBRNGQuk2Dl

View the gif to get an idea of the flow:


wMpmBsGGhoW8wvCiddiYjEo6ILgPUVVtAUTb8PRrWenJJ8hnQtLl5gz1LmDdtx3Y9h_ZZnk883KpdPY37yf7stmvgYHtMgRgRiBNmUsbAeXT6p49lto5l9iZiiEPAA69g8_I3FNf

Users will only be able to click on one card at a time.

Routing Based

When building a Sequence Bot, it’s sometimes necessary to route a customer to a branch that’s not part of the usual flow. Webhooks may be used to help you direct customers to specific branches in the same bot. To construct the JSON, provide your webhook response with a “gotoBranch” key and the branch ID value.

In the example below, the webhook will transfer the customer to branch 122. Note that the ID is in string form.


{"gotoBranch":"122"}

You will need to know the branch ID you’d like to route to before constructing your webhook. We recommend building out your Sequence Bot and then constructing your webhook.


TH1AIBZ5AUChxgyUsx72CbYySp7zV_3rQeeyrsrrX_a4jXu_3iFi_0eZiFmse94GB5Z1Id9TMegYPl1h-ip8LE77fgW622GHM285re5Pk2nXvOXz-QeJKiooc-ohvzoR5155FpVM

The visitor will be routed to the specified branch. Any text entered in the same field as the {{gotoBranch}} variable will not be displayed.


ICKwwiDmwDvv7HsmZj4AiT_K5jw15kMC3h4rnsbzqGrctYNe4VYeTizZO6jCOFSKGOsMJk02qRue0uWNubMem0gj6hSDGiqYw_1uKQnVe-skPZ9G-uFMwn5XiY6Yf6ysW-qnHNWp

Note: If your sequence does not contain any branch with the ID mentioned, then the bot will ignore the webhook and continue with the remaining flow.

Chat Transfer Based

If you would like to transfer a chat to a particular agent or department during a conversation with a bot, use the chat transfer webhook. You will need the ID of that particular agent or department, which is accessible in Settings > Account Settings > Users and Roles and/or Departments.


The required format is:

{"chatRouteTo":"<Stringify Chat Routing JSON>”}

Modify the Chat Routing JSON to suit your use case. To route to two or more agents or departments, separate the IDs by commas.

Route to agents

{“agentIds”: “11,12”} OR {“agentIds”:”all”}

Route to departments

{“deptIds”: “1,2”} OR {“deptIds”:”all”}

Note: We do not support agentIds and deptIds simultaneously.If both are activated at the same time, agentIds will take precedence.

In the example below, if the visitor chooses the ‘Transfer’ branch, they will be routed to the relevant agent. 

EH4ICommZrQHTRJnFgxmiSv0rvEcd8rSte8_amAwyHN08U1cjoSsFCkI4Cofmhph5R_iSjPkjoXdzBuyRrnjOsKoJPpvNGsk3HpMLgH4QVxqr83VLnkVC2PS82S9Ds_BIwrU90AX

In the visitor’s view, a helpful message lets the visitor know that they’re being transferred to an agent.


zCd2lNUZfl89yF7tnuMZm3LVnF54EvQDfJcf9relPnRW5WzcrTRCr5pczgZsSijUdai-_cea50FzZD3y8J_dwW0KIrtz49XZ_HraeAOqoaahrFcCkCTxf6dUl00FDCSCrYxVt-4b

Setting a Fallback Response

Set a fallback JSON response under “Fallback response, when webhook URL fails”. The system will try to get a response from the original webhook URL three times. If the system does not get a valid response by then, It will send the fallback response.


5vwKFle5g0Jy4mNwIX9v5we5_hT3KufFSe3xoGuHkRhKBajPvqWKUCRg5Ewg1VyJELH1COPl_WwiH5CSEU0gJGIuSW7KZwjcOxBdLkV37ZWDNhlXCJlsyHVX-cQEt_yB0xFUPyr6

Ex. (as shown in the screenshot above)

If the webhook URL fails, the default response will be {{“gotoBranch”: “789”}}.
You can use this functionality for various purposes (i.e. redirecting to a fallback branch in sequence bot OR showing static card items, etc.) 


Webhooks allow you to customize your bot experiences even further. Whether promoting an ever changing list of new products or fluctuating service times, webhooks make these types of interactions possible. Get in touch with your development team and support@acquire.io to see if webhooks are right for your business needs.

 

Webhook Examples

View and use these examples to better understand our webhook format.

  1. String-based Response:
    https://botapi.acquire.io/webhook_responses.php?type=regular
  2. Replace Whole Response:
    https://botapi.acquire.io/webhook_responses.php?type=anything
  3. Go to Branch:
    https://botapi.acquire.io/webhook_responses.php?type=goto&branch=123456
  4. Carousel Card:
    https://botapi.acquire.io/webhook_responses.php?type=carousel
  5. Browse Carousel Card:
    https://botapi.acquire.io/webhook_responses.php?type=browse_carousel



Related Articles