How to return a chat transcript from a webhook
Last updated: 02 May 2023
There are two types of webhooks available in your chatbot platform. The first is simple webhooks which, once hit, allow you to trigger a conversation.
The second is action webhooks. When hit, action webhooks will:
Execute the webhook (allowing you to trigger a conversation, for example), and,
Perform an action back to the sender.
At the time of writing this tutorial, there is only one action webhook available: chat transcript. This action allows you to, when hit, return a chat transcript back to the sender.
Let's see how to set this up.
Step 1: Choose and create a unique identifier
Chat transcripts are, of course, tied to a specific chatbot user. To return the right chat transcript, we need to identify the right user first.
To do so, we will create a variable to store a unique identifier. This identifier is of your choosing and should be:
Unique to the chatbot user
Hard to guess
Something you store in your database
For example, let's say you own a gym. Your chatbot users, aka your gym members, must identify before talking to the bot using their gym membership ID. This membership ID is a great identifier, which we could use to recognise the user and capture their chat transcript.
For the purpose of this tutorial, we'll continue on with the gym membership ID.
Go to Settings → Variables. Click + Variable.
Give your variable a name and hit Save.
Why can't I use a built-in variable such as `subscriber.identifier`? There are two reasons we don't allow built-in variables as unique identifiers.
The first is built-in variables such as `subscriber.identifier` are too easy to guess. Chat transcripts may include sensitive information, we want to make sure exporting them is secure.
The second is we need the unique identifier to be something you store on your end. This ensures the identifier is cross-checked with a third-party (your application) before this process can execute.
Step 2: Store the identifier in your variable
With this variable handy, we now need to store the identifier of every user talking to your chatbot.
This could be as simple as asking them for their membership ID the first time they talk to your bot, or more streamlined using an API integration that would automatically store this value.
Regardless of how you are storing this value, it is imperative it is done before you execute your webhook. Without the value stored, the webhook will not return anything.
For the purpose of this tutorial, let's take the simpler approach of storing the value as the user first engages with the chatbot.
Go to the Builder.
Find your welcome conversation. Create a step asking the user to enter their membership ID.
Create a second step thanking them, with a simple if a message is sent transition.
Drag and drop a variable into the transition and select your unique ID variable.
Great! We now know exactly which user is talking to the chatbot at any point in time. We can use this information to return the chat transcript when needed.
Step 3: Create your action webhook
Go to Integrations and click Add webhooks.
Give your webhook a name and a refering URL. In the dropdown, select Return subscriber transcript.
Click the new dropdown and select your unique ID variable.
Click Save.
Step 4: Execute the webhook
Almost there!
Your new webhook URL, including its key, is now available.
Grab this URL and append:
The identifier (dynamically) to the URL such as
gym_membership=123.The channel as a parameter to the URL, too, such as
channel_driver_name=Converse(or Embedded, or Full-page).
Your final webhook should look something like: https://demo-api.website.io/api/webhook?key=aaaaaa-2222-2222-22vb22-1099102jda&channel_driver_name=Converse&gym_membership=123
You're now ready to hit this webhook.
Step 5: Return the chat transcript
Your transcript will return in the following JSON format:
{
"messages": [
"[14:17:17] Visitor: hello there",
"[14:17:17] voluptas Bot: hello how can I help"
],
"chatbotName": "My Chatbot",
"channel": "Converse",
"startDate": "05-12-2022 02:17pm",
"exportDate": "05-12-2022 02:17pm",
"variables": {
"subscriber_identifier": "abc-xyz-123",
// any other variables set in the conversation
}
}