Skip to main content
Skip table of contents

Chat Voice API

Overview

The Chat Voice API provides methods to create and manage voice sessions through WebSocket communication. This document describes the available endpoints and the structure of the messages that can be sent and received through these endpoints.

Base endpoint

WebSocket endpoint:
wss://{host}/ws/voice/dialogs

Replace {host} with the appropriate hostname to connect to the WebSocket server.

Message types

The Chat Voice API uses JSON-based message exchange. The messages are grouped into the following categories:

Incoming

The incoming messages are used to acknowledge a connection event sent by Talkdesk.

ConnectedMessage

This message starts a connection session with Talkdesk and marks the event as connected.

Click to see the details

Payload example

JSON
{
  "protocol": "string",
  "event": "connected",
  "version": "string"
}

Parameter

Type

Required

Description

protocol

String

No

Defines the protocol for the WebSocket connections lifetime. For example, “Call”.

event

String

No

Indicates the event type. It must be set to connected.

version

String

No

Specifies the semantic version of the protocol.

IncomingMediaMessage

This message is used to encapsulate raw audio data.

Click to see the details

Payload example

JSON
{
  "sequenceNumber": 0,
  "streamSid": "string",
  "media": {
    "payload": "string",
    "chunk": "string",
    "track": "string",
    "timestamp": "string"
  },
  "event": "media"
}

Parameter

Type

Required

Description

sequenceNumber

Integer

Yes

The number used to keep track of the message-sending order. The first message starts with 1 and is incremented for each message.

streamSid

String

Yes

A unique identifier of the Twilio stream.

media

Object

Yes

An object containing media metadata and payload. Additional properties are allowed.

payload

String

No

Raw audio encoded in base64.

chunk

String

No

The chunk for the message. The first message starts with 1 and is incremented for each message.

track

String

No

One of inbound or outbound.

timestamp

String

No

Presentation Timestamp in Milliseconds from the start of the stream

event

String

No

Indicates the event type. It must be set to media.

MarkCallbackMessage

This message is sent to connector to notify that the audio ends or there is no buffered audio. It is sent in case if the MarkCallbackMessage was sent after the MediaMessage.

Click to see the details

Payload example

JSON
{
  "sequenceNumber": 0,
  "streamSid": "string",
  "event": "mark",
  "mark": {
    "name": "string"
  }
}

Parameter

Type

Required

Description

sequenceNumber

Integer

Yes

The number used to keep track of the message-sending order. The first message starts with 1 and is incremented for each message.

streamSid

String

Yes

A unique identifier of the Twilio stream.

event

String

No

Indicates the event type. It must be set to mark.

mark

Object

Yes

An object containing the mark metadata. Additional properties are allowed.

name

String

No

The value specified when creating the mark message.

StartMessage

This message contains important metadata about the conversation and is sent immediately after the ConnectedMessage. It is only sent to connector once, at the start of the conversation.

Click to see the details

Payload example

JSON
{
  "sequenceNumber": 0,
  "streamSid": "string",
  "start": {
    "callSid": "string",
    "customParameters": {
      "business_hours": "string",
      "initial_timestamp": "string",
      "account_id": "string",
      "correlation_id": "string",
      "interaction_id": "string",
      "type": "string",
      "stream_url": "string"
    },
    "mediaFormat": {
      "channels": 0,
      "encoding": "string",
      "sampleRate": 0
    },
    "accountSid": "string",
    "tracks": [
      "string"
    ]
  },
  "event": "start"
}

Parameter

Type

Required

Description

sequenceNumber

Integer

Yes

The number used to keep track of the message-sending order. The first message starts with 1 and is incremented for each message.

streamSid

String

Yes

A unique identifier of the Twilio stream.

start

Object

No

An object containing call metadata. Additional properties are allowed.

callSid

String

Twilio unique call identifier. This is a 34-character string that starts with CA.

customParameters

Object

No

An object that represents the custom parameters set when defining the stream.

Additional properties are allowed.

business_hours

String

No

A custom input that Talkdesk wants to send to OCP.

initial_timestamp

String

No

The timestamp of the moment the stream started, in a recognized time format (for example, "HH:MM:SS").

account_id

String

No

The Talkdesk ID of the account.

correlation_id

String

No

The ID that identifies the call throughout its lifetime, for all the corresponding interaction_id of that call.

interaction_id

String

No

The unique ID of that Talkdesk interaction.

