Chat Voice API | OCP® Learning Center

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}/chat/ws/voice/dialogs?apiKey=xxxxxx

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

The apiKey parameter is required and should be added from the console (check your documentation for the corresponding parameters). For more info, see API Authentication

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	Yes	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	Yes	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	Yes	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	Yes	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`.