HTTP

Introduction

The aim of this document is to explain Http integration details for Data Flow.

Data Flow has been designed for streaming from the ground up. Even though the main focus is on streaming, one can also benefit from the use of Data Flow with batch operations. For Data Flow batch operations Http is the go-to protocol.

Example

Let's first see what a sample Data Flow Http request looks like on Postman.
You can download Postman Collection below.

Wagtail_Postman_Collection.json

Authorization

Necessary Headers

Multipart Body

Http Operation Flow

You can consider a batch operation as an aggregate of stream operations. When a request is received by Data Flow server, basically the following steps are executed:

• Bearer token is read from Http "Authorization" header and it is validated by the Identity Server.
• Tenant, ProjectName(or services) Http headers are read and corresponding project is determined by the server.
• Http Multipart body is segregated and parsed.
• A start message is generated from Http Multipart body part Parameters
• Any errors while starting the operation causes the operation to fail at this stage. If operation starts successfully then we continue.
• Http Multipart body Audio is read and converted to BinaryMessage(s), then written to Data Flow.
• A Flush command is sent to all the nodes which tells them to consume whatever data they received and try to finish as soon as possible.
• Wait until all the data in the system has been consumed and all the nodes finish their work.
• Accumulate all the events that reach the publisher node, serialize them and send it as the Http response.

Multipart Explanations

Data Flow requires several inputs for a single operation. Http endpoint expects Multipart Body message to receive both the audio and textual parameters at the same time.

Bearer token is read from Http headers. So you do not need to send "token" here.

Audio

• Audio: has to be a wav file. pcm, alaw, ulaw formats are supported.
• Audio information is extracted from the wav file header. You are expected not to send "Audio" field that is normally sent in start messages.

Parameters

Parameters is a json formatted string. This part is treated similarly to a Start message with a few differences. There are Four main fields that are generally utilized in parameters.

• Settings: Json Object
• CallProperties: Json Object.
• Events: Json Array.
• Language: string. This field is a language tag that can be used by project nodes to override their default language for this session. The language tags follow IETF standards. i.e. "en-US".

Settings

Settings field contains information that is used by the Channel Switch node, as well as project specific Constraints The example below shows how you can run the demo-batch default project with every service.

{  
    "Settings":
    {    
        "ChannelTags":["agent", "customer"],
        "SpeakerDiarization": true,
        "DetectLanguage": true,
        "Normalizer": true,
        "ProfanityFilter": true,
        "Punctuation": true,
        "Summarization":true,
        "TopicDetection":true,
        "DebugMode":false
    }
}

CallProperties

Call Properties field contains useful information that is necessary for some of the Knovvu integration nodes to work. If the node documentation doesn't explicitly state that Call Properties is required, the user can skip this field altogether. For more information you can check the CA Realtime, RTG and VB Realtime pages.

{ 
  "CallProperties": 
  {
    "ExternalId": "a_valid_ext_id_for_call",
    "CustomerPhoneNumber": "a_valid_phone_number",
    "Direction": "1", 
    "UserProperties": {"ExternalId": "a_valid_ext_id_for_agent"}
  }
}

Events

Events field is a Json formatted array of objects. Each object represents an event. After the project starts, each of these events will be sent from the Entry node consecutively. The example below sends two SR Milestone events that can be processed by many nodes such as: TTS, Punctuation, Profanity Filter, Sentiment and more.

{
  "Events": [
    {
      "Name": "SR Milestone",
      "Channel": 0,
      "Data": {
        "Text": "Hello from channel zero"
      },
      "StartSampleIndex": 0,
      "EndSampleIndex": 1000
    },
    {
      "Name": "SR Milestone",
      "Channel": "1",
      "Data": {
        "Text": "Hello from channel one"
      },
      "StartSampleIndex": 1200,
      "EndSampleIndex": 2400
    }
  ]
}

Using Multiple Fields In Parameters

We can utilize all fields of Parameters at once as such:

{
    "Language":"en-US",
    "Settings":{ 
        "ChannelTags":["agent", "customer"]
    },
     "Events": [
        {
          "Name": "SR Milestone",
          "Channel": 0,
          "Data": {
            "Text": "Hello from channel zero"
          },
          "StartSampleIndex": 0,
          "EndSampleIndex": 1000
        },
        {
          "Name": "SR Milestone",
          "Channel": "1",
          "Data": {
            "Text": "Hello from channel one"
          },
          "StartSampleIndex": 1200,
          "EndSampleIndex": 2400
        }
     ],
     "CallProperties": 
     {
        "ExternalId": "a_valid_ext_id_for_call",
        "CustomerPhoneNumber": "a_valid_phone_number",
        "Direction": "1", 
        "UserProperties": {"ExternalId": "a_valid_ext_id_for_agent"}
      }
}