Global

Table of Contents

Methods

dataCollectionDefaultConstantToObject(def)

Given a data collection from library (data collection definition) check if some field is configured as autofill from constant. In that case, will return only these values. All the other possible fields will be ignored.

Parameters:
Name Type Description
def

Data collection definition from database
Returns:

only value in variables configured as constant

dataCollectionDefaultConstantToObject(def)

Given a data collection from library (data collection definition) check if some field is configured as autofill from constant. In that case, will return only these values. All the other possible fields will be ignored.

Parameters:
Name Type Description
def

Data collection definition from database
Returns:

only value in variables configured as constant

dataCollectionDefaultConstantToObject(def)

Given a data collection from library (data collection definition) check if some field is configured as autofill from constant. In that case, will return only these values. All the other possible fields will be ignored.

Parameters:
Name Type Description
def

Data collection definition from database
Returns:

only value in variables configured as constant

dataCollectionDefaultConstantToObject(def)

Given a data collection from library (data collection definition) check if some field is configured as autofill from constant. In that case, will return only these values. All the other possible fields will be ignored.

Parameters:
Name Type Description
def

Data collection definition from database
Returns:

only value in variables configured as constant

dataCollectionDefaultConstantToObject(def)

Given a data collection from library (data collection definition) check if some field is configured as autofill from constant. In that case, will return only these values. All the other possible fields will be ignored.

Parameters:
Name Type Description
def

Data collection definition from database
Returns:

only value in variables configured as constant

dataCollectionDefaultConstantToObject(def)

Given a data collection from library (data collection definition) check if some field is configured as autofill from constant. In that case, will return only these values. All the other possible fields will be ignored.

Parameters:
Name Type Description
def

Data collection definition from database
Returns:

only value in variables configured as constant

dataCollectionDefaultConstantToObject(def)

Given a data collection from library (data collection definition) check if some field is configured as autofill from constant. In that case, will return only these values. All the other possible fields will be ignored.

Parameters:
Name Type Description
def

Data collection definition from database
Returns:

only value in variables configured as constant

Type Definitions

ContactData

See the corresponding JSON Schema for further information.

DataCollection

Properties:
Name Type Description
name string

Name of the form
desc string

Human-readable name of the form
data Array.<object>

List of fields of the form

Properties
Name Type Description
name string

Name of the field
desc string

Human-readable name of the field
type string

Field type:

  • checkbox, a boolean value, use the property checked to store the value
  • date, a ISO8601 formatted date
  • email, an email address, the value of first field of this type is assumed to be the visitor's email
  • link, a HTTP/HTTPS URL
  • number, a number (integer or float)
  • phone, a E.164 formatted phone number
  • text, a text value
  • nickname, the value of first field of this type is assumed to be the visitor's nickname/diplay name
value *

The value of the field, for types other than checkbox
checked boolean

The value of the field, for checkboxes
visible boolean

If true, the field and its value are visible to the agent
editable boolean

If true, the agent is allowed to modify the value of the field. In case of edits, Vivocha stores also the original value and the id of the agent that changed it.

This type describes the format to attach user-defined data to a Vivocha contact. The data collection is a list of data forms, which are sets of fields, with their values and associated metadata. See the corresponding JSON Schema for further information.

Type:
  • Array.<object>

VisitData

See the corresponding JSON Schema for further information.

MediaStateDetails

Properties:
Name Type Attributes Description
tx boolean

The media is being transmitted to the remote.
rx boolean

The media is being accepted from the remote.
via string <optional>

The network or communication method used to transmit the media. Built-in engines currently set this property to either net, indicating that the communication will be over IP, or pstn, indicating the telephony network will be used. Custom engines might set this property to additional values. The property is mandatory if at least one of tx and rx is true.
engine string <optional>

The identifier of the engine handling the media. The property is mandatory if at least one of tx and rx is true.
data object <optional>

Opaque state info used by the media engine.

MediaState

Properties:
Name Type Attributes Description
Sharing MediaStateDetails

Sharing state, the state of the media used to communicate at a protocol level with the remote party, to enable features like co-browsing, form-sharing, page pushing and in general all forms of RPC
Chat MediaStateDetails <optional>

