Service Integration Guide

Configuring technical aspects for optimal analytics gathering

URL Configuration

To process requests sent by Parloa, you'll need to define an HTTPS endpoint.

Authentication

Protect your endpoint against unauthorized access by choosing between HTTP Basic Auth and Bearer token authentication. Configure these in the Configuration tab.

Optionally, employ a custom header, such as x-api-key, for an additional layer of security.

Authentication Methods	Required Input
Authorization token	Token
Basic authorization	Username, password

Authentication Methods

Required Input

Authorization token

Token

Basic authorization

Username, password

Headers

Custom headers that will accompany your request can be specified as needed.

Cache Service Response

By enabling the cache for a particular service, you cache responses for the current version. The cache is keyed based on the release, input parameters, and the service URL.

Retry Mechanism

Parloa will attempt a retry if:

A timeout occurs.
The status code is within the range of 502 to 504 or equals 429.
The error code is deemed retryable according to is-retry-allowed.

Retries will persist until they are exhausted, after which standard error procedures take over.

Service Timeout

Customize Parloa's timeout settings between 0ms to 20,000ms by toggling the Override Service Timeout switch on the Service screen.

The default timeout is 4000ms if none is specified.
A specified timeout will take precedence and replace the default setting.

In a timeout scenario, calculate the duration using the formula: service timeout + retries * (service timeout + 50ms), where 50ms accounts for the retry delay.

Service Request

Parloa sends requests in JSON format via HTTP POST, which includes context and input data tailored to the platform.

You are not obliged to process all provided information.

Request Body

The request body sent to your endpoint contains a predefined set of properties, as illustrated below:

Key

Type

Description

context

object

Contains an object with context information.

context.releaseId

string

The Parloa ID of the release which initiated the request.

context.userContextId

string

An internal Parloa ID representing a conversation by mapping the user ID with the release ID.

context.platform

string

The platform interacting with the release. Possible values: -phoneV1- phoneV2 - alexa- dialogflow

context.request

object

The raw request received by Parloa from the platform.

context.conversationId

string

The unique conversation identifier of the current conversation between the user and your bot. You can use it to retrieve the corresponding conversation history.

input

object

Contains the key-value pairs representing the input parameters defined in the correspondingService block.

Be aware that these properties are exclusive to a service call and should not be mistaken for context variables.

Example Request Bodies

The structure of the request body differs based on the platform. Here are examples for phoneV2 and Alexa:

{
    "input": {
        "addressInput": "Münz straße 5 in Berlin"
    },
    "context": {
        "releaseId": "60f6dab0adb66dce7fac1d7a",
        "userContextId": "60f6e59699712c59611f39df",
        "conversationId": "5e68aa33-e0a3-4d3a-b263-10540ef03d21",
        "dialogId": "60f6dab0adb66dce7fac1d7a",
        "dialogVersion": "1",
        "fovConversationId": "+4917612345678-60f6dab0adb66dce7fac1d7a--default",
        "platform": "phoneV2",
        "request": {
            "callMeta": {
                "callId": "54cb5639-6e40-123a-4ba8-d094667acbd8",
                "callerId": "+4917612345678",
                "instanceId": "60f6dab0adb66dce7fac1d7a"
            },
            "intent": {
                "id": -6487798570032697000,
                "name": "TellAddress",
                "confidence": 0.9999997615814209
            },
            "intentRanking": [
                {
                    "id": -6487798570032697000,
                    "name": "TellAddress",
                    "confidence": 0.9999997615814209
                },
                {
                    "id": 4374073288754445300,
                    "name": "CancelIntent",
                    "confidence": 2.335296192534919e-11
                }
            ],
            "slots": [
                {
                    "extractor": "DIETClassifier",
                    "entity": "Address",
                    "confidenceEntity": 0.7132492661476135,
                    "value": "Münz straße 5 in Berlin",
                    "start": 0,
                    "end": 23,
                    "processors": [],
                    "text": ""
                },
                {
                    "extractor": "DucklingEntityExtractor",
                    "value": 5,
                    "confidence": 1,
                    "entity": "number",
                    "additionalInfo": {
                        "value": 5,
                        "type": "value"
                    },
                    "start": 12,
                    "end": 13,
                    "processors": [],
                    "text": "86"
                }
            ],
            "text": "Münz straße 5 in Berlin"
        }
    }
}

