--- title: "Messages (Requests)" slug: "dataflow-messages" description: "This documentation focuses on the format and content of messages (requests) used to initiate operations in Knovvu Data Flow. " updated: 2026-04-07T07:15:46Z published: 2026-04-07T07:15:46Z canonical: "docs.knovvu.com/dataflow-messages" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.knovvu.com/llms.txt > Use this file to discover all available pages before exploring further. # Messages (Requests) ## Client Sourced Messages ### Message Names - Start - Finalize - Update - Stop ### Start **Description** The first message client needs to send in [WebSocket](/v1/docs/dataflow-integrations-websocket)and [gRPC](/v1/docs/dataflow-integrations-grpc)integrations. The server returns a [StartResponse](/v1/docs/dataflow-messages#startresponse) message after initialization is finished. Also used as the “[Parameters](/v1/docs/dataflow-integrations-http#Parameters)” multipart field in [HTTP](/v1/docs/dataflow-integrations-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](/v1/docs/dataflow-architecture-textual-data#requests)for info about finding your tenant id. --- `Token` string** Token retrieved from the [Authentication Service](/v1/docs/dataflow-authentication). --- `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. --- `VARuntimeParameters` *object(stringified) \| null* **Show Properties** `CustomActionData` *object \| null* Sent to VA as the CustomActionData field of Activity Objects. --- `ProjectName` *string \| null* Sent to VA as the Project Name. --- `ChannelId` *string \| null* Sent to VA as the Channel Id. --- `EndUser` *object\| null* Sent to VA as the End User. --- `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](/v1/docs/dataflow-architecture-project-design#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](/v1/docs/events) styled JSON objects. These objects are sent through the [Entry](/v1/docs/dataflow-nodes-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](/v1/docs/dataflow-messages#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 SESTEK CA, SESTEK 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. | ```json { "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":{ "VARuntimeParameters":"{ \"CustomActionData\":{}, \"ProjectName\":\"va-demo\", \"ChannelId\":\"ivr-external\", \"EndUser\":{\"Name\":\"John\"} }", "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*](/v1/docs/dataflow-integrations-http)*integrations.* ****: Not Necessary for*[*HTTP*](/v1/docs/dataflow-integrations-http)*integrations if the Input Audio is a Wave.* | | --- ### Update **Description** Updates the key-value pairs given by the [StartMessage](/v1/docs/dataflow-messages#start) 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*. | ```json { "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](/v1/docs/events#FinalResult)event. The server returns a [FinalizeResponse](/v1/docs/dataflow-messages#finalizeresponse)to acknowledge the message. | **Explanations** | **JSON** | | --- | --- | | `MessageName` *string* Name of the sent message. Must be **Finalize****.** | ```json { "MessageName": "Finalize" } ``` | --- ### Stop **Description** Tells every node in the session to **interrupt and dismiss**their remaining work and **then**send a [FinalResult](/v1/docs/events#FinalResult)event. | **Explanations** | **JSON** | | --- | --- | | `MessageName` *string* Name of the sent message. Must be **Stop**. | ```json { "MessageName": "Stop" } ``` | --- ### Event **Description** Sends a custom [Event](/v1/docs/events) to the session to be outputted from the [Entry](/v1/docs/dataflow-nodes-entry) node. | **Explanations** | **JSON** | | --- | --- | | Event *object* The Event object in JSON format. | ```json { "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](/v1/docs/dataflow-messages#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** | ```json { "MessageName": "StartResponse", "OperationResult": "Success" } ``` | --- ### UpdateResponse **Description** Acknowledges the incoming [Update](/v1/docs/dataflow-messages#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**. | ```json { "MessageName": "UpdateResponse", "OperationResult": "Success" } ``` | --- ### FinalizeResponse **Description** Acknowledges the incoming [Finalize](/v1/docs/dataflow-messages#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** | ```json { "MessageName": "FinalizeResponse", "OperationResult": "Success" } ``` | > [!CAUTION] > 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](/v1/docs/dataflow-messages#stop) Message , and returns the result of the operation. *Busy*means that there is **another**[Finalize](/v1/docs/dataflow-messages#finalize)or [Stop](/v1/docs/dataflow-messages#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** | ```json { "MessageName": "StopResponse", "OperationResult": "Success" } ``` | --- ### Event **Description** A JSON object of any event that reached the [Publisher](/v1/docs/dataflow-nodes-publisher) Node. Event objects are highly customizable. For reference you can check [here](/v1/docs/events#general-structure). | **Explanations** | **JSON** | | --- | --- | | `Event`*object* The Event object in JSON format. | ```json { "Event":{ "Name":"", "Channel":-1, "StartMsec":-1, "EndMsec":-1, "GroupId":"", "Tags":[], "Data":{} } } ``` | | | | ### Incident | **Explanations** | **JSON** | | --- | --- | | `Incident`*object* 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. | ```json { "Incident":{ "Message":"Could not connect to SR Service", "Level":"Error", "NodeName":"SR Http", "NodeId":"sr-http-2", "Channel":"1", "SessionId":"782ee533ef514499" } } ``` |