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 `connected`event
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"
  }
}

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.