{
  "context": {
    "releaseId": "5d4ab7ec5e8a29004109cee4",
    "userContextId": "e8a29004109cee5d4ab7ec54",
    "platform": "alexa",
    "request": {
      "version": "1.0",
      "session": {
        "new": true,
        "sessionId": "amzn1.echo-api.session.7f30f70a-c669-4cd4-9da0-85e1b3bd80cf",
        "application": {
          "applicationId": "amzn1.ask.skill.1004db3c-48e8-4ed3-8204-0fb4512176ec"
        },
        "user": {
          "userId": "amzn1.ask.account.XXQ4QKVHXJKNDQKCQ5P6QXR6YRHCPLJ7TOMOYVUEB3XHGYIXY2YRMEC644CQWTCFAVGD6HIWENTVS2JFXM4PLXWNXGD234H4WPCPIGAUW24RBLE5HOESE5ZETLQE2U47Q6DROCAK4QKGVIFZJL3P7RY4YZNHKYF2ZDZUAKQUJCP7N43YOBPSJ4ZVUJBCR7HDOHF4POYN7C4YODQ"
        }
      },
      "context": {
        "System": {
          "application": {
            "applicationId": "amzn1.ask.skill.1004db3c-48e8-4ed3-8204-0fb4512176ec"
          },
          "user": {
            "userId": "amzn1.ask.account.XXQ4QKVHXJKNDQKCQ5P6QXR6YRHCPLJ7TOMOYVUEB3XHGYIXY2YRMEC644CQWTCFAVGD6HIWENTVS2JFXM4PLXWNXGD234H4WPCPIGAUW24RBLE5HOESE5ZETLQE2U47Q6DROCAK4QKGVIFZJL3P7RY4YZNHKYF2ZDZUAKQUJCP7N43YOBPSJ4ZVUJBCR7HDOHF4POYN7C4YODQ"
          },
          "device": {
            "deviceId": "amzn1.ask.device.XX7BQUB6H6DECNQZDNPD6VNC666K4XIPXXQJFDVXLQSESDCED2OCMXOT4CKGO37BA2AVT6DQ74ZT3GK7GLAO4FYEISL5Y3Y6FLQ2Z2CUKC7YZ4I3YTDAYXG5JRUQZ3F2KJWA42KDI4PR3PSA6PI7TSZYLOQCZP7VZ6PQZ27N3WEGNP3W2632M",
            "supportedInterfaces": {}
          },
          "apiEndpoint": "https://api.eu.amazonalexa.com",
          "apiAccessToken": "eyJ0eXXiOiJKV1XXLCJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJhdWQiOiJodHRwczovL2FwaS5hbWF6b25hbGV4YS5jb20iLCJpc3MiOiJBbGV4YVNraWxsS2l0Iiwic3ViIjoiYW16bjEuYXNrLnNraWxsLjFhMzRkYjNjLTQ4ZTgtNGVkMy04MjA0LTBmYjQ1MTIxNzZlYyIsImV4cCI6MTU2NTE3ODY0NSwiaWF0IjoxNTY1MTc4MzQ1LCJuYmYiOjE1NjUxNzgzNDUsInByaXZhdGVDbGFpbXMiOnsiY29udGV4dCI6IkFBQUFBQUFBQVFESmZScEl0bEgybjArZERQVFk2SURyS3dFQUFBQUFBQURCeUVBUHdvTXRjM2NtRExVY2t4ZWs4ekl0QzMyb2UzazIrc2J5UXE5ajJrbXZiem1Rb3RKcjdBTEhDTWw4SHJyNmZLMGNiRTRPMElOSGNTNCs2Z3p5RW16NmtnV2k2QjdFSDA5L2RNN1gyTnBiY25pRFZnOUVmdmNROHpoR2UwL3RjYk5IalBRelY2VWVPSFMxbEhMSGU4TDJ2a3FXS1VPRlFBdFU0Qkt2eklVVHhndURhS2JlOWFPTjNoSDFYalRuZkVHTFArNEVDZUZza093RjdZOS8xZk96ZWRGVWY1UTg1cHRuV0k5cHlTbEdFNGVQVnIrNjRBY2wvaDJ6bHVCM3lHbC9NbGxSQjN4ZkFzQjFHRHdENlVUcDJkb29BL0JTeTVPdXNkTzQ4aW1vc0JxRUZaL3Vwai82cXc3ZjU4TGNmcHQ5aGcwazBGeVgzY3ZQbWw4YmtNL2pXSUVKV1BRRHFETi8vbzlPemIrWUtRVGdEZXJxWTFkem9jVkRLTjNuR3lwUDB0MXRML0c3cnc9PSIsImNvbnNlbnRUb2tlbiI6bnVsbCwiZGV2aWNlSWQiOiJhbXpuMS5hc2suZGV2aWNlLkFFN0JRVUI2SDZERUNOUVpETlBENlZOQzY2Nks0WElQWFhRSkZEVlhMUVNFU0RDRUQyT0NNWE9UNENLR08zN0JBMkFWVDZEUTc0WlQzR0s3R0xBTzRGWUVJU0w1WTNZNkZMUTJaMkNVS0M3WVo0STNZVERBWVhHNUpSVVFaM0YyS0pXQTQyS0RJNFBSM1BTQTZQSTdUU1pZTE9RQ1pQN1ZaNlBRWjI3TjNXRUdOUDNXMjYzMk0iLCJ1c2VySWQiOiJhbXpuMS5hc2suYWNjb3VudC5BRlE0UUtWSFhKS05EUUtDUTVQNlFYUjZZUkhDUExKN1RPTU9ZVlVFQjNYSEdZSVhZMllSTUVDNjQ0Q1FXVENGQVZHRDZISVdFTlRWUzJKRlhNNFBMWFdOWEdEMjM0SDRXUENQSUdBVVcyNFJCTEU1SE9FU0U1WkVUTFFFMlU0N1E2RFJPQ0FLNFFLR1ZJRlpKTDNQN1JZNFlaTkhLWUYyWkRaVUFLUVVKQ1A3TjQzWU9CUFNKNFpWVUpCQ1I3SERPSEY0UE9ZTjdDNFlPRFEifX0.PozFsIY356WdQUZAwwXTLdb7xTqGdtbFDJJGz5WVSzZ8hAbHfd6_R7enJnTTsft_44Lrokn53nfCuITeBcf903twHcH5_FzimlGd0_n38ySTmJBnnVQS1eVAPe7PqnE_r0cuxOcsj-SOwfCvONmXC_lkehjGEao749LFPlJeKlgyoOLvtGY-SMA908MZAfx4Gr3eicSgoUWZ6cIetIxHGbwgFvdfqwahhwEM9fwypSwzh9H6YcQepK-N1nVDPajMWsXyMuANZQuXKpMim4YdTx8HjAXFFHe53PxcmweN37GnFVHrcFTST7bf_x8gfVM-NjQEeXgIRHPqUKpx0dnM5Q"
        },
        "Viewport": {
          "experiences": [
            {
              "arcMinuteWidth": 246,
              "arcMinuteHeight": 144,
              "canRotate": false,
              "canResize": false
            }
          ],
          "shape": "RECTANGLE",
          "pixelWidth": 1024,
          "pixelHeight": 600,
          "dpi": 160,
          "currentPixelWidth": 1024,
          "currentPixelHeight": 600,
          "touch": [
            "SINGLE"
          ],
          "video": {
            "codecs": [
              "H_264_42",
              "H_264_41"
            ]
          }
        }
      },
      "request": {
        "type": "LaunchRequest",
        "requestId": "amzn1.echo-api.request.3f090e9c-cd9e-4804-9a3b-a3d42c218e17",
        "timestamp": "2019-08-07T11:45:45Z",
        "locale": "en-GB",
        "shouldLinkResultBeReturned": false
      }
    }
  },
  "input": {
    "roomName": "Batman",
    "duration": "20"
  }
}

