Talkdesk to Partner

WebSocket Messages

There are separate types of events that occur during the conversation stream's lifecycle. These events are represented via WebSocket messages:

Each message sent is a JSON string. You can determine which type of event is occurring by using the event property of every JSON object. The messages below are sent from Talkdesk to your app.

Connected Message

The first message sent once a WebSocket connection is established is the connected event. This message describes the protocol to expect in the following messages.

Parameter

Description

event

The value of the connectedevent

protocol

Defines the protocol for the WebSocket connections lifetime. E.g.: "Call".

version

Semantic version of the protocol

{
  "event": "connected",
  "protocol": "Call",
  "version": "1.0.0"
}

Start Message

This message contains important metadata about the conversation stream and is sent immediately after the Connected message. It is only sent once at the start of the conversation stream.

Parameter

Description

event

The value of the start event

sequenceNumber

Number used to keep track of message sending order. The first message starts with "1" and then is incremented.

start

An object containing the conversation stream metadata

start.streamSid

The unique identifier of the conversation stream

start.accountSid

The account identifier that created the conversation stream

start.callSid

The call identifier from where the conversation stream was started

start.tracks

An array of values that indicates what media flows to expect in subsequent messages. Values include inbound and outbound.

start.customParameters

An object that represents the custom parameters that are set when defining the conversation stream.
By default, Talkdesk sends the following list of custom parameters:

  • interaction_id: the unique ID of that Talkdesk interaction.
  • agent_id: the Talkdesk ID for the agent
  • account_id: the Talkdesk ID for the account
  • type: can be “input”, “output”, or “both”. Set to “input” by default.
  • agent_phone_number: the phone dialed by the caller
  • customer_phone_number: the caller phone number
  • ring_groups: the ring group where it was sent.
  • timestamp: with the timestamp of the moment the call was answered by the agent.

start.mediaFormat

An object containing the format of the payload in the Media messages

start.mediaFormat.encoding

The encoding of the data in the upcoming payload. Value will always be audio/x-mulaw.

start.mediaFormat.sampleRate

The sample rate, in Hertz, of the upcoming audio data. Value is always 800.

start.mediaFormat.channels

The number of channels in the input audio data. Value will always be 1.

{
  "event": "start",
  "sequenceNumber": "2",
  "Start": {
    "streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0",
    "accountSid": "AC123",
    "callSid": "CA123",
    "tracks": [
      "Inbound",
      "Outbound"
    ],
    "customParameters": {
      "interaction_id": "073c9e0e1ab44c8a8085da2b08c1ecf9",
      "agent_id": "614c537a2021746aead25356",
      "account_id": "5cee471c844dda000d67a428",
      "type": "inbound",
      "agent_phone_number": "+11234567890",
      "customer_phpne_number": "+19876543210",
      "ring_groups": "english_speakers",
      "timestamp": "2022-01-16T16:12:47.254Z"
    },
    "mediaFormat": {
      "encoding": "audio/x-mulaw",
      "sampleRate": 8000,
      "channels": 1
    }
  },
  "streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0"
}

Media Message

This message type encapsulates the raw audio data.

Parameter

Description

event

The value of the media event

sequenceNumber

Number used to keep track of message sending order. The first message starts with "1" and then is incremented.

media

An object containing media metadata and payload information

media.track

inbound or outbound

media.chunk

The chunk for the message. The first message will begin with "1" and increment with each subsequent message.

media.timestamp

Presentation timestamp in milliseconds from the start of the stream

media.payload

An array of values that indicates what media flows to expect in subsequent messages. Values include inbound and outbound.

streamSid

The unique identifier of the conversation stream

