Messages (Requests)

07 May 2025
6 Minutes to read
Contributors

Messages (Requests)

Updated on 07 May 2025
6 Minutes to read
Contributors

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Client Sourced Messages

Message Names

Start
Finalize
Update
Stop

Start

Description

The first message client needs to send in WebSocket and gRPC integrations.

The server returns a StartResponse message after initialization is finished.

Also used as the “Parameters” multipart field in HTTP integrations.

Explanations

JSON

MessageName string **

Name of the sent message. Must be Start.

ProjectName string**

Name of the project.

Tenant string**

Tenant id of the project, you can check here for info about finding your tenant id.

Token string**

Token retrieved from the Authentication Service.

Audio object***

Properties of the incoming and outgoing audio messages.

Show Properties:

Encoding string

Encoding of the incoming wave, can be either “pcm”, “ulaw“ or “alaw”.

SampleRate int | string

Sample rate of incoming audio.

ChannelCount int

Channel Count of incoming audio, 1 for mono, 2 for stereo waves.

Output object | null

Output audio properties as a JSON object.

Show Properties

Encoding string

Audio output encoding in String form. Can be either “pcm”, “ulaw“ or “alaw”.

Language string | null

Language code for overriding the configuration defaults in language aware nodes. The language tags follow IETF standards. i.e. "en-US".

Settings object | null

Session specific settings for the project.

Show Properties

ChannelTags array | null

An array of semicolon separated strings, as of now, only customer and agent tags are utilized.

Any* primitive | null

Any name for a key can be used as long as it is assigned to a primitive(int, float, string, bool) data type, these key-value pairs are used to activate constraints during runtime. The values defined here will overwrite the project default parameters. If any value was defined in the project version that wasn’t included here, those values will be untouched.

Events array | null

An array of Event styled JSON objects. These objects are sent through the Entry node’s event output depending on their channel as soon as the session starts. Not supported in streaming integrations, you can check the Event section to learn about how to send events in streaming integrations.

CallProperties object | null

Session specific properties for CA, RTG, VT and VB integrations.

Show Properties

ExternalId string | null

External call id for the session. If null, Data Flow Session Id is used instead.

UserProperties object | null

Vendor specific agent ids, for these to be used properly, the ids need to be registered to Knovvu CA, Knovvu VB, and such beforehand.

Show Properties

AgentName string | null

Agent name

DeviceId string | null

DeviceId of the agent.

ExternalId string | null

Vendor specific ExternalId of the agent.

PbxAgentId string | null

PBX Id of the agent.

CustomerPhoneNumber string | null

Phone number of the customer, is required for VB integration.

Direction int | null

Call direction, values can be :

IN = 1, OUT = 2, IN_TRANSFER = 3, IN_CONSULT = 4, INTERNAL = 5, UNKNOWN = 6

AttachedData object | null

Attached data KVPs of the call. Currently used for Attached-Data-Specific scenarios in RTG.

Show Properties

Any* string | null

Any key-value pair can be given under the AttachedData, these are all passed along to RTG and are used to filter through Attached Data specific scenarios.

CallerNumber string | null

Number that initiated the call, required for VB integration.

CalledNumber string | null

Number that picked up the call, required for VB integration.

CallStartTime string | null

Call start time in ISO 8601 format.

Source string | null

Source of the call, currently, this is only passed to Copilot without being processed.

CA object | null

Session specific properties for CA.

Show Properties

TextBased bool | null

True if the session is text based. False if it is an audio based session.

{
    "MessageName":"Start",
    "ProjectName": "ca-online",
    "Tenant": "3a10d354-a7e8-7d76-cfc1-3f3d75e0127f",
    "Token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjExMDcyNDYxODF",
    "Audio":{
        "Encoding": "pcm",
        "SampleRate": 16000,
        "ChannelCount": 1,
        "Output":{
            "Encoding":"ulaw"
        }
    },
    "Language":"en-US",
    "Settings":{
        "ChannelTags":["agent", "customer"],
		"key1": "value1",
		"key2": 2,
		"key3": 2.1,
		"key4": true
    },
     "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_external_id_for_call",
		"UserProperties": {
		  "DeviceId": "123",
		  "PbxAgentId": "pbx_agent_id",
		  "AgentName": "John Doe",
		  "ExternalId": "a_valid_ext_id_for_agent"
		},
		"CustomerPhoneNumber": "+0123456789",
		"Direction": 1,
		"AttachedData": {
		  "key1": "value1",
		  "key2": "value2"
		},
		"CallerNumber": "5336563494",
		"CalledNumber": "123123",
		"CallStartTime": "2024-11-06 00:00:01",
		"Source":"IVR"
	  },
	"CA": {
		"TextBased": false
	}
}

*: Client configurable, any name can be given to the key.

** : Not Necessary for HTTP integrations.