Service Response

Parloa anticipates a 200 HTTP status response in JSON format.

Response Body

Parloa expects to receive a response body structured as follows:

Key Required Type Description

Key	Required	Type	Description
`choice`	Yes	string	The name of the branch that should be followed after the `Service` block.
`output`	Yes	object	An object containing key-value pairs that match the output defined in the code output configuration.
`responseOverwrites`	No	object	An object which can contain key-value pairs where the key is the platform name and the value is an object representing a partial response for the platform which will be merged with the response generated by Parloa. Please take into account that no deep-merging will be performed and high-level keys defined in the response will overwrite those set by Parloa. Possible platform keys: - `alexa` - `phoneV1` - `dialogflow`.
`dynamicEntityOverwrites.alexa`	No	UpdateDynamicEntities[]	A list of UpdateDynamicEntities directives. They are expected in the Alexa specific format. If provided they will be written into the Parloa generated Alexa response. ℹ️ The uploaded dynamic entities time out after 30 minutes on Alexa.
`dynamicEntityOverwrites.<dialogflowPlatform>`	No	SessionEntityType[]	A list of SessionEntityType. They are expected in the Dialogflow specific format. If provided they will be written into the Parloa generated Dialogflow response. Possible Dialogflow platform keys: - `dialogflow` - `phoneV1` - `whatsapp`
`speechToTextHints`	No	string[]	An array of words of phrases to be used as hints during speech recognition of `phoneV2` releases.

