Textual Data

Data Flow uses json format for all of its text based communication.

There are 4 text message types that can be exchanged between clients and the server of Data Flow.

• Requests
• Responses
• Events
• Incidents

Requests are sent from clients to Data Flow servers. They are meant for letting the client manage the lifetime of an operation.

Requests are sent from Data Flow servers to Data Flow clients in response to the request messages. Responses bascially let the client learn about their requests' success or failure.

Events on the other hand take care of everything else. Data Flow servers notify their clients about every important piece information by sending events. Nodes communicate between themselves by sending events.

Requests

Requests are sent from clients to servers. eg. Start, Stop and Finalize messages are requests.
Request messages must contain a MessageName field.

Start Request

Example

{
  "MessageName": "Start",
  "ProjectName": "[project-name]",
  "Token":"[token]",
  "Tenant":"[tenant]",
  "Audio":
  {
    "Encoding": "ulaw",
    "SampleRate": "8000",
    "ChannelCount": "2"
  }
}

The field names in the start message above are self explanatory. You are expected to send whatever information necessary for your project to start.

Common Parameters

How To Determine Tenant

Note: You can see your tenant as Tenant Id in the Projects page of Data Flow . See image below. Above the New Project button.

Additional Parameters
Data Flow works with a project based approach. Data Flow projects include several different kinds of nodes. Each Data Flow node represents a new ability and some of the nodes may require additional information to perform their tasks. Also note that you can define your own nodes and implement new functionality in Data Flow which in turn may require different information that your clients will need to send in their start messages.

Due to node requirements, your start message may have to contain extra information in addition to the Common Parameters. For example ChannelSwitch node expects the client to provide tag's for each audio/text channel that will be used in the project. You will need to check the specific nodes' documentations to see what extra information you need to send in your project. Again for a project which contains a ChannelSwitch node you will need a start message somewhat like the following:

{
  "MessageName": "Start",
  "ProjectName": "[project-name]",
  "Token":"[token]",
  "Tenant":"[tenant]",
  "Audio":
  {
    "Encoding": "pcm",
    "SampleRate": "8000",
    "ChannelCount": "1"
  },
  "Settings":
  { 
    "ChannelTags":[    
      "customer",
      "agent"
    ]
  }
}

While this document is being prepared, among the preinstalled nodes Channel Switch, CA Realtime, Conversation Analyzer are the only nodes that have this requirement.

Reading Additional Parameters From Custom Node

If you are developing a custom node you can read the contents of start message in the createNode method.

createNode = function(nodeConfig, startMessage)
{
  var tagsOfEachChannel = startMessage.Settings.ChannelTags;
   ...

}

Finalize Request

Example

{"MessageName": "Finalize"}

Parameters

Responses

Responses are sent from servers to clients as replies to the request messages. Each request has a response message. Response message contain following fields:

Events

Events are the most prominent way to communicate information in Data Flow.

When a node wants to share its findings or just wants to share a message it does that in the form of sending an event. Who will receive an event that has been generated by a specific node is determined by that node's outlet connections.

Assume node-A sends event-A.

• If node-A outlet is connected to node-B, then node-B receives event-A as input. At that point it is up to node-B to determine what to do with event-A, it can take some action upon it or just ignore it.
• If node-A outlet is connected to the Publisher node, then event-A is sent to the other side of the connection, ie. the client receives this info.

A sample event:

{
    "Event": {
        "Channel": 0,
        "Data": {
            "Confidence": 0.96,
            "Text": "hi carlos i renewed my plan on the mobile application i'm not sure if it worked i just want to make sure i tried twice i also called you once an hour ago it's still not you know giving me a confirmation message",
            "TextAttributes": "recognized"
        },
        "EndMsec": 17999,
        "Name": "sr-milestone",
        "StartMsec": 5119
    }
}

Events carry the information beneath an Event object.

Event Information

Due to Data Flow's project structure, the same piece of audio data may be processed by several nodes concurrently. For example, a piece of audio data may be sent to the sr-http and emotion nodes separately. Even though sr-http and emotion nodes will produce separate events containing their own analysis results, the groupId of these events will be the same. Therefore, if you want to combine these results, you can depend on groupId.

Incidents

Incidents are the way Data Flow reports problems observed during an operation to its clients.

A sample Incident:

 {
            "Message": " an error occured during the Detect Topic API call. http status code : 401 http status text : Unauthorized",
            "IncidentLevel": "Error",
            "NodeId": "topic-detection-22",
            "NodeName": "Topic Detection",
            "SessionId": "b4295a17072f4f42"
}

Incident Information

Message and IncidentLevel fields are required, other fields is optional.

Remarks
Incidents are reported immediately in the streaming protocols eg. websocket and grpc. For batch protocols (ie. http) the client will receive an incident list in the response message.

Incidents occur after an operation has already been started. Any problem that prevents the operation from being started is reported in the start response as an error.

To learn more, you can check this link about creating and viewing incidents.