Chat state
Voice MediaStateDetails <optional>

Audio state
Video MediaStateDetails <optional>

Video state
Screen MediaStateDetails <optional>

Screen sharing state

Each property of a MediaState object represents the state of corresponding media. This type is used to both represent the current state of the media in a contact and to described a desired media transition. NOTE: tx and rx are always relative to who's reading the message (the library takes care of swapping them when transmitting the data)

Example

Sample media state

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC",
     "data": {
       "tx_stream": {
         "id": "oR9TTCaHtKz8C9Dn9ITUJ1KQcqFBDpLwbkqg",
         "url": "blob:https%3A//beta.vivocha.com/e021fa15-23ab-41de-9f09-8e5f661dc690"
       },
       "rx_stream": {
         "id": "Jkg2lX8Mw3WW1VUqRZMJmDDkwYEi6Olqky2d",
         "url": "blob:https%3A//beta.vivocha.com/87be3964-1391-4afb-ad6a-fc42abbd8618"
       }
     }
   },
   "Screen": {
     "rx": false,
     "engine": "WebRTC"
   }
 }

MediaOfferDetails

Properties:
Name Type Attributes Description
tx string

The transmission offer: can be required (if the receiving party accepts the offer, it must transmit the media), off (the receiving party must not transmit the media), optional (the receiving party must choose whether to transmit or not the media, the decision must be in the answer).
rx string

The reception offer: can be required (if the receiving party accepts the offer, it must be prepared to receive the media), off (the receiving party won't receive the media), optional (the receiving party must choose whether to receive or not the media, the decision must be in the answer).
via string <optional>

The network or communication method used to transmit the media. Built-in engines currently set this property to either net, indicating that the communication will be over IP, or pstn, indicating the telephony network will be used. Custom engines might set this property to additional values. The property is mandatory if at least one of tx and rx is not off.
engine string <optional>

The identifier of the engine handling the media. The property is mandatory if at least one of tx and rx is not off.

MediaOffer

Properties:
Name Type Attributes Description
Chat MediaOfferDetails <optional>

Chat offer
Voice MediaOfferDetails <optional>

Audio offer
Video MediaOfferDetails <optional>

Video offer
Screen MediaOfferDetails <optional>

Screen sharing offer

This type describes the message that a party sends to its communication peer when it wants to enable or disable one or more media channels. Each media that is not mentioned in the offer will be treated as having an off offer. The response to a MediaOffer must be a MediaState describing. NOTE: tx and rx are always relative to who's reading the message (the library takes care of swapping them when transmitting the data)

Examples

Sample media state, seen from the side that received the request

 {
   "Sharing": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": "optional",
     "rx": "required",
     "via": "net",
     "engine": "WebRTC"
   }
 }

Sample answer accepting the request above, seen from the side that received the answer

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": true,
     "rx": false,
     "via": "net",
     "engine": "WebRTC"
   }
 }

Sample answer rejecting the request above: video rx was mandatory in the requested, and the answers has tx set to false

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": false,
     "rx": false,
     "via": "net",
     "engine": "WebRTC"
   }
 }

MediaStateDiffDetails

Properties:
Name Type Description
media object

The engine affected by the change, for each media that changed state.

Properties
Name Type Description
{Chat|Voice|Video|Sharing} string

Id of the engine that changed state.
engine object

The list of media affected by the change, for each media that changed state.

Properties
Name Type Description
{engine_id} Array.<string>

Media that changed state.

MediaStateDiff

Properties:
Name Type Description
added MediaStateDiffDetails

Info about media that was added (turned on) to the contact
removed MediaStateDiffDetails

Info about media that was removed (turned off) from the contact
changed MediaStateDiffDetails

Info about media that was already present and changed state (usually when the data property changes).

Describes the difference between two media state, usually the state before and after a state transition.

Examples

Sample diff of a contact activating a WebRTC audio session

 {
   "added": {
     "media": {
       "Voice": "WebRTC"
     },
     "engine": {
       "WebRTC": [
         "Voice"
       ]
     }
   },
   "removed": {
     "media": {
     },
     "engine": {
     }
   },
   "changed": {
     "media": {
     },
     "engine": {
     }
   }
 }

