CUCM Usage Guide

Using the Cisco Webex Android SDK 3.0+, you can make, receive, transfer and merge CUCM calls.

To get started developer need to first login to CUCM and then wait for Phone Services to get connected, once both steps are successful, you are good to start enjoying features of CUCM.

Usage

1. Start the UC Services

   webex.startUCServices()

2. Check if you're already logged into CUCM

   val isUCLoggedIn = webex.isUCLoggedIn()
   if(isUCLoggedIn) {
       // Already logged in to the CUCM service.
   } else {
       // You are not logged into CUCM service
   }

3. If you're not logged in, you can start the login process by providing the UC domain/server Url from the user and invoking the below method. Note: Provide only either a domain or a server, but not both.

   webex.setUCDomainServerUrl(ucDomain = "cucm.example.com", serverUrl = "cucmserver.example.com")

4. Webex SDK exposes an interface called WebexUCLoginDelegate. Developers should implement this interface to listen to async CUCM callbacks like login status change, server connection status change, etc. For example :

   class HomeActivity : WebexUCLoginDelegate {
       // Callbacks
       override fun onUCLoggedIn() {
           // CUCM login attempt was successful
       }
   
       override fun onUCLoginFailed() {
           // CUCM login attempt failed
       }
   
       override fun loadUCSSOViewInBackground(ssoUrl: String) {
           // If your CUCM server supports SSO based sign in, you'll need to open a webview using `UCSSOWebViewAuthenticator.launchWebView` helper like below
           UCSSOWebViewAuthenticator.launchWebView(webviewInstance, ssoUrl, CompletionHandler { result ->
               if (result.isSuccessful) {
                   // CUCM login attempt was successful
               } else {
                   // CUCM login attempt failed
               }
           })
       }
   
       override fun showUCNonSSOLoginView() {
               // This method will be invoked if your CUCM server requires a non-sso(username/password) flow
           // You should collect the username / password from user and call the below method 
           webex.setCUCMCredential(username = "user@example.com", password = "SuperSecret")
       }
   
       override fun onUCSSOLoginFailed(failureReason: UCSSOFailureReason) {
           // If the SSO login failed due to reason like session expiry, you'll need to re-login using `webex.retryUCSSOLogin` like below 
           webex.retryUCSSOLogin()
       }
   
       override fun showUCSSOBrowser() {
           // Show the webview
       }
   
       override fun hideUCSSOBrowser() {
           // Hide the webview
       }
   
       override fun onUCServerConnectionStateChanged(status: UCLoginServerConnectionStatus, failureReason: PhoneServiceRegistrationFailureReason) {
           if (status == UCLoginServerConnectionStatus.Connected) {
               // CUCM server connection success. Once connected you can start making/receiving calls
           }
       }
   }

5. (Optional) If onUCServerConnectionStateChanged callback is triggered with failureReason equal to PhoneServiceRegistrationFailureReason.RegisteredElsewhere then you can force register the cucm server on current device by calling the below api

   webex.forceRegisterPhoneServices()

6. Check if you're connected to CUCM server

   val status = webex.getUCServerConnectionStatus()
   if (status == UCLoginServerConnectionStatus.Connected) {
       // You're successfully connected to a CUCM server
   }

7. Once you're successfully connected, You can start making calls using either a PSTN number or a sip uri. 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. 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
       }
   })

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

8. Once you have an instance of a CUCM call object, you can perform actions like transfer or merge with another call. But before that, you need first hold the current ongoing call and then associate the call with a new call. The Call interface provides method holdCall and startAssociatedCall for holding the current call and for associating with a new call respectively.

   // Hold current ongoing call before associating to another call
   call?.holdCall(true)
   call?.startAssociatedCall("+1800123457", associationType = CallAssociationType.Transfer, audioCall = true, CompletionHandler { result ->
           if (result.isSuccessful) {
               // Call association is successful, result.data gives new Call object
               val newCall: Call? = result.data
               // Transfer call
               call?.transferCall(newCall?.getCallId())
           } else {
               // Call association failed
           }
       })

9. Merge current call with a new call

   // Hold current ongoing call before associating to another call
   call?.holdCall(true)
   // start a new call that can be merged later to the previous call
   call?.startAssociatedCall("+1800123457", associationType = CallAssociationType.Merge, audioCall = true, CompletionHandler { result ->
       if (result.isSuccessful) {
           // Call association is successful, result.data gives new Call object
           val newCall: Call? = result.data
           // Merge call
           call?.mergeCalls(newCall?.getCallId())
       } else {
           // Call association failed
       }
   })

10. To log out from CUCM services, you have to log out from Webex services itself. Call the deauthorize method of the Authenticator class and pass in a completion handler object.

    webex.authenticator?.deauthorize(CompletionHandler { result ->
        if (result.isSuccessful) {
            // You have been logged out of CUCM and webex services successfully
        } else {
            // Logout failed, result.error?.errorMessage gives you the error message.
        }
    })

NOTE : In case SSO login is in process and user cancels the login flow (For e.g. by clicking back button when SSO browser is displayed), then we should cancel the SSO flow by calling the below api: kotlin webex.ucCancelSSOLogin()

FLOW CHART FOR CUCM LOGIN :

CUCM CALL NOTIFICATIONS:

For CUCM incoming call notifications, please visit App Registration For Mobile SDK v3