custom integrations

/* Title: Custom Integrations Sort: 2 */ 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

  • Add the Base URL Details

  • Add Headers

  • Choose Authentication method

  • Save the Base URL

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 :-

  • Select a Base URL

  • Add Request details

  • Add Request Parameters

  • Add Response Definitions

  • Save the Request

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.

PreviousManaging IntegrationsNexttemplate integrations

Last updated