Sample diff of a chat terminating, stopping the sharing and chat media

 {
   "added": {
     "media": {
     },
     "engine": {
     }
   },
   "removed": {
     "media": {
       "Sharing": "Native",
       "Chat": "Native"
     },
     "engine": {
       "Native": [
         "Sharing",
         "Chat"
       ]
     }
   },
   "changed": {
     "media": {
     },
     "engine": {
     }
   }
 }

MediaCapabilities

Properties:
Name Type Attributes Description
Media object

Media capabilities

Properties
Name Type Attributes Description
Sharing object <optional>

Sharing capabilities

Properties
Name Type Attributes Description
FileTransfer boolean <optional>

Ability to send/receive file attachments
MaxFileSize number <optional>

Maximum attachment size in bytes
Engines object <optional>

Available media engines capable to doing Sharing

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Sharing: Native
Chat object <optional>

Chat capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Chat

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Chat: Native
Voice object <optional>

Audio capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Voice

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Voice: Native, WebRTC
Video object <optional>

Video capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Video

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Video: WebRTC
Screen object <optional>

Screensharing capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Screen

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Screen: WebRTC
Mobile boolean

The device using by the party is mobile
CoBrowsing boolean <optional>

Co-browsing supported
WebRTC object <optional>

WebRTC capabilities

Properties
Name Type Attributes Description
AudioCapture boolean <optional>

Party capable of capturing (e.g. allowed to access the microphone) and streaming audio
AudioConstraints boolean <optional>

Party capable of setting audio capture parameters (as opposed to only using the defaults provided by the browser/app)
VideoCapture boolean <optional>

Party capable of capturing (e.g. allowed to access the camera) and streaming video
VideoQuality boolean <optional>

Party capable of setting video capture parameters (as opposed to only using the defaults provided by the browser/app)
ScreenCapture boolean <optional>

Party capable of capturing and streaming the screen of the computer/mobile
Chrome boolean <optional>

Party using a Chrome-derived WebRTC endine
Firerox boolean <optional>

Party using a Mozilla-derived WebRTC endine
MediaAvailability object <optional>

Current availability or willingness to use different media types

Properties
Name Type Attributes Description
Sharing boolean <optional>

Sharing media availability
Chat boolean <optional>

Chat media availability
Voice boolean <optional>

Voice media availability
Video boolean <optional>

Video media availability
Screen boolean <optional>

Screen media availability

The MediaCapabilities describe which features a participant in a contact is able or willing to use. Additional custom capabilities can be freely added by third-party integration. The following list is therefore non-exhaustive and only describes builtin capapabilities.

ContactData

See the corresponding JSON Schema for further information.

DataCollection

Properties:
Name Type Description
name string

Name of the form
desc string

Human-readable name of the form
data Array.<object>

List of fields of the form

Properties
Name Type Description
name string

Name of the field
desc string

Human-readable name of the field
type string

Field type:

  • checkbox, a boolean value, use the property checked to store the value
  • date, a ISO8601 formatted date
  • email, an email address, the value of first field of this type is assumed to be the visitor's email
  • link, a HTTP/HTTPS URL
  • number, a number (integer or float)
  • phone, a E.164 formatted phone number
  • text, a text value
  • nickname, the value of first field of this type is assumed to be the visitor's nickname/diplay name
value *

The value of the field, for types other than checkbox
checked boolean

The value of the field, for checkboxes
visible boolean

If true, the field and its value are visible to the agent
editable boolean

If true, the agent is allowed to modify the value of the field. In case of edits, Vivocha stores also the original value and the id of the agent that changed it.

This type describes the format to attach user-defined data to a Vivocha contact. The data collection is a list of data forms, which are sets of fields, with their values and associated metadata. See the corresponding JSON Schema for further information.

Type:
  • Array.<object>

VisitData

See the corresponding JSON Schema for further information.

MediaStateDetails

Properties:
Name Type Attributes Description
tx boolean

The media is being transmitted to the remote.
rx boolean

The media is being accepted from the remote.
via string <optional>

