API Adapter

The API Adapter service simplifies the process of integrating existing REST APIs with Parloa. It converts the data from these APIs to a format Parloa can understand, without requiring the deployment of a custom service, provided no additional processing is needed.

For instance, if you have an existing API that fetches user information, the API Adapter can help bring this data into Parloa effortlessly.

Service Configuration

Branches

• success: Service call was completed successfully.

• error: Error when calling the external API.

• error_<whitelistError> (optional): Service call intercepted by an HTTP error that requires different handling. It's activated only when the whitelistError flag is used.

Input

• url: The web address of the API you want to call.

• format (optional): Specifies the data format of the external API. It can be either json or xml. Leave blank if using the "Content-Type" header.

• authToken (optional): Used for Authorization. Leave blank if using the "Authorization" header.

• method: Specifies the HTTP method, commonly GET or POST.

• body:The content of the request, formatted as a string. It may need to be escaped if passed as a JSON object and require a set format flag.

• headers: Additional headers formatted as a JSON-stringified object.

• bodySelector: Specifies which data element from the original response should be returned to Parloa. For example: objects[0].object.

• singleObjectOutput (optional): When set, all output data is wrapped into a single object named outputObject.

• whitelistError (optional): When set, all output data is wrapped into a single object named outputObject. If enabled, the API Adapter forwards the error.response object, corresponding to the specified error code, to Parloa. For smoother dialog flow management, an optional error branch following the format error_<whitelistError> can be used. For instance, specifying "whitelistError" : "400" triggers the error branch "choice": "error_400". Multiple error codes can be listed by separating them with a comma, for example, "whitelistError" : "400, 403, 404".

Output

The output is generated dynamically based on the API used and will match its response object. If the top-most element is not an object, values are returned in a data property.

Technical configuration

• URL: https://parloaservices.azurewebsites.net/api/API-Adapter?clientId=<CLIENTID>

• Header: x-functions-key: <AUTHCODE>

For authentication, replace <AUTHCODE> and <CLIENTID> with the values provided by your Parloa representative.

Examples

GET REST

This example demonstrates calling a JSON GET API and selecting the first data entry as the response:

    "input": {
        "url": "https://reqres.in/api/users",
        "method": "get",
        "bodySelector": "data.0",
        "format": "json"
    }

This generates the following result:

{
    "choice": "success",
    "output": {
        "id": 1,
        "email": "[e-mail]",
        "first_name": "George",
        "last_name": "Bluth",
        "avatar": "https://reqres.in/img/faces/1-image.jpg"
    }
}

POST REST

This example demonstrates calling a JSON POST API and selecting the first data entry as the response:

    "input": {
        "url": "https://reqres.in/api/users",
        "method": "post",
        "bodySelector": "",
        "format": "json",
        "body": "{\"name\": \"morpheus\",\"job\": \"leader\"}"
    }

This generates the following result:

{
    "choice": "success",
    "output": {
        "name": "morpheus",
        "job": "leader",
        "id": "886",
        "createdAt": "2022-07-04T22:17:55.040Z"
    }
}

GET XML API

This example demonstrates calling an XML API:

    "input": {
        "url": "https://gorest.co.in/public/v2/users.xml",
        "bodySelector": "objects.0.object.0",
        "format": "xml"
    }

This generates the following result:

{
    "choice": "success",
    "output": {
        "id": "4003",
        "name": "Bhagvan Banerjee",
        "email": "[e-mail]",
        "gender": "female",
        "status": "active"
    }
}

Using the API Adapter in Parloa Frontend

You can pass input parameters as simple text strings or use storage variables obtained during the conversation.

Using Simple Text Strings for the Input Parameters

Using Information Captured During the Call To Query an Endpoint

The output branches help create alternative conversation flows based on the success or failure of the service call:

How Branches Can Be Used with the API Adaptor

Sending a SOAP Request

The Parloa API Adapter is primarily designed for handling REST requests. However, it can also be used for SOAP requests with some additional steps.

To send a SOAP request, you may need to create the required XML inputs using text or JavaScript strings. Since Parloa's text fields aren't optimized for parsing XML input directly, pasting XML into a text-string field might lead to unexpected outcomes. Therefore, it's advisable to use the JavaScript option to construct and stringify the request parameter.

Here is an example showcasing what this process could look like:

Construction of Input Variables

Using the Constructed Variables in the Input Parameters

For a SOAP request, it's important to leave the 'format' field empty. Instead, you should use a properly stringified JSON object for the headers. This object should be placed in the 'headers' field:

Stringified-JSON Headers for a SOAP Request