webex-js-sdk

webex-js-sdk

webex

The Cisco Webex JS SDK

Install

Usage

All of the examples in these API docs assume you've gotten an authenticated Webex instance (unless otherwise specified) using one of the methods below.

webex has three basic modes of operation:

Shell Script (Quick Start)

This is the quickest way to get up and running with our JavaScript SDK. Simply set the environment variable WEBEX_ACCESS_TOKEN to your access token and add the following line at the top of your JavaScript file to get a ready-to-use instance.

You can get your WEBEX_ACCESS_TOKEN from the Cisco Webex for Developers portal.

webex/env is also a great way to get started with bots.

Browser

Our JavaScript SDK provides out-of-the-box support for the OAuth 2.0 Implicit Grant Flow.

You'll need to register an OAuth Client to get your "authorization string"

Use the steps under Bundling (or something similar) to get the SDK into your browser, then use the following JavaScript to get started:

Bundling

You'll need to bundle the SDK to use it in a web browser. Right now, we do all our SDK testing with Browserify, but our Cisco Webex Widgets use webpack.

The following snippet is the bare minimum to get our code into a form suitable for a web browser. You'll probably want to additionally pipe it through a minifier like UglifyJS before going to production.

Then, just load your bundle using:

NodeJS

Though the implicit flow is great for single page apps, it's not ideal for integrations that might need to do things on your users' behalf months in the future. We additionally support the OAuth 2.0 Authorization Code Grant flow, but due to its complexity, there's a bit you'll need to wire up in your app to take advantage of it. The following is an example of how an Express app might do authentication.

See Browser Guide and Server Guide

new Webex()
Related
Browser Guide Server Guide
Static Members
init(attrs)

Authorization

Browser support for OAuth2. Automatically parses the URL hash for an access token

new AuthorizationBrowser()
Instance Members
isAuthorizing
initiateLogin(options)
initiateImplicitGrant(options)
initiateAuthorizationCodeGrant(options)
requestAccessTokenFromJwt(options)
logout(options)

NodeJS support for OAuth2

new AuthorizationNode()
Instance Members
isAuthorizing
requestAuthorizationCodeGrant(options)
requestAccessTokenFromJwt(options)

Meetings

Maintain a cache of meetings and sync with services.

new Meetings(args: ...any)

Extends WebexPlugin

Parameters
args (...any)
Static Members
register()
unregister()
createNoiseReductionEffect
createVirtualBackgroundEffect
getReachability()
startReachability()
getPersonalMeetingRoom()
create(destination, type = null, useRandomDelayForInfo, infoExtraParams, correlationId, failOnMissingMeetingInfo, callStateForMetrics, meetingInfo = undefined, meetingLookupUrl = undefined)
getMeetingByType(type, value)
getAllMeetings()
syncMeetings(keepOnlyLocusMeetings)
sortLocusArrayToUpdate(loci)
checkHandleBreakoutLocus(newCreatedLocus)
Instance Members
personalMeetingRoom
registered
uploadLogs(options)
getLogger()
propertyName
propertyName
Events
meetings:ready
network:disconnected
meetings:registered
meeting:removed
meeting:added

Meeting is the crux of the plugin

