Passing in session data

In addition to data specifically requested by data access actions as part of the dialog flow, you can also send different types of data as desired from the client application to the Dialog service.

This data can include:

• Predefined variables: values for reserved Dialog predefined session variables
• clientData: Map of client-supplied key-value pairs to put into the Dialog event logs
• user_id: Unique ID for the current end user
• Values for customer-defined variables in Mix.dialog

The data can be sent to Dialog as part of the payloads of various runtime methods. Each type of data can be sent in the payload of one or more runtime API calls.

Predefined variables

Values for some Dialog Predefined variables can be set in the data field of a StartRequest payload or an UpdateRequest payload.

This includes:

• userData
• ExternalResourceReferences
• language and channel
• channelIntegration

userData predefined variable

All dialog projects include the userData predefined variable. The userData variable provides end user data such as the user’s timezone, location, and so on.

The JSON code samples below show how to pass userData in the StartRequest and UpdateRequest payloads. This data can then be used in the dialog application.

Here is an example of a StartRequest payload with session data:

{
  "selector":
  {
    "channel": "default",
    "language": "en-US",
    "library": "default"
  },
  "payload":
  {
    "data":
    {
      "userData":
      {
        "timezone": "America/Cancun",
        "userGlobalID": "123123123",
        "userChannelID": "163.128.3.254",
        "userAuxiliaryID": "7319434000843499",
        "systemID": "4561 9219 9923",
        "location":
        {
          "latitude": "21.161908",
          "longitude": "-86.8515279"
        }
      },
      "preferred_coffee": "espresso",
      "user_name": "Miranda"
    }
  }
}

Here is an example of an UpdateRequest payload with session data:

{
  "session_id": "27f8e613-f624-429b-8c11-d2465dbc2692",
  "payload":
  {
    "data":
    {
      "userData":
      {
        "timezone": "America/Cancun",
        "userGlobalID": "123123123",
        "userChannelID": "163.128.3.254",
        "userAuxiliaryID": "7319434000843499",
        "systemID": "4561 9219 9923",
        "location":
        {
          "latitude": "21.161908",
          "longitude": "-86.8515279"
        }
      },
      "preferred_coffee": "cappucino",
      "user_name": "Sam"
    }
  }
}

For a description of the userData variable, see userData schema in the Mix.dialog documentation.

ExternalResourceReferences predefined variable

The ExternalResourceReferences variable is used to pass in references to compiled resources. For more details, see Passing in compiled resource references.

Language and channel predefined variables via selector

The language and channel can be set via a data field like other predefined variables. For the language and channel predefined variables specifically, these can also be set via a selector.

For more details see Selecting language and channel.

Channel integration

The channelIntegration variable carries information of the specific channel integration used for the current channel. For more details on channels and channel integrations, see Channels.

Client data

A map of client-supplied key-value pairs can be passed in via the client_data field of a StartRequest call. These key-value pairs are injected into runtime event logs and can be used for example to inject a client-side ID to correlate between client-side logs and Dialog event logs.

User Id

You can specify a user ID, through the user_id field, in the StartRequest, ExecuteRequest, UpdateRequest, and StopRequest. This user ID is hashed into an unreadable format and stored in call logs and user-specific files.

Variables defined in Mix.dialog

You can set variables that were previously defined in Mix.dialog via a StartRequest or UpdateRequest.

For example, let’s say that the user name and preferred coffee are stored on the user’s phone, and you’d like to use them in your dialog application to customize your messages:

• System: Hey Miranda! What can I do for you today?
• User: I’d like my usual.
• System: Perfect, a double espresso coming up!

To implement this scenario:

1. Create variables in Mix.dialog (for example, user_name and preferred_coffee). See Manage variables in the Mix.dialog documentation for details.

2. Use the variables in the dialog; for example, the following message node includes the user_name value in the initial prompt:

   

3. Send the values of user_name and preferred_coffee as key-value pairs in the StartRequestPayload or UpdateRequestPayload.

The dialog app can then include the user name in the next prompt:

{
    "payload": {
        "messages": [],
        "qa_action": {
            "message": {
                "nlg": [],
                "visual": [
                    {
                        "text": "Hello Miranda ! What can I do for you today?"
                    }
                ],
                "audio": []
            }
        }
    }
}