{
  "event": "media",
  "sequenceNumber": "3",
  "media": {
    "track": "outbound",
    "chunk": "1",
    "timestamp": "5",
    "payload": "no+JhoaJjpzSHxAKBgYJDhtEopGKh4aIjZm7JhILBwYIDRg1qZSLh4aIjJevLBUMBwYHDBUsr5eMiIaHi5SpNRgNCAYHCxImu5mNiIaHipGiRBsOCQYGChAf0pyOiYaGiY+e/x4PCQYGCQ4cUp+QioaGiY6bxCIRCgcGCA0ZO6aSi4eGiI2YtSkUCwcGCAwXL6yVjIeGh4yVrC8XDAgGBwsUKbWYjYiGh4uSpjsZDQgGBwoRIsSbjomGhoqQn1IcDgkGBgkPHv+ej4mGhomOnNIfEAoGBgkOG0SikYqHhoiNmbsmEgsHBggNGDWplIuHhoiMl68sFQwHBgcMFSyvl4yIhoeLlKk1GA0IBgcLEia7mY2IhoeKkaJEGw4JBgYKEB/SnI6JhoaJj57/Hg8JBgYJDhxSn5CKhoaJjpvEIhEKBwYIDRk7ppKLh4aIjZi1KRQLBwYIDBcvrJWMh4aHjJWsLxcMCAYHCxQptZiNiIaHi5KmOxkNCAYHChEixJuOiYaGipCfUhwOCQYGCQ8e/56PiYaGiY6c0h8QCgYGCQ4bRKKRioeGiI2ZuyYSCwcGCA0YNamUi4eGiIyXrywVDAcGBwwVLK+XjIiGh4uUqTUYDQgGBwsSJruZjYiGh4qRokQbDgkGBgoQH9KcjomGhomPnv8eDwkGBgkOHFKfkIqGhomOm8QiEQoHBggNGTumkouHhoiNmLUpFAsHBggMFy+slYyHhoeMlawvFwwIBgcLFCm1mI2IhoeLkqY7GQ0IBgcKESLEm46JhoaKkJ9SHA4JBgYJDx7/no+JhoaJjpzSHxAKBgYJDhtEopGKh4aIjZm7JhILBwYIDRg1qZSLh4aIjJevLBUMBwYHDBUsr5eMiIaHi5SpNRgNCAYHCxImu5mNiIaHipGiRBsOCQYGChAf0pyOiYaGiY+e/x4PCQYGCQ4cUp+QioaGiY6bxCIRCgcGCA0ZO6aSi4eGiI2YtSkUCwcGCAwXL6yVjIeGh4yVrC8XDAgGBwsUKbWYjYiGh4uSpjsZDQgGBwoRIsSbjomGhoqQn1IcDgkGBgkPHv+ej4mGhomOnNIfEAoGBgkOG0SikYqHhoiNmbsmEgsHBggNGDWplIuHhoiMl68sFQwHBgcMFSyvl4yIhoeLlKk1GA0IBgcLEia7mY2IhoeKkaJEGw4JBgYKEB/SnI6JhoaJj57/Hg8JBgYJDhxSn5CKhoaJjpvEIhEKBwYIDRk7ppKLh4aIjZi1KRQLBwYIDBcvrJWMh4aHjJWsLxcMCAYHCxQptZiNiIaHi5KmOxkNCAYHChEixJuOiYaGipCfUhwOCQYGCQ8e/56PiYaGiY6c0h8QCgYGCQ4bRKKRioeGiA=="
  },
  "streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0"
}
{
  "event": "media",
  "sequenceNumber": "4",
  "media": {
    "track": "inbound",
    "chunk": "2",
    "timestamp": "5",
    "payload": "no+JhoaJjpzSHxAKBgYJDhtEopGKh4aIjZm7JhILBwYIDRg1qZSLh4aIjJevLBUMBwYHDBUsr5eMiIaHi5SpNRgNCAYHCxImu5mNiIaHipGiRBsOCQYGChAf0pyOiYaGiY+e/x4PCQYGCQ4cUp+QioaGiY6bxCIRCgcGCA0ZO6aSi4eGiI2YtSkUCwcGCAwXL6yVjIeGh4yVrC8XDAgGBwsUKbWYjYiGh4uSpjsZDQgGBwoRIsSbjomGhoqQn1IcDgkGBgkPHv+ej4mGhomOnNIfEAoGBgkOG0SikYqHhoiNmbsmEgsHBggNGDWplIuHhoiMl68sFQwHBgcMFSyvl4yIhoeLlKk1GA0IBgcLEia7mY2IhoeKkaJEGw4JBgYKEB/SnI6JhoaJj57/Hg8JBgYJDhxSn5CKhoaJjpvEIhEKBwYIDRk7ppKLh4aIjZi1KRQLBwYIDBcvrJWMh4aHjJWsLxcMCAYHCxQptZiNiIaHi5KmOxkNCAYHChEixJuOiYaGipCfUhwOCQYGCQ8e/56PiYaGiY6c0h8QCgYGCQ4bRKKRioeGiI2ZuyYSCwcGCA0YNamUi4eGiIyXrywVDAcGBwwVLK+XjIiGh4uUqTUYDQgGBwsSJruZjYiGh4qRokQbDgkGBgoQH9KcjomGhomPnv8eDwkGBgkOHFKfkIqGhomOm8QiEQoHBggNGTumkouHhoiNmLUpFAsHBggMFy+slYyHhoeMlawvFwwIBgcLFCm1mI2IhoeLkqY7GQ0IBgcKESLEm46JhoaKkJ9SHA4JBgYJDx7/no+JhoaJjpzSHxAKBgYJDhtEopGKh4aIjZm7JhILBwYIDRg1qZSLh4aIjJevLBUMBwYHDBUsr5eMiIaHi5SpNRgNCAYHCxImu5mNiIaHipGiRBsOCQYGChAf0pyOiYaGiY+e/x4PCQYGCQ4cUp+QioaGiY6bxCIRCgcGCA0ZO6aSi4eGiI2YtSkUCwcGCAwXL6yVjIeGh4yVrC8XDAgGBwsUKbWYjYiGh4uSpjsZDQgGBwoRIsSbjomGhoqQn1IcDgkGBgkPHv+ej4mGhomOnNIfEAoGBgkOG0SikYqHhoiNmbsmEgsHBggNGDWplIuHhoiMl68sFQwHBgcMFSyvl4yIhoeLlKk1GA0IBgcLEia7mY2IhoeKkaJEGw4JBgYKEB/SnI6JhoaJj57/Hg8JBgYJDhxSn5CKhoaJjpvEIhEKBwYIDRk7ppKLh4aIjZi1KRQLBwYIDBcvrJWMh4aHjJWsLxcMCAYHCxQptZiNiIaHi5KmOxkNCAYHChEixJuOiYaGipCfUhwOCQYGCQ8e/56PiYaGiY6c0h8QCgYGCQ4bRKKRioeGiA=="
  },
  "streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0"
}

Stop Message

A stop message will be sent when the conversation stream is either stopped or the call has ended.

Parameter

Description

event

The value of the stop event

sequenceNumber

Number used to keep track of message sending order. The first message starts with "1" and then is incremented.

stop

An object containing stop metadata and payload information

stop.accountSid

The account identifier that created the stream

stop.callSid

The call identifier that started the conversation stream

streamSid

The unique identifier of the conversation stream

{
  "event": "stop",
  "sequenceNumber": "5",
  "stop": {
    "accountSid": "AC123",
    "callSid": "CA123"
  },
  "streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0"
}

Mark Message

The mark event is used to track, or label, when media has completed.

Parameter

Description

event

The value of the mark event

sequenceNumber

Number used to keep track of message sending order. The first message starts with "1" and then is incremented.

mark

An object containing the mark metadata

mark.name

The value specified when creating the mark message to Talkdesk

{
"event": "mark",
"sequenceNumber": "4",
"streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0",
"mark": {
"name": "my label"
}
}

Did this page help you?