Articles

See more

Sending data to your Josef bot

  • Updated

On Josef, you can retrieve information from a third-party datasource to be integrated with your bot. This can be done using an API. 

(For the non-developers!) API stands for ‘Application Programming Interface’, and you can think of it as a tool that sits on your website which allows two applications (Josef and your datasource, for example) to talk to each other. 

In this article, we’ll share how to set up an API request so your Josef bot can retrieve information from your datasource and display the information to your users. Here's an example bot demonstrating this functionality. 

Broadly, there are three steps required to integrate data from your systems with your bot. 

  1. Create an API
  2. Create an API request message-type and/or response-type in Josef 
  3. Configure the response 

Steps 1 and 3 happen outside of the Josef dashboard and require configuring your systems, so you may need help from your IT team. You can direct them to this article. If you need help, feel free to get in touch with us at support@joseflegal.com.

Create an API 

The first thing we need to do is to create an API. This is typically created on your website. You can ask your IT team or consult a developer to build the API for you. 

We can also help you create an API! If this is of interest, please reach out to us at support@joseflegal.com to discuss your requirements. We can then provide you with a timeline and cost estimate. 

Create an API request message-type and/or response-type in Josef

Once your API is created, it will have a website URL which you can enter into your Josef bot.

To use this in your bot, first create your API request message or response in Josef. Log-in to the Josef dashboard and select your bot. Then: 

  1. Head to Listview or Flowchart.
  2. Create a new message.
  3. If you wish to retrieve a message from your API for your bot to say, then select from the drop-down menu the message type ‘API request’, and enter in your API URL. 
  4. If you wish to retrieve single-choice option(s) for a user to select from your API, then select from the drop down menu the response type 'API request'. Enter in your API URL.
  5. You can use the same API URL for the message and the response request, alternatively build two separate API endpoints. 
  6. Click ‘Create’ to finalise your message. 

Example URLs

You can use our example URLs to see this in action in your own bot.

Use the following for a API request message type:

https://au.api.joseflegal.com/api_request_statement

Use the following for a API request response type: 

https://au.api.joseflegal.com/api_request_select

Configure the response 

When a bot interaction reaches an API request message, your bot can send response(s) from the user interaction to the API. The API will speak to your datasource and get the information you need based on the user’s answer(s). 

You can configure the bot to return a single-choice response and/or a text-type message.

You’ll be able use the information from your system to build logic in your bot as you do with other messages. 

You’ll need to explain to your IT team what information you would like sent to your bot based on the responses provided by your users. 

For example, in a public-facing intake bot, your bot could ask the user what area of law they need help with. Then the API could retrieve contact information for a lawyer who can help the user. The information you would need to provide to your IT team would be: 

  • Input: possible areas of law
  • Output: text-type message containing contact information of lawyers with expertise in those areas of law

Your IT team can use the information below to configure the API. If you have any questions, feel free to reach out to us at support@joseflegal.com.

For developers 

When a bot interaction reaches an API request message, a GET request to a third party server is sent. The request can contain answers from the user interaction as arguments to filter requested data.

If a response from the server matches the required format, data in the response is displayed to the user as a message/question. You will also be able to use the data from the API to build logic in your bot as you do with other messages.

Note: Please make sure that CORS are enabled for your API. See instructions here: https://enable-cors.org/server.html

 

Example

Here is an example of a request that gets data from a datasource that is accessible via www.example.com URL. The data in this example is filtered with filter a & b using responses x & y as values for the corresponding filtering criteria.

GET request: www.example.com?filter_a={{answer_x}}&filter_b={{answer_y}}

Expected response:

 

{

   "type" : "statement",

   "message" : "Information from the third-party server.",

}

 

or

 

{

   "type" : "select",

   "possible_answers" : [

       {"text" : "Yes, continue"},

       {"text" : "No, tell me more"}

   ],

}

Related articles