new Meeting()
Static Members
fetchMeetingInfo(options)
verifyPassword(password, captchaCode, sendCAevents)
refreshCaptcha()
postMetrics(eventName)
invite(invitee, alertIfActive = true)
cancelPhoneInvite(invitee)
admit(memberIds, sessionLocusUrls)
remove(memberId)
mute(memberId, mute)
transfer(memberId, moderator)
getMembers()
uploadLogs(options)
closeRemoteStream()
closeRemoteStreams()
setMercuryListener()
closePeerConnections()
unsetPeerConnections()
setCorrelationId(id)
updateCallStateForMetrics(callStateForMetrics)
muteAudio()
unmuteAudio()
muteVideo()
unmuteVideo()
joinWithMedia(options)
reconnect(options)
usePhoneAudio(phoneNumber)
disconnectPhoneAudio()
moveTo(resourceId)
moveFrom(resourceId)
addMedia(options, turnServerInfo)
processNextQueuedMediaUpdate
updateMedia(options)
acknowledge(type)
decline(reason)
leave(options)
startWhiteboardShare(channelUrl, resourceToken)
stopWhiteboardShare(channelUrl)
startRecording()
setMuteOnEntry(enabled)
setDisallowUnmute(enabled)
setMuteAll(mutedEnabled, disallowUnmuteEnabled, muteOnEntryEnabled)
stopRecording()
pauseRecording()
resumeRecording()
lockMeeting()
unlockMeeting()
sendDTMF(tones)
changeVideoLayout(layoutType?, renderInfo)
endMeetingForAll()
clearMeetingData
sendReaction(reactionType, skinToneType)
toggleReactions(enable)
Instance Members
callStateForMetrics
simultaneousInterpretation
annotation
receiveSlotManager
mediaRequestManagers
meetingFiniteStateMachine
mediaConnections
isMultistream
mediaProperties
networkStatus
passwordStatus
requiredCaptcha
recordingController
controlsOptionsManager
remoteMediaManager
turnDiscoverySkippedReason
turnServerUsed
getWebexObject()
isLocusCall()
correlationId
correlationId
injectMeetingInfo(meetingInfo, fetchParams, meetingLookupUrl)
refreshPermissionToken(reason?)
handleDataChannelUrlChange(datachannelUrl)
setSelfUserPolicies()
setPermissionTokenPayload(permissionToken)
unsetRemoteStreams()
cleanupLocalStreams()
isTranscriptionSupported()
isReactionsSupported()
setCaptionLanguage(language)
setSpokenLanguage(language)
startTranscription(options)
stopTranscription()
updateLLMConnection(datachannelUrl)
handleRoapFailure
roapMessageReceived
setupSdpListeners
canUpdateMedia()
buildLeaveFetchRequestOptions(options)
setRemoteQualityLevel(level)
getCurUserType()
enableMusicMode(shouldEnableMusicMode)
setSendNamedMediaGroup(mediaType, languageCode)
publishStreams(streams)
unpublishStreams(streams)
getPermissionTokenExpiryInfo()
checkAndRefreshPermissionToken(threshold, reason)
Events
meeting:stateChange
media:ready
media:stopped
meeting:ringing
meeting:ringingStop
meeting:startedSharingLocal
meeting:stoppedSharingLocal
meeting:startedSharingRemote
meeting:stoppedSharingRemote
meeting:locked
meeting:unlocked
meeting:actionsUpdate
meeting:self:unmutedByOthers
meeting:self:mutedByOthers
meeting:self:requestedToUnmute
meeting:self:guestAdmitted
meeting:self:lobbyWaiting
meeting:self:left
meeting:reconnectionStarting
meeting:reconnectionSuccess
meeting:reconnectionFailure
network:quality

Messaging

Messages are how people communicate in rooms. Each message timestamped and represented in Webex as a distinct block of content. Messages can contain plain text and a single file attachment. See the Message Attachments Guide for a list of supported media types.

new Messages()
Instance Members
listen()
listen()
create(message)
update(message, altMessage)
get(message)
list(options)
remove(message)

Resources

These are the resources provided by Webex instances for interacting with our developer API

Memberships represent a person's relationship to a room. Use this API to list members of any room that you're in or create memberships to invite someone to a room. Memberships can also be updated to make someone a moderator or deleted to remove them from the room.

new Memberships()
Instance Members
listen()
create(membership)
get(membership)
list(options)
listWithReadStatus(options)
remove(membership)
update(membership)
updateLastSeen(message)
new People()
Instance Members
get(person)
list(options, showAllTypes)

Rooms are virtual meeting places for getting stuff done. This resource represents the room itself. Check out the Memberships API to learn how to add and remove people from rooms and the Messages API for posting and managing content.

new Rooms()
Instance Members
listen()
create(room)
get(room, options)
list(options)
listWithReadStatus(maxRecent)
getWithReadStatus(roomId)
remove(room)
update(room)
new Teams()
Instance Members
create(team)
get(team, options)
list(options)
update(team)

Team Memberships represent a person's relationship to a team. Use this API to list members of any team that you're in or create memberships to invite someone to a team. Team memberships can also be updated to make someone a moderator or deleted to remove them from the team.

Just like in the Webex app, you must be a member of the team in order to list its memberships or invite people.

new TeamMemberships()
Instance Members
create(membership)
get(membership)
list(options)
remove(membership)
update(membership)

Webhooks allow your app to be notified via HTTP when a specific event occurs on Webex. For example, your app can register a webhook to be notified when a new message is posted into a specific room.

new Webhooks()
Instance Members
create(webhook)
get(webhook)
list(options)
remove(webhook)
update(webhook)

Logging

new Logger()
Instance Members
formatLogs()
LoggerConfig

Type: Object

Properties
level (string?) : Maximum log level that should be printed to the console. One of silent|error|warn|log|info|debug|trace
historyLength (number?) : Maximum number of entries to store in the log buffer.
Example
{
  level: process.env.WEBEX_LOG_LEVEL,
  historyLength: 1000
}

