Basic Usage

To use the SDK, you will need Cisco Webex integration credentials. If you do not already have a Cisco Webex account, visit the Cisco Webex for Developers portal to create your account and register an integration. Your app will need to authenticate users via an OAuth grant flow for existing Cisco Webex users or a JSON Web Token for guest users without a Cisco Webex account.

See the Android SDK area of the Cisco Webex for Developers site for more information about this SDK.

Examples

Here are some examples of how to use the Android SDK in your app.

Create a new Webex instance using Webex ID authentication (OAuth-based):

val clientId: String = "YOUR_CLIENT_ID"
val clientSecret: String = "YOUR_CLIENT_SECRET"
val redirectUri: String = "https://webexdemoapp.com"
val scope: String = "spark:all"
val email = "EMAIL_ID_OF_END_USER" // Get email id from end user

val authenticator: OAuthWebViewAuthenticator = OAuthWebViewAuthenticator(clientId, clientSecret, scope, redirectUri, email)
val webex = Webex(application, authenticator)
webex.enableConsoleLogger(true)
webex.setLogLevel(LogLevel.VERBOSE) // Highly recommended to make this end-user configurable incase you need to get detailed logs.

webex.initialize(CompletionHandler { result ->
    if (result.error == null) {
        //already authorised
    } else {
        authenticator.authorize(loginWebview, CompletionHandler { result ->
                if (result.error != null) {
                    //Handle the error
                }else{
                    //Authorization Successful
                    webex.spaces.setOnInitialSpacesSyncCompletedListener( CompletionHandler { result->
                        if(result.isSuccessful){
                           //Initial Sync successful
                        } 
                    }
                }
            })
    }
})

Create a new Webex instance using JWT authentication

val token: String = "jwt_token"
val authenticator: JWTAuthenticator = JWTAuthenticator()
val webex = Webex(application, authenticator)
webex.initialize(CompletionHandler { result ->
    if (result.error == null) {
        //already authorised
    } else {
        authenticator.authorize(token, CompletionHandler { result ->
                if (result.error != null) {
                    //Handle the error
                }else{
                    //Authorization Successful
                    webex.spaces.setOnInitialSpacesSyncCompletedListener( CompletionHandler { result->
                        if(result.isSuccessful){
                            //Initial Sync successful
                        } 
                    }
                }
            })
    }
})

Create a new Webex instance using access token authentication

 val token: String = "<your-access-token>"
 val expiryInSeconds = 60      //expiry time in seconds
 val authenticator: TokenAuthenticator = TokenAuthenticator()
 val webex = Webex(application, authenticator)
 webex.initialize(CompletionHandler { result ->
     if (result.error == null) {
         //already authorised
     } else {
         authenticator.authorize(token, expiryInSeconds, CompletionHandler { result ->
                 if (result.error != null) {
                     //Handle the error
                 }else{
                     //Authorization successful
                     webex.spaces.setOnInitialSpacesSyncCompletedListener( CompletionHandler { result->
                         if(result.isSuccessful){
                             ///Initial Sync successful
                         } 
                     }
                 }
             })
     }
 })

Extend the WebexAuthDelegate interface to receive all authentication-related event callbacks.

interface WebexAuthDelegate {
    /**
    * This will notify when user is logged out and re login is required
    */
    fun onReLoginRequired() {}
}

Example usage:

class SomeClass : WebexAuthDelegate {
    ...
    override onReLoginRequired() {
        // Handle signout and perform any cleanup if required.
    }
    ...
}

Create a new Cisco Webex space, add users to the space, and send a message:

// Create a Cisco Webex space:
webex.spaces.create("Hello World", null, CompletionHandler<Space?> { result ->
    if (result.isSuccessful) {
        val space = result.data
    } else {
        val error= result.error
    }
})

// Add a user to a space:
webex.memberships.create("spaceId", null, "[email protected]", true, CompletionHandler<Membership?> { result ->
    if (result.isSuccessful) {
        val space = result.data
    } else {
        val error= result.error
    }
})

// Send a message to a space:
webex.messages.postToSpace("spaceId", Message.Text.plain("Hello"), null, null, CompletionHandler<Message> { result ->
    if(result != null && result.isSuccessful){
        val message = result.data
    }
})

Make an outgoing call:

Use the webex.phone.dialPhoneNumber() api to dial phone numbers. Incase of meeting links, meeting ids, spaces(only 1:1 spaces), meeting numbers, sip uris and email addresses, you can use the regular webex.phone.dial() api. If you use webex.phone.dialPhoneNumber()to dial anything other than phone numbers, you will get a call failure with INVALID_API_ERROR. e.g:

    val mediaOption = MediaOption.audioOnly()
    webex.phone.dialPhoneNumber("+1800123456", mediaOption, CompletionHandler { result ->
        if (result.isSuccessful) {
            // Call started successfully, result.data gives you a Call object
        } else {
            // Call failed, result.error gives you the error code. The error code will be an instance of WebexError.ErrorCode
        }
    })

webex.phone.dial("[email protected]", MediaOption.audioVideo(local, remote), CompletionHandler {
    val call = it.data
    call?.setObserver(object : CallObserver {
        override fun onConnected(call: Call?) {
            super.onConnected(call)
        }

        override fun onDisconnected(event: CallDisconnectedEvent?) {
            super.onDisconnected(event)
        }

        override fun onFailed(call: Call?) {
            super.onFailed(call)
        }
    })
})

NOTE: The dialPhoneNumber API is available from v3.9.2 onwards

Receive a call:

webex.phone.setIncomingCallListener(object : Phone.IncomingCallListener {
    override fun onIncomingCall(call: Call?) {
        call?.answer(MediaOption.audioOnly(), CompletionHandler {
            if (it.isSuccessful){
                // ...
            }
        })
    }
})

Make a space call:

webex.phone().dial(spaceId, MediaOption.audioVideoSharing(Pair(localView,remoteView), screenShareView), CompletionHandler { result ->
    if (result.isSuccessful) {
        result.data?.let { _call ->
            // Space call connected. Set observer to listen for call events
            call.setObserver(object : CallObserver {
                override fun onConnected(call: Call?) {
                }

                override fun onRinging(call: Call?) {
                }

                override fun onWaiting(call: Call?, reason: Call.WaitReason?) {
                }

                override fun onDisconnected(event: CallObserver.CallDisconnectedEvent?) {
                }

                override fun onInfoChanged(call: Call?) {
                }

                override fun onMediaChanged(event: CallObserver.MediaChangedEvent?) {
                }

                override fun onCallMembershipChanged(event: CallObserver.CallMembershipChangedEvent?) {
                }

                override fun onScheduleChanged(call: Call?) {
                }
            })
        }
    } else {
        result.error?.let { errorCode ->
            // Error in space call
        }
    }
});

NOTE: Creating an instant meeting by dialing into a space is deprecated. A meeting can be created using the meetings endpoint and can be joined in SDK client using the meeting link or meeting ID.

Screen sharing:

webex.phone.dial("spaceId", MediaOption.audioVideoSharing(Pair(localView, remoteView), screenShareView), CompletionHandler {
    if(it.isSuccessful){
        val call = it.data
        call?.setObserver(object :CallObserver{
            override fun onConnected(call: Call?) {
                super.onConnected(call)
            }

            // ...

            override fun onMediaChanged(event: CallObserver.MediaChangedEvent?) {
                event?.let { _event ->
                    val _call = _event.getCall()
                    when (_event) {
                        is CallObserver.RemoteSendingSharingEvent -> {
                            if (_event.isSending()) {
                                _call?.setSharingRenderView(screenShareView)
                            } else {
                                _call??.setSharingRenderView(null)
                            }
                        }
                    }
                }
            }
        })
    } else {
        val error = it.error
    }
})

Start/stop sharing screen:

```kotlin
call.startSharing(CompletionHandler {
   if (it.isSuccessful){
      // ...
   }
})
call.stopSharing(CompletionHandler {
   if (it.isSuccessful){
      // ...
   }
})
```

Post a message

webex.messages.post(targetId, Message.draft(Message.Text.markdown("**Hello**", null, null)).addAttachments(localFile), CompletionHandler { result ->
    if (result.isSuccessful) {
        //message sent success
    } else {
        val error = result.error
        //message sent failed
    }
})

Post a threaded message

webex.messages.post(targetId, Message.draft(Message.Text.markdown("**Hello**", null, null))
.addAttachments(localFile)
.setParent(parentMessage),
CompletionHandler { result ->
    if (result.isSuccessful) {
        //message sent success
    } else {
        val error = result.error
        //message sent failed
    }
})

Set MessageObserver to receive messaging events

webex.messages.setMessageObserver(object : MessageObserver {
    override fun onEvent(event: MessageObserver.MessageEvent) {
        when (event) {
            is MessageObserver.MessageReceived -> {
                val message = event.getMessage()
                if (message?.getParentId() != null) {
                    // Threaded message
                }
            }
            is MessageObserver.MessageDeleted -> {
                // message deleted
            }
            is MessageObserver.MessageFileThumbnailsUpdated -> {
                // thumbnails updated for files
            }
            is MessageObserver.MessageEdited -> {
                // message edited successfully. event.getMessage() returns the edited message.
            }
        }
    }
})

Send Read Receipts

 //Mark all existing messages in space as read
 webex.messages.markAsRead(spaceId)

 //Mark existing message before pointed message(include) in space as read
 webex.message.markAsRead(spaceId, messageId)

 //Mark existing message before pointed message(include) in space as read with a completion handler
 webex.message.markAsRead(spaceId, messageId, CompletionHandler { result ->
    if (result.isSuccessful) {
        // Success
    } else {
        // Failure
    }
})

Get read status of a space

webex.spaces.getWithReadStatus(spaceId, CompletionHandler { result ->
    if (result.isSuccessful) {
        //show the data
    } else {
        //handle error
    }
})

Set MembershipObserver to receive Membership events

webex.memberships.setMembershipObserver(object : MembershipObserver {
    override fun onEvent(event: MembershipObserver.MembershipEvent?) {
        when (event) {
            is MembershipObserver.MembershipCreated -> {
                //The event when a new membership has added to a space.
                ...
            }
            is MembershipObserver.MembershipUpdated -> {
                //The event when a membership moderator status changed
                ...
            }
            is MembershipObserver.MembershipDeleted -> {
                //The event when a membership has been removed from a space.
                ...
            }
            is MembershipObserver.MembershipMessageSeen -> {
                //The event when a user has sent a read receipt
                ...
            }
        }
    }
})

Set SpaceObserver to receive Space events

webex.spaces.setSpaceObserver(object : SpaceObserver {
    override fun onEvent(event: SpaceObserver.SpaceEvent) {
        when (event) {
            is SpaceObserver.SpaceCallStarted -> {
                //The event when a space call was started
                ...
            }
            is SpaceObserver.SpaceCallEnded -> {
                //The event when a space call has ended
                ...
            }
            is SpaceObserver.SpaceCreated -> {
                //The event when a new space was created
                ...
            }
            is SpaceObserver.SpaceUpdated -> {
                //The event when a space was changed (usually a rename)
                ...
            }
        }
    }
})

Get space meeting details

webex.spaces().getMeeting(spaceId, new CompletionHandler<SpaceMeeting>() {
    @Override
    public void onComplete(Result<SpaceMeeting> result) {
        if (result.isSuccessful()){
            SpaceMeeting spaceMeeting = result.getData();
            ...
        }
    }
});

Get read status of a space

webex.spaces().getWithReadStatus(spaceId, new CompletionHandler<SpaceReadStatus>() {
    @Override
    public void onComplete(Result<SpaceReadStatus> result) {
        if (result.isSuccessful()){
            SpaceReadStatus spaceReadStatus = result.getData();
            ...
        }
    }
});

Join password-protected meetings

mediaOption.setModerator(isModerator: Boolean)
mediaOption.setPin(pin: String)

Change the composite video layout during a call

activeCall.setCompositedVideoLayout(layout: MediaOption.CompositedVideoLayout)

Specify how the remote video adjusts its content to be rendered in a view

activeCall.setRemoteVideoRenderMode(mode);

Use a completion handler to get the result of success or failure.

activeCall..setRemoteVideoRenderMode(mode, CompletionHandler {
    it.let {
        if (it.isSuccessful) {
            // callback returned success
        } else {
            // callback returned failure
        }
    }
})

Change the max sending fps for video

webex.phone.setAdvancedSetting(AdvancedSetting.VideoMaxTxFPS(value: Int) as AdvancedSetting<*>)

Enable(disable) android.hardware.camera2

webex.phone.setAdvancedSetting(AdvancedSetting.VideoEnableCamera2(value: Boolean) as AdvancedSetting<*>)

Whether the app can continue video streaming when the app is in background
```
webex.phone.enableBackgroundStream(enable: Boolean)
```

Get a list of spaces that have an ongoing call

webex.spaces.listWithActiveCalls(CompletionHandler { result ->
    if (result.isSuccessful) {
        // callback returned success, result.data gives data if any
    } else {
        // callback returned failure
    }
})

Check if the message mentioned everyone in space
```
message.isAllMentioned()
```
Get all people mentioned in the message
```
message.getMentions()
```

Change the max capture fps when screen sharing

webex.phone.setAdvancedSetting(AdvancedSetting.ShareMaxCaptureFPS(value: Int) as AdvancedSetting<*>)

Switch the audio play output mode during a call

activeCall.switchAudioOutput(mode: Call.AudioOutputMode);

Enable/Disable Background Noise Removal(BNR)

webex.phone.enableAudioBNR(enable: Boolean)

Set Background Noise Removal(BNR) mode

webex.phone.setAudioBNRMode(mode: Phone.AudioBRNMode)

Edit a message

webex.messages.edit(originalMessage, messageText, mentions, CompletionHandler { result ->
    if (result.isSuccessful) {
        // message edit success
        val editedMessage = result.data
    } else {
        // message edit failure
    }
})

Enable/Disable background connection

webex.phone.enableBackgroundConnection(enable: Boolean)

Enable/Disable console logging

webex.enableConsoleLogger(enable: Boolean)

Set log level of logging
```
webex.setLogLevel(logLevel: LogLevel)
```

Get the supported product mode capabilities for the current user

var capability = webex.people.getProductCapability()
var hasCalling = capability.isCallingSupported()
var hasMessaging = capability.isMessagingSupported()
var hasMeeting = capability.isMeetingSupported()

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Basic Usage

Examples

Clone this wiki locally