The network or communication method used to transmit the media. Built-in engines currently set this property to either net, indicating that the communication will be over IP, or pstn, indicating the telephony network will be used. Custom engines might set this property to additional values. The property is mandatory if at least one of tx and rx is true.
engine string <optional>

The identifier of the engine handling the media. The property is mandatory if at least one of tx and rx is true.
data object <optional>

Opaque state info used by the media engine.

MediaState

Properties:
Name Type Attributes Description
Sharing MediaStateDetails

Sharing state, the state of the media used to communicate at a protocol level with the remote party, to enable features like co-browsing, form-sharing, page pushing and in general all forms of RPC
Chat MediaStateDetails <optional>

Chat state
Voice MediaStateDetails <optional>

Audio state
Video MediaStateDetails <optional>

Video state
Screen MediaStateDetails <optional>

Screen sharing state

Each property of a MediaState object represents the state of corresponding media. This type is used to both represent the current state of the media in a contact and to described a desired media transition. NOTE: tx and rx are always relative to who's reading the message (the library takes care of swapping them when transmitting the data)

Example

Sample media state

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC",
     "data": {
       "tx_stream": {
         "id": "oR9TTCaHtKz8C9Dn9ITUJ1KQcqFBDpLwbkqg",
         "url": "blob:https%3A//beta.vivocha.com/e021fa15-23ab-41de-9f09-8e5f661dc690"
       },
       "rx_stream": {
         "id": "Jkg2lX8Mw3WW1VUqRZMJmDDkwYEi6Olqky2d",
         "url": "blob:https%3A//beta.vivocha.com/87be3964-1391-4afb-ad6a-fc42abbd8618"
       }
     }
   },
   "Screen": {
     "rx": false,
     "engine": "WebRTC"
   }
 }

MediaOfferDetails

Properties:
Name Type Attributes Description
tx string

The transmission offer: can be required (if the receiving party accepts the offer, it must transmit the media), off (the receiving party must not transmit the media), optional (the receiving party must choose whether to transmit or not the media, the decision must be in the answer).
rx string

The reception offer: can be required (if the receiving party accepts the offer, it must be prepared to receive the media), off (the receiving party won't receive the media), optional (the receiving party must choose whether to receive or not the media, the decision must be in the answer).
via string <optional>

The network or communication method used to transmit the media. Built-in engines currently set this property to either net, indicating that the communication will be over IP, or pstn, indicating the telephony network will be used. Custom engines might set this property to additional values. The property is mandatory if at least one of tx and rx is not off.
engine string <optional>

The identifier of the engine handling the media. The property is mandatory if at least one of tx and rx is not off.

MediaOffer

Properties:
Name Type Attributes Description
Chat MediaOfferDetails <optional>

Chat offer
Voice MediaOfferDetails <optional>

Audio offer
Video MediaOfferDetails <optional>

Video offer
Screen MediaOfferDetails <optional>

Screen sharing offer

This type describes the message that a party sends to its communication peer when it wants to enable or disable one or more media channels. Each media that is not mentioned in the offer will be treated as having an off offer. The response to a MediaOffer must be a MediaState describing. NOTE: tx and rx are always relative to who's reading the message (the library takes care of swapping them when transmitting the data)

Examples

Sample media state, seen from the side that received the request

 {
   "Sharing": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": "optional",
     "rx": "required",
     "via": "net",
     "engine": "WebRTC"
   }
 }

Sample answer accepting the request above, seen from the side that received the answer

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": true,
     "rx": false,
     "via": "net",
     "engine": "WebRTC"
   }
 }

Sample answer rejecting the request above: video rx was mandatory in the requested, and the answers has tx set to false

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": false,
     "rx": false,
     "via": "net",
     "engine": "WebRTC"
   }
 }

MediaStateDiffDetails

Properties:
Name Type Description
media object

The engine affected by the change, for each media that changed state.

Properties
Name Type Description
{Chat|Voice|Video|Sharing} string

Id of the engine that changed state.
engine object

The list of media affected by the change, for each media that changed state.

Properties
Name Type Description
{engine_id} Array.<string>

Media that changed state.

MediaStateDiff

Properties:
Name Type Description
added MediaStateDiffDetails

Info about media that was added (turned on) to the contact
removed MediaStateDiffDetails