Types

The following typedefs describes the responses of the various API calls.

MembershipObject

Type: Object

Properties
id (string) : Unique identifier for the membership
roomId (string) : The room ID
personId (string) : The person ID
personEmail (email) : The email address of the person / room member
isModerator (boolean) : Indicates whether the specified person should be a room moderator
isMonitor (boolean) : Indicates whether the specified member is a room monitor
created (isoDate) : The date and time that this membership was created
MessageObject

Type: Object

Properties
id (string) : (server generated) Unique identifier for the message
personId (string) : The ID for the author of the message
personEmail (email) : The email for the author of the message
roomId (string) : The ID for the room of the message
text (string) : The message posted to the room in plain text
markdown (string) : The message posted to the room in markdown
files (Array<string>) : The source URL(s) for the message attachment(s). See the Message Attachments Guide for a list of supported media types.
created (isoDate) : (server generated) The date and time that the message was created
PersonObject

Type: Object

Properties
id (string) : (server generated) Unique identifier for the person
emails (Array<email>) : Email addresses of the person
displayName (string) : Display name of the person
created (isoDate) : (server generated) The date and time that the person was created
RoomObject

Type: Object

Properties
id (string) : (server generated) Unique identifier for the room
title (string) : The display name for the room. All room members will see the title so make it something good
teamId (string) : (optional) The ID of the team to which the room belongs
created (isoDate) : (server generated) The date and time that the room was created
TeamObject

Type: Object

Properties
id (string) : (server generated) Unique identifier for the team
name (string) : The name of the team
created (isoDate) : (server generated) The date and time that the team was created
TeamMembershipObject

Type: Object

Properties
id (string) : (server generated) Unique identifier for the team membership
teamId (string) : The team ID
personId (string) : The person ID
personEmail (string) : The email address of the person
isModerator (boolean) : Set to true to make the person a team moderator
created (string) : (server generated) The date and time that the team membership was created
WebhookObject

Type: Object

Properties
id (string) : (server generated) Unique identifier for the webhook
resource (string) : The resource type for the webhook
event (string) : The event type for the webhook
filter (string) : The filter that defines the webhook scope
targetUrl (string) : The URL that receives POST requests for each event
name (string) : A user-friendly name for this webhook
created (string) : (server generated) The date and time that the webhook was created

An email address, as a string.

email

Type: string

The date and time, specified in ISO 8601 extended offset date/time format (e.g. 2015-10-18T14:26:16+00:00).

isoDate

Type: string

AttachmentActionObject

Type: Object

Properties
id (string) : (server generated) Unique identifier for the attachment action
messageId (string) : The ID of the message in which attachment action is to be performed
type (string) : The type of attachment action eg., submit
inputs (Object) : The inputs for form fields in attachment message
personId (string) : (server generated) The ID for the author of the attachment action
roomId (string) : (server generated) The ID for the room of the message
created (isoDate) : (server generated) The date and time that the message was created

AttachmentActions are events that communicate information when a user clicks on an Action.Submit button in a card displayed in Webex Information conveyed in an AttachmentAction includes details about the user that clicked the button along with any card specific inputs. See the Attachments Actions API Documentation for more details

new AttachmentActions()
Instance Members
create(attachmentAction)
get(attachmentAction)

Gets a list of all recent devices associated with the user the device list gets populated from Redis

getAll(): Promise<Device>
Returns
Promise<Device>:

Gets a list of all recent devices associated with the user the device list gets populated from Redis

refresh(): Promise<Device>
Returns
Promise<Device>:

Search for a device by name

search(options: Object): Promise<Device>
Parameters
options (Object)
Name Description
options.searchQuery string
Returns
Promise<Device>:

Caches the device info and also registers to Redis for subsequent fetches

upsert(device: Object): deviceInfo
Parameters
device (Object)
Name Description
device.id string
Returns
deviceInfo:

Retreives device info of a particular device

get(token: string): Promise<deviceInfo>
Parameters
token (string)
Returns
Promise<deviceInfo>:

Unregisters the device from Redis, will not fetch in subsequent loads, similar to space.deleteBinding()

remove(deviceId: string): Promise<deviceInfo>
Parameters
deviceId (string)
Returns
Promise<deviceInfo>:

Requests to display PIN on the device

requestPin(device: object, options: object): Promise<deviceInfo>
Parameters
device (object)
options (object = {})
Name Description
options.data object
Returns
Promise<deviceInfo>:

