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

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:

phoneV2

{
    "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": "[phone]f6dab0adb66dce7fac1d7a--default",
        "platform": "phoneV2",
        "request": {
            "callMeta": {
                "callId": "54cb5639-6e40-123a-4ba8-d094667acbd8",
                "callerId": "[phone]",
                "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"
        }
    }
}

Alexa

{
  "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
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.

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

Example Responses

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

Basic Output

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

responseOverwrites

{
  "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"
      }
    }
  }
}

dynamicEntityOverwrites

{
  "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"
      }
    ]
  }
}