type

String

No

The media flow type. Allowed values are inbound and outbound.

stream_url

String

No

The WebSocket URL where the audio is being streamed.

mediaFormat

Object

No

An object containing the format of the payload in the media messages.

Additional properties are allowed.

channels

Integer

No

The number of channels in the input audio data. It must be set to 1.

encoding

String

No

The encoding of the data in the upcoming payload. It must be set to audio/x-mulaw.

sampleRate

Integer

No

The sample rate in Hertz of the upcoming audio data. It must be set to 8000.

accountSid

String

No

Twilio account identifier that created the stream. It is a 34-character string that starts with AC.

tracks

Array of strings

No

An array of values indicating what media flows to expect in the subsequent messages. Allowed values are inbound and outbound.

event

String

No

Indicates the event type. It must be set to start.

IncomingStopMessage

This message is sent to connector either when the conversation stream has stopped or the call has ended.

Click to see the detail

Payload example

JSON
{
  "sequenceNumber": 0,
  "streamSid": "string",
  "stop": {
    "callSid": "string",
    "accountSid": "string"
  },
  "event": "stop"
}

Parameter

Type

Required

Description

sequenceNumber

Integer

Yes

The number used to keep track of the message-sending order. The first message starts with 1 and is incremented for each message.

streamSid

String

Yes

A unique identifier of the Twilio stream.

stop

Yes

An object containing stream metadata. Additional properties are allowed.

callSid

No

Twilio unique call identifier. It is a 34-character string that starts with CA.

accountSid

No

Twilio account identifier that created the stream. It is a 34-character string that starts with AC.

event

No

Indicates the event type. It must be set to stop.

Outgoing

The outgoing messages are used to accept messages sent to Talkdesk.

OutgoingStopMessage

This message is used to stop an audio stream and communicate the result of the operation. The OutgoingStopMessage can indicate one of three outcomes:

  • ok - The audio stream was successful.

  • error -There was an error during the audio stream.

  • escalate - The audio stream should stop and the call needs to be escalated to a live agent.

Click to see the details

Payload example

JSON
{
  "streamSid": "string",
  "stop": {
    "ringGroup": "string",
    "command": "string"
  },
  "event": "stop"
}

Parameter

Type

Required

Description

streamSid

String

No

A unique identifier of the Twilio stream.

stop

Object

No

Contains additional properties related to the stop command.

ringGroup

String

No

Describes a specific ring group, if applicable.

command

String

No

Specifies a command related to stopping the stream.

event

String

No

Indicates the event type. It must be set to stop.

MarkMessage

This message is used to notify that the audio streamed by the connector has been completed. This message should be sent after the MediaMessage. The connector will receive a MarkCallbackMessage event with the matching name from Talkdesk when the audio ends or if there is no buffered audio. If the ClearMessage is used, the connector will also receive a MarkCallbackMessage event when the buffer clears.

Click to see the details

Payload example

JSON
{
  "streamSid": "string",
  "event": "mark",
  "mark": {
    "name": "string"
  }
}

Parameter

Type

Required

Description

streamSid

String

No

A unique identifier of the Twilio stream.

event

String

No

Indicates the event type. It must be set to mark. Additional properties are allowed.

mark

Object

No

Contains additional properties related to the mark event.

name

String

No

A name that identifies this specific mark event.

ClearMessage

This message is used to interrupt the audio stream. It will cancel all MediaMessages that are buffered and have not yet been played. This action will empty all buffered audio data and trigger a MarkCallbackMessage event to be sent back to the connector.

Click to see the details

Payload example

JSON
{
  "streamSid": "string",
  "event": "clear"
}

Parameter

Type

Required

Description

streamSid

String

No

A unique identifier of the Twilio stream.

event

String

Indicates the event type. It must be set to clear.

MediaMessage

This message sends an audio stream from the connector to Talkdesk. The media messages will be buffered and played in the order received. To interrupt the buffered audio, ClearMessage needs to be sent.

Click to see the details

Payload example

JSON
{
  "streamSid": "string",
  "media": {
    "payload": "string"
  },
  "event": "media"
}

Parameter

Type

Required

Description

streamSid

String

No

A unique identifier of the Twilio stream.

media

Object

No

An object containing media metadata and payload. Additional properties are allowed.

payload

String

No

Raw audio encoded in base64.

event

String

No

Indicates the event type. It must be set to media.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.