pairs the device with the user (manual pairing), also adds it to user's recents list for subsequent fetches. similar to space.join()

pair(options: object): Promise<deviceInfo>
Parameters
options (object = {})
Name Description
options.pin number
Returns
Promise<deviceInfo>:

unpairs the device with the user (manual/ultrasonic pairing), but still keeps in the recents list/does not remove from Redis options.removeAllDevices will remove all associated devices to user similar to space.leave()

unpair(options: object): Promise<deviceInfo>
Parameters
options (object = {})
Name Description
options.removeAllDevices boolean
Returns
Promise<deviceInfo>:

binds the space to the paired device (if supported) similar to space.bindConversation()

bindSpace(options: object): Promise<deviceInfo>
Parameters
options (object = {})
Name Description
options.url boolean , conversation url
options.kmsResourceObjectUrl boolean of the convo
Returns
Promise<deviceInfo>:

unbinds the space to the paired device (if supported) similar to space.unbindConversation()

unbindSpace(): Promise<deviceInfo>
Returns
Promise<deviceInfo>:

Gets the audio state of the paired device similar to device.getAudioState()

getAudioState(): Promise<audioState>
Returns
Promise<audioState>:

Updates audio state of the paired device, should be called every 10 minutes or when mic or volume state is changed similar to device.putAudioState()

putAudioState(space: object, audioState: object): Promise<audioState>
Parameters
space (object)
audioState (object = {})
Returns
Promise<audioState>:

Mutes paired device similar to device.mute()

mute(): Promise<audioState>
Returns
Promise<audioState>:

Unmutes paired device similar to device.unmute()

unmute(): Promise<audioState>
Returns
Promise<audioState>:

Increases paired device's volume similar to device.increaseVolume()

increaseVolume(): Promise<audioState>
Returns
Promise<audioState>:

Decreases paired device's volume similar to device.decreaseVolume()

decreaseVolume(): Promise<audioState>
Returns
Promise<audioState>:

Sets paired device's volume but should use increase and decrease api instead similar to device.setVolume()

setVolume(level: number): Promise<audioState>
Parameters
level (number = 0)
Returns
Promise<audioState>:

Utility function to update decrypted device name on device object

_updateDeviceMetadata(deviceArray: Array): device
Parameters
deviceArray (Array = [])
Returns
device:

Utility function to update decrypted device name on device object

_decryptDeviceName(inDevice: object): device
Parameters
inDevice (object = {})
Returns
device:

Utility function to update device info on mercury updates

_receiveDeviceUpdates(device: object): device
Parameters
device (object)
Returns
device:
new LogsRequest()
Static Members
uploadLogs(options)

MediaDirection

MediaDirection

Type: Object

Properties
sendAudio (boolean)
receiveAudio (boolean)
sendVideo (boolean)
receiveVideo (boolean)
sendShare (boolean)
receiveShare (boolean)

MediaDirection

MediaDirection

Type: Object

Properties
sendAudio (boolean)
receiveAudio (boolean)
sendVideo (boolean)
receiveVideo (boolean)
sendShare (boolean)
receiveShare (boolean)
isSharing (boolean)

SendOptions

SendOptions

Type: Object

Properties
sharePreferences (Object)
Media

Type: any

Static Members
getLocalMedia(options, config)
createMediaConnection(isMultistream, debugId, webex, meetingId, correlationId, options)
getDisplayMedia(options, config)
getMedia(audio, video, config)
toggleStream()
stopStream(stream)
getUserMedia(mediaSetting, audioVideo, sharePreferences, config)

Rtc Metrics

new RtcMetrics(webex: object, meetingId: string, correlationId: string)
Parameters
webex (object) The main webex object.
meetingId (string) The meeting id.
correlationId (string) The correlation id.
Instance Members
metricsQueue
sendMetricsInQueue()
addMetrics(data)
closeMetrics()
anonymizeIp(stats)

Returns the current state of knowledge about whether we are on an ipv4-only or ipv6-only or mixed (ipv4 and ipv6) network. The return value matches the possible values of "ipver" parameter used by the backend APIs.

getIpVersion(webex: Object): (IP_VERSION | undefined)
Parameters
webex (Object) webex instance
Returns
(IP_VERSION | undefined): ipver value to be passed to the backend APIs or undefined if we should not pass any value to the backend

Returns options for leaving a meeting.

prepareLeaveMeetingOptions(meeting: any, options: any): any
Parameters
meeting (any)
options (any = {})
Returns
any: leave options

Returns request options for leaving a meeting.

