Custom Integrations

Custom Integrations allow you to build an interface between your conversational assistant and a third-party API. You can collect information and then call the Integration in a Flow.

A Custom Integration consists of two main parts - a Base URL and one or more Integration Requests.

Base URL

A Base URL is the starting point for an Integration in Humley Studio. This will centre around the URL and other common details (e.g. headers and authentication credentials) of the API you will be connecting to. The API's documentation should specify these requirements.

To build a Custom Base URL, follow these steps :-

Select an Integration Type

From the Integrations page, click Create Integration

In the sidebar, choose the Custom Integration type.

Add the Base URL Details

Specify details for the Base URL.

Enter in the sidebar -

  • Name
    Give the Base URL a name. All Base URL names must be unique within the Project.

  • Description (optional)

  • URL
    The first part of the URL that will become the base of all calls to that API.

Add Headers

Specify the headers, if applicable, for the Base URL. These consist of name and value pairs.

Enter in the sidebar -

  • Headers (optional)

Choose Authentication method

Specify the authentication method & details for the Base URL. These will be inherited by all the Base URL's child requests, although you can choose to change them in those requests if necessary.

Enter in the sidebar -

  • Authentication Type
    No Authentication
    The default.

    Basic Authentication
    Selecting this will require you to enter a Username and Password that will be used by the API for authentication.

    API Key
    Selecting this will require you to enter an Authentication Type, Key Location, Key Name and Key Value that will be used by the API for authentication.

    Token Authentication
    Selecting this will require you to enter a Request URL, Headers (if applicable), Authentication Type, Request Type, Token Location and Token Node that will be used to create a bearer token that will be used by the API for authentication.

Save the Base URL

Save your new Base URL.

Click Create Base URL to save your new Base URL

The Base URL for your new Integration will be shown on the Integrations list page. As the newly-created Base URL has no child Requests, the Create Request sidebar will be open ready for you to create one.

Integration Request

A Request must have a parent Base URL, from which it inherits the start of its URL (e.g. https://example_service/api/), and can inherit authenticatiom and headers (if they exist).

A Request also contains other information such as -

  • The RESTful API method (e.g. GET, POST etc.)
  • The endpoint (the remaining part of the URL, which usually contains what you're asking the API to do, and the parameters that you're passing to it)
  • Request Parameters (the pieces of information you're passing to the API)
  • Response Definitions (the pieces of information you expect to receive from the API)
  • Authentication details (if you're not inheriting them from the Base URL)
  • Headers (if you're not inheriting them from the Base URL)

The API's documentation should specify these requirements.


In the following step-by-step example, we will :-

From the Integrations page, click Create Request

Select a Base URL

Select a Base URL which you intend to base the Request upon.

Enter in the sidebar -

  • Base URL Select a Base URL from the dropdown list and click Next

    If no Base URLs exist, or you need to create a new one, click Create Base URL and follow the instructions in Add the Base URL Details section above

Add Request details

Give the Request a name, define what API method it will be using, add the endpoint, and either inherit the authentication & headers from the Base URL or redefine them here.

Enter on the page -

  • Name
    Name the Request. All Request names must be unique within the Project.

  • Description (optional)

  • Request Type
    Select an HTTP method to call the API

  • Endpoint
    The remaining part of the URL that will be used to call the API Any request parameters included in the endpoint URL must be enclosed in curly braces e.g. update_record?record_id=102345&{request_def1}&{request_def2}

  • Body
    Enter the body of the request
    This is only available when a PATCH, POST, or PUT request type is selected.

Add Request Parameters

Define the names of the parameters that you may need to include in the API request's endpoint. These will hold data that will be passed to the API.

Click the Request Parameters section to expand it.

Click Create Parameter

Enter in the sidebar -

  • Parameter Name
    Name the parameter. All parameter names must be unique within the request.

  • Help Text
    Enter help text. This will be displayed as a tool tip to give more information about the request parameter within Integration modules in Flows.

  • Mandatory Parameter checkbox
    Defaults to checked
    Check if this parameter needs to be present in the API endpoint.

    If parameter is not mandatory (checkbox is unchecked), another checkbox is shown -

    • Remove Parameter checkbox
      Defaults to checked
      Check if this parameter is to be removed from the request if it is not populated with a value i.e. NULL

      If parameter is not to be removed (checkbox is unchecked), a further field is shown -

      • Default Value field
        Enter a value that the parameter will be defaulted to if the value is NULL

In the sidebar, click Create Parameter to save your new request parameter.

Your new request parameter will be shown in the Request Parameters section's list.
Create more as needed by clicking Create Parameter at the bottom of the list.

Add Response Definitions

Define the names of the response definitions that will capture any data passed back from the API.

Click the Response Definitions section to expand it and then click Create Definition

Enter in the sidebar -

  • Definition Name
    Name the definition. All definition names must be unique within the request.

  • Help Text
    Enter help text. This will be displayed as a tool tip to give more information about the response definition within Integration modules in Flows.

  • Capture entire JSON checkbox
    Defaults to unchecked
    Check if you want to set the value of this response definition to the entire value of the JSON returned. Do this, for instance, if you want to select the values of individual keys, using JSON notation, within a Flow where the Integration was called.
    Using this option will grey out the JSON Node field below.

  • JSON Node
    Enter the name of the JSON node (what it's called on the API side) that will be passing back the data you want to store against this response definition

Click Create Definition to save your new response definition

Your new response definition will be shown in the Response Definitions section's list. Create more as needed by clicking Create Definition at the bottom of the list.

Save the Request

Click Create Request

The new Request will be shown on the Integrations list page under its parent Base URL.

Still need help? Get in touch!
Last updated on 20th Jul 2020