Info about media that was removed (turned off) from the contact
changed MediaStateDiffDetails

Info about media that was already present and changed state (usually when the data property changes).

Describes the difference between two media state, usually the state before and after a state transition.

Examples

Sample diff of a contact activating a WebRTC audio session

 {
   "added": {
     "media": {
       "Voice": "WebRTC"
     },
     "engine": {
       "WebRTC": [
         "Voice"
       ]
     }
   },
   "removed": {
     "media": {
     },
     "engine": {
     }
   },
   "changed": {
     "media": {
     },
     "engine": {
     }
   }
 }

Sample diff of a chat terminating, stopping the sharing and chat media

 {
   "added": {
     "media": {
     },
     "engine": {
     }
   },
   "removed": {
     "media": {
       "Sharing": "Native",
       "Chat": "Native"
     },
     "engine": {
       "Native": [
         "Sharing",
         "Chat"
       ]
     }
   },
   "changed": {
     "media": {
     },
     "engine": {
     }
   }
 }

MediaCapabilities

Properties:
Name Type Attributes Description
Media object

Media capabilities

Properties
Name Type Attributes Description
Sharing object <optional>

Sharing capabilities

Properties
Name Type Attributes Description
FileTransfer boolean <optional>

Ability to send/receive file attachments
MaxFileSize number <optional>

Maximum attachment size in bytes
Engines object <optional>

Available media engines capable to doing Sharing

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Sharing: Native
Chat object <optional>

Chat capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Chat

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Chat: Native
Voice object <optional>

Audio capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Voice

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Voice: Native, WebRTC
Video object <optional>

Video capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Video

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Video: WebRTC
Screen object <optional>

Screensharing capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Screen

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Screen: WebRTC
Mobile boolean

The device using by the party is mobile
CoBrowsing boolean <optional>

Co-browsing supported
WebRTC object <optional>

WebRTC capabilities

Properties
Name Type Attributes Description
AudioCapture boolean <optional>

Party capable of capturing (e.g. allowed to access the microphone) and streaming audio
AudioConstraints boolean <optional>

Party capable of setting audio capture parameters (as opposed to only using the defaults provided by the browser/app)
VideoCapture boolean <optional>

Party capable of capturing (e.g. allowed to access the camera) and streaming video
VideoQuality boolean <optional>

Party capable of setting video capture parameters (as opposed to only using the defaults provided by the browser/app)
ScreenCapture boolean <optional>

Party capable of capturing and streaming the screen of the computer/mobile
Chrome boolean <optional>

Party using a Chrome-derived WebRTC endine
Firerox boolean <optional>

Party using a Mozilla-derived WebRTC endine
MediaAvailability object <optional>

Current availability or willingness to use different media types

Properties
Name Type Attributes Description
Sharing boolean <optional>

Sharing media availability
Chat boolean <optional>

Chat media availability
Voice boolean <optional>

Voice media availability
Video boolean <optional>

Video media availability
Screen boolean <optional>

Screen media availability

The MediaCapabilities describe which features a participant in a contact is able or willing to use. Additional custom capabilities can be freely added by third-party integration. The following list is therefore non-exhaustive and only describes builtin capapabilities.

ContactData

See the corresponding JSON Schema for further information.

DataCollection

Properties:
Name Type Description
name string

Name of the form
desc string

Human-readable name of the form
data Array.<object>

List of fields of the form

Properties
Name Type Description
name string

Name of the field
desc string

Human-readable name of the field
type string

Field type:

  • checkbox, a boolean value, use the property checked to store the value
  • date, a ISO8601 formatted date
  • email, an email address, the value of first field of this type is assumed to be the visitor's email
  • link, a HTTP/HTTPS URL
  • number, a number (integer or float)
  • phone, a E.164 formatted phone number
  • text, a text value
  • nickname, the value of first field of this type is assumed to be the visitor's nickname/diplay name
value *

The value of the field, for types other than checkbox
checked boolean

The value of the field, for checkboxes
visible boolean

If true, the field and its value are visible to the agent
editable boolean

If true, the agent is allowed to modify the value of the field. In case of edits, Vivocha stores also the original value and the id of the agent that changed it.

