Service Development

Developing Custom Services for Integration with Parloa

Interface Requirements

For seamless integration, Parloa mandates adherence to a specific request-response format within the dialog graph.

HTTP Request

Parloa issues an HTTP POST request to the service URL defined within your configuration, carrying a JSON payload that includes additional headers as outlined in the technical settings. The request body, structured as shown below, contains dialog-generated variables and meta information about the interaction:

{
    "input": {
        "input_name_1": "value from dialog",
        "input_name_2": "another value from the dialog"
    },
    "context": {
        // Additional context information
    }
}

The variables generated during the graph execution are provided in the input property as string values. Further meta information about the dialog and the interaction is provided in the context field.

Expected Response

A response with an HTTP status code of 200 is mandatory, with any other codes signaling a fault that redirects to the error branch. For predictable errors, like invalid inputs, send a status code of 200 with an error message in the body. The expected response JSON format is:

{
    "choice": "success",
    "output": {
        "result_var_1": "data content",
        "result_var_2": "further information",
        "result_object": { ... }
    }
}

It is crucial that the choice field is present in the response, as this determines which path to follow in the dialog graph. Information from the service, required for the subsequent dialog execution, must be provided in an output object. These values can then be easily copied to a storage variable in Parloa. In this context, it is also possible to return non-string values, which requires further processing in Storage blocks with JavaScript to extract relevant values for use in other contexts.

Important Considerations

• High Availability – Ensure that the APIs have a maximum response time between 4-9 seconds, depending on the platform the bot runs on. See Timeout for more information.

• Avoid Downtimes – For instance, during deployment. Invest in a zero-downtime deployment process, or use another approach to ensure that the API endpoints are always available. Otherwise, ongoing bot dialogs may fail.

• Input Strings Only – Only string values can be sent out of Parloa. You can, however, JSON-stringify objects or arrays if needed, and process them accordingly in your service.

• No Global State – Parloa cannot store information from the service requests beyond the current dialog execution.

• Authentication – Static authentication methods, such as basic authentication and API key headers, are supported out of the box. See Authentication for more information.

Parloa's Services

Parloa offers a suite of common services ready for use. Familiarize yourself with Parloa's Services, including the API Adapter service which adapts existing APIs to Parloa's expected format.

Sample Code

Visit our GitHub repository for service examples which can serve as templates for your service development: https://github.com/parloa/services-examples​