You can integrate Josef into your workflows in various ways.
In this article, we’ll explain how you can use webhooks to send data from Josef bots to other applications that you use.
Once you have your webhook URL, reach out to us at firstname.lastname@example.org and we’ll link it to your bot.
What are webhooks
Webhooks are one way that Josef sends automated messages, information or documents to other applications.
Webhooks allow you to send real-time data from Josef to another application whenever a specific event occurs.
Whenever that event occurs, data is sent from Josef to the receiving application that handles the data. Here’s a visual representation of what that looks like:
This exchange of data happens over the web through a “webhook URL.” A webhook URL is a web address provided by the receiving application for Josef to send data to.
One way to understand this is to think about the webhook URL as a phone number that Josef can call when an event happens.
If the phone number is correct, Josef sends data about the event to the webhook URL in either JSON or XML format. This is known as the “payload.”
How you can use webhooks
By adding a webhook URL to your bot, Josef will send a POST request to the designated webhook in the receiving application, when a specific event occurs.
On Josef, the event that triggers this request is a completed interaction.
A completed interaction takes place when a user reaches a final message in your bot.
Only when a user reaches a final message will the bot send the payload to the webhook URL. Incomplete interactions – where the user does not reach a final message – will not trigger a request.
When a completed interaction occurs in a bot that is set up to send data to a webhook URL, the data will be sent in JSON format, according to the schema below.
A Josef payload uses the following parameters:
- “account” contains information about the user account in which the bot is housed, including the user’s name, email address and the bot styles they use
- “issue” contains information about the bot, including its name, the introductory message, and the bot’s universally unique identifier (UUID)
- “answers” contains a full record of the interaction, including mapping the messages sent by the bot and the responses given by the user
- “user documents” contains URLs for user generated documents
Below is a sample JSON payload that contains data with the “account”, “issue”, “answers” and “user documents” parameters.
"name": "John Doe",
"name": "My Josef Bot",
"Name": "Jane Doe",
"Address": "123 Example Street, Melbourne",
"Occupation": "Legal Technologist",
"Description of request": "Bot interaction completed",
"Looping message": "First response|Second response|Last response"