This type describes the format to attach user-defined data to a Vivocha contact. The data collection is a list of data forms, which are sets of fields, with their values and associated metadata. See the corresponding JSON Schema for further information.

Type:
  • Array.<object>

VisitData

See the corresponding JSON Schema for further information.

MediaStateDetails

Properties:
Name Type Attributes Description
tx boolean

The media is being transmitted to the remote.
rx boolean

The media is being accepted from the remote.
via string <optional>

The network or communication method used to transmit the media. Built-in engines currently set this property to either net, indicating that the communication will be over IP, or pstn, indicating the telephony network will be used. Custom engines might set this property to additional values. The property is mandatory if at least one of tx and rx is true.
engine string <optional>

The identifier of the engine handling the media. The property is mandatory if at least one of tx and rx is true.
data object <optional>

Opaque state info used by the media engine.

MediaState

Properties:
Name Type Attributes Description
Sharing MediaStateDetails

Sharing state, the state of the media used to communicate at a protocol level with the remote party, to enable features like co-browsing, form-sharing, page pushing and in general all forms of RPC
Chat MediaStateDetails <optional>

Chat state
Voice MediaStateDetails <optional>

Audio state
Video MediaStateDetails <optional>

Video state
Screen MediaStateDetails <optional>

Screen sharing state

Each property of a MediaState object represents the state of corresponding media. This type is used to both represent the current state of the media in a contact and to described a desired media transition. NOTE: tx and rx are always relative to who's reading the message (the library takes care of swapping them when transmitting the data)

Example

Sample media state

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC",
     "data": {
       "tx_stream": {
         "id": "oR9TTCaHtKz8C9Dn9ITUJ1KQcqFBDpLwbkqg",
         "url": "blob:https%3A//beta.vivocha.com/e021fa15-23ab-41de-9f09-8e5f661dc690"
       },
       "rx_stream": {
         "id": "Jkg2lX8Mw3WW1VUqRZMJmDDkwYEi6Olqky2d",
         "url": "blob:https%3A//beta.vivocha.com/87be3964-1391-4afb-ad6a-fc42abbd8618"
       }
     }
   },
   "Screen": {
     "rx": false,
     "engine": "WebRTC"
   }
 }

MediaOfferDetails

Properties:
Name Type Attributes Description
tx string

The transmission offer: can be required (if the receiving party accepts the offer, it must transmit the media), off (the receiving party must not transmit the media), optional (the receiving party must choose whether to transmit or not the media, the decision must be in the answer).
rx string

The reception offer: can be required (if the receiving party accepts the offer, it must be prepared to receive the media), off (the receiving party won't receive the media), optional (the receiving party must choose whether to receive or not the media, the decision must be in the answer).
via string <optional>

The network or communication method used to transmit the media. Built-in engines currently set this property to either net, indicating that the communication will be over IP, or pstn, indicating the telephony network will be used. Custom engines might set this property to additional values. The property is mandatory if at least one of tx and rx is not off.
engine string <optional>

The identifier of the engine handling the media. The property is mandatory if at least one of tx and rx is not off.

MediaOffer

Properties:
Name Type Attributes Description
Chat MediaOfferDetails <optional>

Chat offer
Voice MediaOfferDetails <optional>

Audio offer
Video MediaOfferDetails <optional>

Video offer
Screen MediaOfferDetails <optional>

Screen sharing offer

This type describes the message that a party sends to its communication peer when it wants to enable or disable one or more media channels. Each media that is not mentioned in the offer will be treated as having an off offer. The response to a MediaOffer must be a MediaState describing. NOTE: tx and rx are always relative to who's reading the message (the library takes care of swapping them when transmitting the data)

Examples

Sample media state, seen from the side that received the request

 {
   "Sharing": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": "required",
     "rx": "required",
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": "optional",
     "rx": "required",
     "via": "net",
     "engine": "WebRTC"
   }
 }

Sample answer accepting the request above, seen from the side that received the answer

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": true,
     "rx": false,
     "via": "net",
     "engine": "WebRTC"
   }
 }

