WebSocket Messages

When streaming a call, CarrierX sends JSON messages as events of 4 types:

• connected
• start
• media
• stop

Connected Event

CarrierX sends the connected event once a WebSocket connection is established, and is the first message your WebSocket server receives.

Connected Event Object

Attribute	Data Type	Description
event	string	connected
protocol	string	Call
version	string	The version of the Call protocol.

Sample Connected Event

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

Start Event

The start message contains metadata about the stream and any custom Parameters. The start event is sent once immediately after the Connected Event.

Start Event Object

Attribute	Data Type	Description
event	string	start
sequenceNumber	integer	The sequenceNumber is a sequential integer to help reorder messages delivered out of order. sequenceNumber will always be 1 in the start event.
start	object	The Start Message Object containing call metadata and custom Parameter key/value pairs.

Sample Start Event

{
  "event": "start",
  "sequenceNumber": 1,
  "start": {
    "callId": "7a9a4e28-1631-11ef-a79b-d4ce64f0cdf9",
    "tracks": [
      "inbound",
      "outbound"
    ],
    "mediaFormat": {
      "encoding": "audio/x-mulaw",
      "sampleRate": 8000
    },
    "customParameters": {
      "RemoteParty": "Bob",
      "FirstName": "Jane",
      "LastName":"Doe"
    }
  }
}

Start Message Object

The Start Message Object contains call metadata and custom Parameter key/value pairs.

Attribute	Data Type	Description
callId	string	The secure ID of the call is unique per call and will be consistent across all subsequent events.
customParameters	object	An object defined by the Parameter tags included in the Stream. See the example on the right.
mediaFormat	object	The Media Format Object is the encoding and sample rate of the media being streamed.
tracks	array of strings	The tracks that will be streamed as Media Events, and can be any of inbound, outbound, or mixed.

Media Format Object

The Media Format Object describes the encoding and sample rate of the media being streamed.

Attribute	Data Type	Description
encoding	string	The MIME type describing the encoding of the media stream, for instance audio/x-mulaw.
sampleRate	integer	The sample rate, or number of samples per second, of the media stream.

Media Event

The media message contains the actual stream content. The media message is used to send audio to the call.

Media Event Object

Attribute	Data Type	Description
event	string	media
media	string	The Media Message Object containing a slice of call content.
sequenceNumber	integer	The sequenceNumber is a sequential integer to help reorder messages delivered out of order. sequenceNumber will increment with every message. Note, that this attribute applies to unidirectional streams only.

Sample Media Event Object

{
  "event":"media",
  "sequenceNumber":1495,
  "media":{
    "callId":"80e6178c-1701-11ef-927b-e6b664f0cdf9",
    "track":"outbound",
    "timestamp":14712,
    "chunk":736,
    "payload":"sUhORChD6K6nr6aqpq3CP0yxra/ePPDeNmj7fL65qq/vNSxaVi0nSaqurdnHuG++uFhCy7GyWzQtw7dOO2atu9s7N0s4M0U7O8m8trziatqsyDtQQj8sMUZZt2hassFtSdP2PTw5TE85MkvE1UDbv9jOLzT2OTAtP1W0sb2qrtpYu2Q6LzpOOzswWb+/607Gy7t1Oc05JzBHUTE+urHOuQ=="
  }
}

Media Message Object

Attribute	Data Type	Description
callId	string	The secure ID of the call is unique per call and will be consistent across all subsequent events.
chunk	integer	Similar to sequenceNumber, chunk is the sequential integer indicating the order of the media chunks or slices. However, chunk is within the particular track.
payload	string	Base64 encoded string of the bytes of the chunk of audio. Concatenating all of the decoded bytes, ordered by chunk for a particular track will render the audio, encoded as identified in the Start Event Object.
timestamp	integer	The timestamp of the audio chunk, in milliseconds. The timestamp can be relative or absolute and is defined by <Stream timestampStart="">. Relative timestamps start at 0. Absolute timestamps start at the epoch (1970-01-01T00:00:00).
track	string	The track the media belongs to, and is one of inbound, outbound, or mixed.

note

When sending a media event object, only the payload field is sent.

Clear Event

Your application may send the clear message in bidirectional streams to delete any sent, but unplayed media payload, clearing all buffered audio.

Clear Event Object

Attribute	Data Type	Description
event	string	clear

Sample Clear Event Object:

{
  "event": "clear"
}

Stop Event

The stop event is sent in unidirectional streams only. It is sent once per call, is the last message sent, and represents the end of all streamed tracks.

Stop Event Object

Attribute	Data Type	Description
callId	string	The secure ID of the call is unique per call and will be consistent across all subsequent events.
event	string	stop
sequenceNumber	integer	The sequenceNumber is a sequential integer to help reorder messages delivered out of order. sequenceNumber will increment with every message.

Sample Stop Event Object

{
  "event":"stop",
  "sequenceNumber":433,
  "callId":"f68c10b6-1708-11ef-9daa-27d264f0cdf9"
}