choice

Yes

string

The name of the branch that should be followed after the Service block.

output

Yes

object

An object containing key-value pairs that match the output defined in the code output configuration.

responseOverwrites

object

An object which can contain key-value pairs where the key is the platform name and the value is an object representing a partial response for the platform which will be merged with the response generated by Parloa. Please take into account that no deep-merging will be performed and high-level keys defined in the response will overwrite those set by Parloa. Possible platform keys: - alexa

- phoneV1 - dialogflow.

dynamicEntityOverwrites.alexa

UpdateDynamicEntities[]

A list of UpdateDynamicEntities directives. They are expected in the Alexa specific format. If provided they will be written into the Parloa generated Alexa response.

ℹ️ The uploaded dynamic entities time out after 30 minutes on Alexa.

dynamicEntityOverwrites.<dialogflowPlatform>

SessionEntityType[]

A list of SessionEntityType. They are expected in the Dialogflow specific format. If provided they will be written into the Parloa generated Dialogflow response.

Possible Dialogflow platform keys: - dialogflow

- phoneV1 - whatsapp

speechToTextHints

string[]

An array of words of phrases to be used as hints during speech recognition of phoneV2 releases.

Response Timeout

An external service must respond within a given timeout with a successful status code, otherwise, Parloa will delegate the control to the error branch. For more information, please refer to Parloa Errors.

Release Types	Response Timeout
Dialogflow	4 Seconds
Whatsapp	4 Seconds
PhoneV1	4 Seconds
PhoneV2	9.5 Seconds

Release Types

Response Timeout

Dialogflow

4 Seconds

PhoneV1

4 Seconds

PhoneV2

9.5 Seconds

Example Responses

Here you can find a sample response for the basic return of data, responseOverwrites and for dynamicEntityOverwrites:

{
  "choice": "success",
  "output": {
    "formattedAddress": "Münzstraße 5, 10178 Berlin"
  }
}

{
  "choice": "booksFound",
  "output": {
    "firstTitle": "Albert muss nach Hause"
  },
  "responseOverwrites": {
    "gaction": {
      "systemIntent": {
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
          "listSelect": {
            "items": [
              {
                "title": "Albert muss nach Hause",
                "description": "Homer Hickam - 2016",
                "image": {
                  "accessibilityText": "Cover Image",
                  "url": "https://storage.googleapis.com/content/Albert_muss_nach_Hause/CoverImage.png"
                },
                "optionInfo": {
                  "key": "Albert_muss_nach_Hause",
                  "synonyms": [
                    "Albert muss nach Hause"
                  ]
                }
              },
              {
                "title": "Das Fundament der Ewigkeit",
                "description": "Ken Follett - 2017",
                "image": {
                  "accessibilityText": "Cover Image",
                  "url": "https://storage.googleapis.com/content/Das_Fundament_der_Ewigkeit/CoverImage.png"
                },
                "optionInfo": {
                  "key": "Das_Fundament_der_Ewigkeit",
                  "synonyms": [
                    "Das Fundament der Ewigkeit"
                  ]
                }
              }
            ],
            "title": "Hörbuch Liste"
          }
        },
        "intent": "actions.intent.OPTION"
      }
    }
  }
}

{
  "choice": "booksFound",
  "output": {
    "firstTitle": "Albert muss nach Hause"
  },
  "dynamicEntityOverwrites": {
    "alexa": [
      {
        "type": "Dialog.UpdateDynamicEntities",
        "updateBehavior": "CLEAR"
      },
      {
        "type": "Dialog.UpdateDynamicEntities",
        "updateBehavior": "REPLACE",
        "types": [
          {
            "name": "food",
            "values": [
              {
                "id": "fruit",
                "name": {
                  "value": "fruit",
                  "synonyms": [
                    "apple",
                    "banana"
                  ]
                }
              },
              {
                "id": "ice",
                "name": {
                  "value": "ice",
                  "synonyms": [
                    "ice cream"
                  ]
                }
              }
            ]
          }
        ]
      }
    ],
    "dialogflow": [
      {
        "name": "food",
        "entities": [
          {
            "value": "fruit",
            "synonyms": [
              "apple",
              "banana"
            ]
          },
          {
            "value": "ice",
            "synonyms": [
              "ice cream"
            ]
          }
        ],
        "entityOverrideMode": "ENTITY_OVERRIDE_MODE_OVERRIDE"
      }
    ]
  }
}

PreviousServices NextService Development

Last updated 5 months ago