Sample answer rejecting the request above: video rx was mandatory in the requested, and the answers has tx set to false

 {
   "Sharing": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Chat": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "Native"
   },
   "Voice": {
     "tx": true,
     "rx": true,
     "via": "net",
     "engine": "WebRTC"
   },
   "Video": {
     "tx": false,
     "rx": false,
     "via": "net",
     "engine": "WebRTC"
   }
 }

MediaStateDiffDetails

Properties:
Name Type Description
media object

The engine affected by the change, for each media that changed state.

Properties
Name Type Description
{Chat|Voice|Video|Sharing} string

Id of the engine that changed state.
engine object

The list of media affected by the change, for each media that changed state.

Properties
Name Type Description
{engine_id} Array.<string>

Media that changed state.

MediaStateDiff

Properties:
Name Type Description
added MediaStateDiffDetails

Info about media that was added (turned on) to the contact
removed MediaStateDiffDetails

Info about media that was removed (turned off) from the contact
changed MediaStateDiffDetails

Info about media that was already present and changed state (usually when the data property changes).

Describes the difference between two media state, usually the state before and after a state transition.

Examples

Sample diff of a contact activating a WebRTC audio session

 {
   "added": {
     "media": {
       "Voice": "WebRTC"
     },
     "engine": {
       "WebRTC": [
         "Voice"
       ]
     }
   },
   "removed": {
     "media": {
     },
     "engine": {
     }
   },
   "changed": {
     "media": {
     },
     "engine": {
     }
   }
 }

Sample diff of a chat terminating, stopping the sharing and chat media

 {
   "added": {
     "media": {
     },
     "engine": {
     }
   },
   "removed": {
     "media": {
       "Sharing": "Native",
       "Chat": "Native"
     },
     "engine": {
       "Native": [
         "Sharing",
         "Chat"
       ]
     }
   },
   "changed": {
     "media": {
     },
     "engine": {
     }
   }
 }

MediaCapabilities

Properties:
Name Type Attributes Description
Media object

Media capabilities

Properties
Name Type Attributes Description
Sharing object <optional>

Sharing capabilities

Properties
Name Type Attributes Description
FileTransfer boolean <optional>

Ability to send/receive file attachments
MaxFileSize number <optional>

Maximum attachment size in bytes
Engines object <optional>

Available media engines capable to doing Sharing

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Sharing: Native
Chat object <optional>

Chat capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Chat

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Chat: Native
Voice object <optional>

Audio capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Voice

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Voice: Native, WebRTC
Video object <optional>

Video capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Video

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Video: WebRTC
Screen object <optional>

Screensharing capabilities

Properties
Name Type Attributes Description
Engines object <optional>

Available media engines capable to doing Screen

Properties
Name Type Attributes Description
{name} boolean <optional>

Builtin engines that support Screen: WebRTC
Mobile boolean

The device using by the party is mobile
CoBrowsing boolean <optional>

Co-browsing supported
WebRTC object <optional>

WebRTC capabilities

Properties
Name Type Attributes Description
AudioCapture boolean <optional>

Party capable of capturing (e.g. allowed to access the microphone) and streaming audio
AudioConstraints boolean <optional>

Party capable of setting audio capture parameters (as opposed to only using the defaults provided by the browser/app)
VideoCapture boolean <optional>

Party capable of capturing (e.g. allowed to access the camera) and streaming video
VideoQuality boolean <optional>

Party capable of setting video capture parameters (as opposed to only using the defaults provided by the browser/app)
ScreenCapture boolean <optional>

Party capable of capturing and streaming the screen of the computer/mobile
Chrome boolean <optional>

Party using a Chrome-derived WebRTC endine
Firerox boolean <optional>

Party using a Mozilla-derived WebRTC endine
MediaAvailability object <optional>

Current availability or willingness to use different media types

Properties
Name Type Attributes Description
Sharing boolean <optional>

Sharing media availability
Chat boolean <optional>

Chat media availability
Voice boolean <optional>

Voice media availability
Video boolean <optional>

Video media availability
Screen boolean <optional>

Screen media availability

The MediaCapabilities describe which features a participant in a contact is able or willing to use. Additional custom capabilities can be freely added by third-party integration. The following list is therefore non-exhaustive and only describes builtin capapabilities.