buildLeaveFetchRequestOptions(meeting: any, options: any): any
Parameters
meeting (any)
options (any = {})
Returns
any: request options

Adds the current locus sequence information to a request body

addSequence(meeting: Object, requestBody: Object): void
Parameters
meeting (Object) The meeting object
requestBody (Object) The body of a request to locus
Returns
void:

Updates the locus info for the meeting with the delta locus returned from requests that include the sequence information Returns the original response object

updateLocusWithDelta(meeting: Object, response: Object): Object
Parameters
meeting (Object) The meeting object
response (Object) The response of the http request
Returns
Object:

Returns a CA-recognized error payload for the specified raw error message/reason.

New errors can be added to this function for handling in the future

getChangeMeetingFloorErrorPayload(reason: String): Array<object>
Parameters
reason (String) the raw error message
Returns
Array<object>: an array of payload objects
new MeetingInfo()
Static Members
getMeetingInfo(id)
setMeetingInfo(id, info)
fetchInfoOptions(destination, type = null)
fetchMeetingInfo(destination, type = null, password = null, captchaInfo = null, installedOrgID = null, locusId = null, extraParams = {}, options = {})
fetchMeetingInfo(destination, type = null, password, captchaInfo, installedOrgID, locusId, extraParams, options)
createAdhocSpaceMeeting(conversationUrl, installedOrgID)
new MeetingInfo()
Static Members
getMeetingInfo(id)
setMeetingInfo(id, info)
fetchInfoOptions(destination, type = null)
fetchMeetingInfo(destination, type = null, password = null, captchaInfo = null, installedOrgID = null, locusId = null, extraParams = {}, options = {})
fetchMeetingInfo(destination, type = null, password, captchaInfo, installedOrgID, locusId, extraParams, options)
createAdhocSpaceMeeting(conversationUrl, installedOrgID)
new MeetingInfoCollection()
Static Members
get(id)
new MeetingInfoRequest()
Static Members
fetchMeetingInfo(options)
new MeetingInfoRequest()
Static Members
fetchMeetingInfo(options)
new MeetingInfoUtil()
Static Members
getResourceUrl(type, value)
getRequestBody(options)
getWebexSite(uri)
getDirectMeetingInfoURI(options)
new MeetingInfoUtil()
Static Members
getResourceUrl(type, value)
getRequestBody(options)
getWebexSite(uri)
getDirectMeetingInfoURI(options)
new PersonalMeetingRoom()
Static Members
claim(link, pin, preferred = true)
get(options)
Instance Members
claimPmr(options: Object): Promise
Parameters
options (Object) with format of {userId, passcode, meetingAddress, preferred}
Returns
Promise: returns a promise that resolves/rejects the result of the request

This is the type that matches what backend expects us to send to them. It is a bit weird, because it uses strings instead of booleans and numbers, but that's what they require.

TransportResultForBackend

Type: {reachable: ("true" | "false")?, latencyInMilliseconds: string?, clientMediaIPs: Array<string>?, untested: "true"?}

Properties
reachable (("true" | "false")?)
latencyInMilliseconds (string?)
clientMediaIPs (Array<string>?)
untested ("true"?)
new Reachability()
Static Members
gatherReachability()
isAnyPublicClusterReachable()
Instance Members
getReachabilityMetrics()
getReachabilityResults()
new ReachabilityRequest()
Instance Members
getClusters
remoteSDPForClusters

A class that handles reachability checks for a single cluster.

new ClusterReachability(name: string, clusterInfo: ClusterNode)
Parameters
name (string) cluster name
clusterInfo (ClusterNode) information about the media cluster
Instance Members
getResult()
start()

Converts a stun url to a turn url

convertStunUrlToTurn(stunUrl: string, protocol: ("tcp" | "udp")): string
Parameters
stunUrl (string) url of a stun server
protocol (("tcp" | "udp")) what protocol to use for the turn server
Returns
string: url of a turn server

Converts a stun url to a turns url

convertStunUrlToTurnTls(stunUrl: string): string
Parameters
stunUrl (string) url of a stun server
Returns
string: url of a turns server
new MeetingRequest()
Instance Members
getActiveMeetings()
fetchGeoHint()
getMeetingPreferences()
determineRedirections(responseBody)
joinMeeting(options)
getLocusDTO(options)
prepareLeaveMeetingRequestOptions(options)
leaveMeeting(options)
buildLeaveMeetingRequestOptions(options)
acknowledgeMeeting(options)
lockMeeting(options)
declineMeeting(options)
changeMeetingFloor(options)
sendDTMF(options)