Backend integration
When implementing the REST web service for a server-side integration, follow these guidelines.
Connection URL
For security considerations, outgoing traffic is only allowed on port 443, using HTTPS.
Please contact your Nuance Mix representative if you need a different connection option.
Certificate
When implementing your HTTPS REST service, you must provide a standard certificate, for example, using Let’s Encrypt . Otherwise, connecting to the web service from Dialog will not be allowed.
Custom private certificates cannot be used.
Date header
The Dialog service adds a standard HTTP Date
header as part of the HTTPS request to your service.
This header contains the date and time at which the request originated, in the GMT time zone.
The header uses the following format:
Date: <day-name>
, <day>
<month>
<year>
<hour>
:<minute>
:<second>
GMT
Where:
<day-name>
is the three character day of the week, for example, “Mon”, “Tues”, “Wed”, and so on.<day>
is the day of the month using two digits. For example, “01”, “02”, “03”, and so on.<month>
is the three character English month abbreviation. For example, “Jan”, “Feb”, “Mar”, and so on.<year>
is the four digit Gregorian calendar year. For example, “2020”, “2021”, and so on.<hour>
,<minute>
, and<second>
give the hour (24 hour clock), minute, and second, respectively, of the GMT time, using two digits each.
For example:
Date: Mon, 27 Nov 2023 16:53:00 GMT
Supported methods
The Dialog server currently handles the following methods:
POST method
The POST method requires as input, and output, a JSON map of objects.
Input
The POST method requires as input a JSON map of objects: the variables configured in the Send Data section of the data access node.
For example, for the coffee app, the request sent by the dialog application might look as follows:
POST /coffee/price HTTP/1.1
Host: coffee.app.com
Content-Type: application/json;charset=UTF-8
{
"COFFEE_TYPE": "cappuccino",
"COFFEE_SIZE": "medium"
}
Output
The POST method requires as output a JSON map of objects: the variables configured in the Get Data section of the data access node.
The returned payload must include the following variable: returnCode
This variable indicates whether the query was successful and will be used by the dialog flow as follows:
- A
returnCode
of “0” indicates that the transaction was successful; the dialog flow will continue to the node specified in the Success section of the data access node. - Any value other than “0” indicates that the transaction failed; the dialog flow will continue to the node specified in the Failure section of the data access node.
For example, for the coffee app, the dialog application would expect a response similar to the following:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 21 May 2020 14:04:00 GMT
{
"returnCode": "0",
"coffeePrice": "2.85"
}
Note:
The middle layer handling the web service can easily convert the POST request into any other request required by the backend or database.Example
This Java example for a coffee app returns coffee prices based on coffee size and type.
GET method
The GET method is used to retrieve information from the backend.
As a best practice, use a standard GET method, that is:
- Input: You can send Mix.dialog variables as URL parameters; see Specify URL parameters for details. These variables must be configured in the Send Data section of the data access node.
- Output: As with the POST method, the GET method must return as output a JSON map of objects. See POST method output for details.
Specify URL parameters
You can pass Mix.dialog variables as URL parameters in a GET request by specifying the variable name in curly braces in the URL Extension field.
For example, to pass the values of the COFFEE_TYPE
and COFFEE_SIZE
variables, specify them in the URL Extension field of the data access node as follows:
/coffee/price?coffee_type={COFFEE_TYPE}&coffee_size={COFFEE_SIZE}
The dialog engine resolves the value of any variable in curly braces, so you can use variables in the endpoint path as needed. For example:
coffee/{myVar1}/{myVar2}
coffee/price?{myVar1}={myVar2}
coffee/{myVar1}/price?par1={myVar3}
The variable values will be URL-encoded when used as URL query parameters. For example, the variable value 7/31/2021 5:15pm
will be automatically encoded to 7%2F31%2F2021%205%3A15pm
by the dialog engine.
Note:
The dialog engine supports query parameters of type string only. In addition to specifying the desired variables in the URL extension, you must also pass them as Send Data parameters in the data access node.Dialog service mTLS support
Dialog service supports mTLS with client X.509 certificates to give additional security for backend integrations. This allows you to verify that the backend data request actually comes from the expected source.
Confirm Nuance-hosted Dialog service as sender
Dialog service sends a certificate. Perform the following checks on the certificate:
- Verify the certificate CN name, which should be
backend.dlgaas.nuance.partner.azure.com
- Verify that the certificate is signed by a valid Microsoft Azure issuing CA. For more details, see Azure Certificate Authority Details . Note that the CA in the path will change regularly. See Certificate lifecycle for details.
Confirm that request comes from expected application
The request from Dialog also includes the application Mix App Id in the HTTP header as x-nuance-application-id
. This allows you to verify that the request is coming from your own Dialog application and not that of another organization.
Recommended approach
By creating an integration layer consisting of a cloud function and a key-value store between Dialog and your web service, you can receive requests and authenticate the source of the request before passing it along to your web service to fetch the data.
Nuance recommends the following approach:
- Create a cloud function, whether using an Azure function, AWS Lambda, Power Automate flow, or other similar mechanism.
- Create an Azure Key Vault, AWS Key Management, or similar to store any authentication credentials (for example, OAuth) for your web service.
- Configure your Dialog data access node to call the cloud function, rather than your web service directly.
- The cloud function validates the certificate and app Id received from the Dialog service. If these are as expected, it forwards the request to your web service. The function returns the data that comes back to Dialog.
The diagram below illustrates in brief how this works.
Certificate lifecycle
Certificates are created with a validity period of three months and replaced 40 days before the end of that period.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.