About payloads

Each event log message has the same top-level structure, which is based on standard Kafka messages.

The top-level value field contains high-level information about the event that generated the event log and follows the CloudEvents - Version 1.0  specification.

In particular, it includes the data field, which provides the actual contents of the payloads. This field includes a set of standard fields, which are available for all payloads, as well as a set of service-specific fields.

This section first describes the top-level structure of the event logs. The remainder of this document describes the specifics of each service payloads.

Top-level Kafka structure

  Example of top-level Kafka structure  

All Kafka messages have the following top-level structure:

Field Description
topic Name of the topic. In Mix, this is the app ID.
key Key for this message. Messages with the same key go to the same partition in the topic. The key includes two fields:
  • service: Name of the runtime service that generated this message. Valid values are: TTSaaS (for TTSaaS and Neural TTSaaS), ASRaaS, NLUaaS, DLGaaS, NRaaS, Fabric.
  • id: Randomly-generated UUID that uniquely identifies the message.
value Contents of the Kafka message. See value field structure.
partition Partition number for this topic. See Partitions.
offset Integer number representing the last record that Kafka has sent to a consumer. See Using offsets.

value field structure

  Example of value field  

The top-level value field contains high-level information about the event that generated the event log. It follows the CloudEvents - Version 1.0  specification and has the following structure:

value field
Field Description
specversion Version of the specification.
service Name of the runtime service that generated this message. Valid values are: TTSaaS (for TTSaaS and Neural TTSaaS), ASRaaS, NLUaaS, DLGaaS, NRaaS, Fabric.
source Context (endpoint) in which the event was generated. Possible values are service-specific. See source and type fields.
type Type of the event. Possible values depend on the source. See source and type fields.
id Randomly-generated UUID that identifies the event. The combination of the source and id fields is unique for each distinct event.
timestamp Timestamp of when the event occurred.
appid App ID for this event.
datacontenttype Content type of data field. Always application/json.
data Contents of the payload. See data field structure.

source and type fields

The source field specifies the context in which the event was generated.

source and type fields
Service source field type field
ASRaaS nuance.asr.v1.Recognizer/Recognize Recognize
NLUaaS nuance.nlu.v1.Runtime/Interpret Interpret
DLGaaS nuance.dlg.v1.DialogService/Start Start
DLGaaS nuance.dlg.v1.DialogService/Status Status
DLGaaS nuance.dlg.v1.DialogService/Update Update
DLGaaS nuance.dlg.v1.DialogService/Execute Execute
DLGaaS nuance.dlg.v1.DialogService/ExecuteStream ExecuteStream
DLGaaS nuance.dlg.v1.DialogService/Stop Stop
DLGaaS NIIEventLogger NIIEventLog
TTSaaS nuance.tts.v1.Synthesizer/Synthesize Synthesize
TTSaaS nuance.tts.v1.Synthesizer/UnarySynthesize Synthesize
NTTSaaS nuance.tts.v1.Synthesizer/Synthesize Synthesize
NRaaS nuance.nrc.v1.Recognizer/Recognize Recognize
NRaaS nuance.nrc.v1.NRC/DTMFRecognize DTMFRecognize
Fabric nuance.fabric.forget.v1.ForgetMe/Forget ForgetMe

data field structure

  Example of data field  

The data field specifies the actual content of the payload. It includes a set of standard fields, which are available for all payloads, as well as a set of service-specific fields, which depend on the value of the dataContentType field.

The following table lists the standard fields:

data field
Field Description
dataContentType Defines the type of content that will be available in the data field. See dataContentType field.
traceid Currently not used.
requestid Nuance-generated UUID that identifies an entire API request through all the services. This field can be used for debugging and to correlate all the event logs that relate to a specific interaction. See Correlate logs for a specific API interaction.
clientRequestid Client-provided ID that identifies an entire API request through all the services. See Client-provided request ID.
sessionId Identifier of the current sesssion, used by most services. ASRaaS uses asrSessionid and NRaaaS uses nrcSessionid.
userid A combination of the user_id field provided in the API and the appid field. (For example, for DLGaaS, the user_id is provided as part of the StartRequest). To generate the userid value, the appid and user_id fields are concatenated and separated by a colon, as follows: appid:user_id. This value is then hashed using SHA256 and provided as a 64-character hexadecimal string. See User ID.
locale Locale used for this interaction.
processingTime Included in the final response payload, when duration can be calculated. Includes the following fields:
  • startTime: Time that the request is received.
  • firstAudioBufferTime: Time that the first audio buffer is received. Applies to TTSaaS only.
  • durationMs: Duration of the request in milliseconds. The duration is defined as the number of milliseconds between the time that the request has arrived and the time that the response is sent. It includes the time required by the other invoked services, such as when the dialog engine invokes NLU.
clientData Contents of the client_data map provided in the API. See Client data. For TTSaaS, Neural TTSaaS, and NII logs, this is provided at the top level of the data field. For DLGaaS, NLUaaS, ASRaaS, and NRaaS the client_data field is provided in the request object.
request Contents of the request, if applicable. Value is service-specific.
response Contents of the response, if applicable. Can contain a status code, message, and details. Value is service-specific.

dataContentType field

The dataContentType field specifies the content type of the data field. In particular, it determines which additional service-specific fields are included in the payload.

The dataContentType value has the following structure:

application/contenttype.version+json

Where:

  • contenttype defines the type of content that will be available in the event log
  • version specifies the version of the specification for this data content type; see About payload versions

The following table links to the sections that document each dataContentType payload:

dataContentType payload
Service Field See
ASRaaS application/x-nuance-asr-callsummary.v2+json asr-callsummary payload
  application/x-nuance-asr-finalresultresponse.v2+json asr-finalresultresponse payload
  application/x-nuance-asr-finalstatusresponse.v2+json asr-finalstatusresponse payload
  application/x-nuance-asr-recognitioninitmessage.v2+json asr-recognitioninitmessage payload
  application/x-nuance-asr-startspeechresponse.v2+json asr-startspeechresponse payload
  application/x-nuance-asr-statusresponse.v2+json asr-statusresponse payload
NLUaaS application/x-nuance-nluaas-interpretation.v1+json nluaas-interpretation payload
DLGaaS application/x-nuance-dlg-interaction-summary.v1+json dlg-interaction-summary payload
  application/x-nuance-dlg-nii-logs.v1+json dlg-nii-logs payload
TTSaaS application/x-nuance-tts-callsummary.v3+json tts-callsummary payload
NTTSaaS application/x-nuance-tts-callsummary.v4+json callsummary payload (Neural TTS)
NRaaS application/x-nuance-nrc-result.v1+json nrc-result payload
  application/x-nuance-nrc-startofspeech.v1+json nrc-startofspeech payload
  application/x-nuance-nrc-endofspeech.v1+json nrc-endofspeech payload
  application/x-nuance-nrc-control.v1+json nrc-control payload
  application/x-nuance-nrc-status.v1+json nrc-status payload
  application/x-nuance-nrc-dtmfrecognitioninit.v1+json nrc-dtmfrecognitioninit payload
  application/x-nuance-nrc-recognitioninit.v1+json nrc-recognitioninit payload
Fabric application/json tts-callsummary payload

About payload versions

The version number (for example, v1 in application/x-nuance-dlg-nii-logs.v1+json) specifies the version of the specification for this data content type. Non-breaking changes may be applied to the specification without updating the version number. Non-breaking changes include updates such as adding fields, adding new events, adding new values, and so on.

The client application that consumes the payloads should take this into account and should not assume that the structure and content are fixed.

Should a breaking change occur (for example, an event or a field is no longer available), then the version number will be increased to indicate this change.