Partner to Talkdesk

WebSocket Messages

There are separate types of events, which you can send back to Talkdesk, 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.

Media Message

To send media back to Talkdesk, you must provide a similarly formatted mediamessage. The payload must be encoded audio/x-mulaw with a sample rate of 8000 and be base64 encoded. The audio can be of any size.
The media messages will be buffered and played in the order received. If you'd like to interrupt the buffered audio, see here.
The media payload must not contain audio file type header bytes. Providing header bytes will cause the media to be streamed incorrectly.

Parameter	Description
event	The value of the `media` event
streamSid	The SID of the conversation stream that must play back the audio
media	An object containing media metadata and payload information
media.payload	Raw `mulaw/8000` audio in encoded in base64

{
  "event": "media",
  "streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0",
  "media": {
    "payload": "a3242sadfasfa423242... (a base64 encoded string of 8000/mulaw)"
  }
}

Stop Message

Send the stop event message if you want to stop the audio stream and communicate the result of the operation. Possible results are:

Success (the original call will continue the OK flow path).
Error (the original call will move the error exit).
Escalate (the original call will move to the escalation exit).

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
stop.command	One of ok/error /escalate options. This command will make the original call flow in the different exit paths on Talkdesk Studio.
stop.ringGroup	In case of escalation, this parameter indicates the ring group where to redirect the original call (it populates the `ring group` exit variable on the Talkdesk Studio component
streamSid	The SID of the stream that should receive the stopped stream

{
  "event": "stop",
  "streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0",
  "stop": {
    "command": "escalate",
    "ringGroup": "agents"
  }
}

Mark Message

Send a mark event message after sending a media event message to be notified when the audio that you have sent has been completed. You'll receive a mark event with a matching name from Talkdesk when the audio ends (or if there is no audio buffered).
You will also receive an incoming mark event message if the buffer was cleared using the clear event message.

Parameter	Description
event	The value of the `mark` event
streamSid	The SID of the conversation stream that must receive the mark
mark	An object containing the mark metadata and payload information
mark.name	A name specific to your needs that will assist in recognizing future received `mark` event

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

Clear Message

Send the clear event message if you would like to interrupt the audio that has been sent to various media event messages. This will empty all buffered audio and cause any mark event messages to be sent back to you.

Parameter	Description
event	The value of the `clear`event
streamSid	The SID of the conversation stream that must receive the `clear` event

{
  "event": "clear",
  "streamSid": "MZ18ad3ab5a668481ce02b83e7395059f0"
}

Troubleshooting

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