Skip to content

Basic Usage

Jump to bottom
ciscoRankush edited this page Feb 13, 2024 · 8 revisions

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.

  1. 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
                        } 
                    }
                }
            })
    }
})

  2. 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
                        } 
                    }
                }
            })
    }
})

  3. 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
                         } 
                     }
                 }
             })
     }
 })

  4. 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, "person@example.com", 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
    }
})

  5. Make an outgoing call:

    Use the webex.phone.dialPhoneNumber() api to dial phone numbers. Incase of meeting links, 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("person@example.com", 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

  1. Receive a call:

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

  2. 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 dialling into a space is deprecated. A meeting can be created using meetings endpoint and that meeting can be joined in SDK client using meeting link or meeting id.

  1. 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
    }
})

  2. Start/stop sharing screen:

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

  3. 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
    }
})

  4. 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
    }
})

  5. 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.
            }
        }
    }
})

  6. 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
    }
})

  7. Get read status of a space

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

  8. 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
                ...
            }
        }
    }
})

  9. 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)
                ...
            }
        }
    }
})

  10. 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();
            ...
        }
    }
});

  11. 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();
            ...
        }
    }
});

  12. Join password-protected meetings

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

  13. Change the composite video layout during a call

    activeCall.setCompositedVideoLayout(layout: MediaOption.CompositedVideoLayout)

  14. 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
        }
    }
})

  15. Change the max sending fps for video

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

  16. Enable(disable) android.hardware.camera2

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

  17. Whether the app can continue video streaming when the app is in background

    webex.phone.enableBackgroundStream(enable: Boolean)

  18. 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
    }
})

  19. Check if the message mentioned everyone in space

    message.isAllMentioned()

  20. Get all people mentioned in the message

    message.getMentions()

  21. Change the max capture fps when screen sharing

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

  22. Switch the audio play output mode during a call

    activeCall.switchAudioOutput(mode: Call.AudioOutputMode);

  23. Enable/Disable Background Noise Removal(BNR)

    webex.phone.enableAudioBNR(enable: Boolean)

  24. Set Background Noise Removal(BNR) mode

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

  25. 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
    }
})

  26. Enable/Disable background connection

    webex.phone.enableBackgroundConnection(enable: Boolean)

  27. Enable/Disable console logging

    webex.enableConsoleLogger(enable: Boolean)

  28. Set log level of logging

    webex.setLogLevel(logLevel: LogLevel)

  29. 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()
Clone this wiki locally