***: Not Necessary for HTTP integrations if the Input Audio is a Wave.

Update

Description

Updates the key-value pairs given by the StartMessage under Settings. These new values overwrite the old ones, and keep others untouched.

The server returns a UpdateResponse message to let the client know if update was successful.

Explanations

JSON

MessageName string

Name of the message. Must be Update.

Parameters object

The key-value pairs that will redefine the parameters used in the session.

Show Properties

Any* primitive | null

Any primitive key-value pair can be given in JSON format. Accepted data types are string, int, float and bool.

{
    "MessageName": "Update",
    "Parameters": {
        "key1":"value2",
        "key2":3
    }
}

*: Client configurable, any name can be given to the key.

Finalize

Description

Tells every node in the session to finalize their remaining work and then send a FinalResult event.

The server returns a FinalizeResponse to acknowledge the message.

Explanations

JSON

MessageName string

Name of the sent message. Must be Finalize.

{
    "MessageName": "Finalize"
}

Stop

Description

Tells every node in the session to interrupt and dismiss their remaining work and then send a FinalResult event.

Explanations

JSON

MessageName string

Name of the sent message. Must be Stop.

{
    "MessageName": "Stop"
}

Event

Description

Sends a custom Event to the session to be outputted from the Entry node.

Explanations

JSON

Event object

The Event object in JSON format.

{
    "Event":{
        "Name":"",
        "Channel":-1,
        "StartMsec":-1,
        "EndMsec":-1,
        "GroupId":"",
        "Tags":[],
        "Data":{}
    }
}

Server Sourced Messages

Message Names

StartResponse
FinalizeResponse
StopResponse
UpdateResponse

StartResponse

Description

Acknowledges the incoming Start Message, and returns the result of the operation. Any response other than Success indicates that the session didn’t start.

Explanations

JSON

MessageName string

Name of the message. Must be StartResponse.

OperationResult string

Operation result. Can be Success, Busy, NoActiveOperation, UnknownMessageName and Failed

{
    "MessageName": "StartResponse",
    "OperationResult": "Success"
}

UpdateResponse

Description

Acknowledges the incoming Update Message , and returns the result of the operation. Any response other than Success indicates that the Parameters stayed the same.

Explanations

JSON

MessageName string

Name of the message. Must be UpdateResponse.

OperationResult string

Operation result. Can be Success, Busy, NoActiveOperation, UnknownMessageName and Failed.

{
    "MessageName": "UpdateResponse",
    "OperationResult": "Success"
}

FinalizeResponse

Description

Acknowledges the incoming Finalize Message , and returns Success if nodes successfully started finalizing their work.

Busy means that there is another Finalize or Stop operation is going on.

NoActiveOperation means either the session was already finished or was never started.

Explanations

JSON

MessageName string

Name of the message. Must be FinalizeResponse.

OperationResult string

Operation result. Can be Success, Busy, NoActiveOperation, UnknownMessageName and Failed

{
    "MessageName": "FinalizeResponse",
    "OperationResult": "Success"
}

A successful FinalizeResponse doesn’t mean the operation is finished. It means the finalization sequence has started. The client still needs to wait for the Event “FinalResult”.

StopResponse

Description

Acknowledges the incoming Stop Message , and returns the result of the operation.

Busy means that there is another Finalize or Stop operation is going on.

NoActiveOperation means either the session was already finished or was never started.

Explanations

JSON

MessageName string

Name of the message. Must be StopResponse.

OperationResult string

Operation result. Can be Success, Busy, NoActiveOperation, UnknownMessageName and Failed

{
    "MessageName": "StopResponse",
    "OperationResult": "Success"
}

Event

Description

A JSON object of any event that reached the Publisher Node. Event objects are highly customizable. For reference you can check here.

Explanations

JSON

Eventobject

The Event object in JSON format.

{
    "Event":{
        "Name":"",
        "Channel":-1,
        "StartMsec":-1,
        "EndMsec":-1,
        "GroupId":"",
        "Tags":[],
        "Data":{}
    }
}

Incident

Explanations

JSON

Incidentobject

The Incident object in JSON format.

Show Properties

Message string

Incident message in string format.

Level string

Incident Level in string format, can be one of “Debug”, “Warning”, “Error”.

NodeName string | undefined

Node name if the incident occurred from a Node.

NodeId string | undefined

Project Specific Node Id the incident occurred from.

Channel string | undefined

Channel Id in string format if the incident was Channel-Specific

SessionId string | undefined

Session Id if the incident is session-specific.

{
    "Incident":{
        "Message":"Could not connect to SR Service",
        "Level":"Error",
        "NodeName":"SR Http",
        "NodeId":"sr-http-2",
        "Channel":"1",
        "SessionId":"782ee533ef514499"
    }
}

Was this article helpful?

What's Next

Binary Data

Table of contents

Client Sourced Messages
Server Sourced Messages