Add chat capability to the Contact Center SDK for iOS

Add the chat service one of two ways: the standard chat service, or Zoom Virtual Agent chat.

Add standard chat service

Follow these steps to add standard chat functionality.

Initialize the standard chat service

Create an instance of class ZoomCCItem to set the channel to use, chat or video. For chat, set the sdkType property to ZoomCCIInterfaceType_Chat.

Include the entryId from your Zoom Contact Center flow.

Objective-C
Swift
ZoomCCItem *item = [ZoomCCItem new];
item.sdkType = ZoomCCIInterfaceType_Chat;
item.entryId = APP_CHAT_ENTRY_ID;
let item = ZoomCCItem.init()
item.sdkType = .chat
item.entryId = APP_CHAT_ENTRY_ID

Pass engagement variables (optional)

To pass custom application context variables to a chat engagement, configure custom variables in Contact Center Management and set its value source to Application. Before calling initializeWithItem, use the variable name as the key and the application-provided value as the dictionary value in ZoomCCItem.engagementVariables.

Objective-C
Swift
ZoomCCItem *item = [ZoomCCItem new];
item.sdkType = ZoomCCIInterfaceType_Chat;
item.entryId = APP_CHAT_ENTRY_ID;
item.engagementVariables = @{@"test_key":@"test_value"};
let item = ZoomCCItem.init()
item.sdkType = .chat
item.entryId = APP_CHAT_ENTRY_ID
item.engagementVariables = ["test_key": "test_value"]

Fetch the standard chat service instance

Fetch the chat service instance and set its delegate to receive callbacks from ZoomCCSDK. When the status of the service is ZoomCCSDKStatus_Initial, initialize the chat service by calling initializeWithItem: and login. The service then connects to the Contact Center server to fetch information, and you can send and receive messages to and from the server.

Objective-C
Swift
id<ZoomCCChatService> chatService = [[ZoomCCInterface sharedInstance] chatService];
chatService.chatDelegate = self;
if (chatService.status == ZoomCCSDKStatus_Initial) {
    [chatService initializeWithItem:item];
    [chatService login];
}
let chatService = ZoomCCInterface.sharedInstance().chatService()
chatService.chatDelegate = self
if (chatService.status == .initial) {
    chatService.initialize(with: item)
    chatService.login()
}

Show the standard chat view

To show the chat view, call the function below. The call back gets the view's instance and displays it.

Objective-C
Swift
__weak typeof(self) wself = self;
[chatService fetchUI:^(UIViewController * _Nonnull viewController) {
    [wself directShow:viewController];
}];
chatService .fetchUI { vc in
    self.navigationController?.pushViewController(vc, animated: true)
}

Forcibly end an active chat engagement

To forcibly end a chat engagement, call the endChat method. This closes the chat view presented by the SDK and returns control to your application. Any service instances created by the Contact Center SDK for this chat are released.

Objective-C
Swift
id<ZooomCCChatService> chatService = [[ZoomCCInterface sharedInstance] chatService];
[chatService endChat];
let chatService = ZoomCCInterface.sharedInstance().chatService()
chatService.endChat()

Add Virtual Agent chat service

Follow these steps to add Virtual Agent chat functionality.

Initialize the Virtual Agent chat service

Create an instance of the ZoomCCItem class to set the Virtual Agent channel to use, chat or video. For Virtual Agent chat, set the sdkType`` property to ZoomCCIInterfaceType_ZVA`.

Include the entryId from your Virtual Agents flow.

Objective-C
Swift
ZoomCCItem *item = [ZoomCCItem new];
item.sdkType = ZoomCCIInterfaceType_ZVA;
item.entryId = APP_ZVA_ENTRY_ID;
let item = ZoomCCItem.init()
item.sdkType = .ZVA
item.entryId = APP_ZVA_ENTRY_ID

Pass engagement variables (optional)

To pass custom application context variables to a Virtual Agent engagement, configure custom variables in Contact Center Management and set its value source to Application. Before calling initializeWithItem, use the variable name as the key and the application-provided value as the dictionary value in ZoomCCItem.engagementVariables.

Objective-C
Swift
ZoomCCItem *item = [ZoomCCItem new];
item.sdkType = ZoomCCIInterfaceType_ZVA;
item.entryId = APP_ZVA_ENTRY_ID;
item.engagementVariables = @{@"test_key":@"test_value"};
let item = ZoomCCItem.init()
item.sdkType = .ZVA
item.entryId = APP_ZVA_ENTRY_ID
item.engagementVariables = ["test_key": "test_value"]

Fetch the Virtual Agent chat service instance

Fetch the Virtual Agent chat service instance and set its delegate to receive callbacks from ZoomCCSDK. When the service's status is ZoomCCSDKStatus_Initial, initialize the chat service by calling initializeWithItem: and login. The service then connects to the Contact Center server to fetch information.

Objective-C
Swift
id<ZoomCCChatService> zvaService = [[ZoomCCInterface sharedInstance] zvaService];
zvaService.chatDelegate = self;
if (zvaService.status == ZoomCCSDKStatus_Initial) {
  [zvaService initializeWithItem:item];
  [zvaService login];
}
let zvaService = ZoomCCInterface.sharedInstance().zvaService()
zvaService.chatDelegate = self
if (zvaService.status == .initial) {
  zvaService.initialize(with: item)
  zvaService.login()
}

Show the Virtual Agent chat view

To show the Virtual Agent chat view, call this function. The callback gets and displays the view's instance.

Objective-C
Swift
__weak typeof(self) wself = self;
[zvaService fetchUI:^(UIViewController * _Nonnull viewController) {
    [wself directShow:viewController];
}];
zvaService.fetchUI { vc in
    if (vc != nil) {
        self.navigationController?.pushViewController(vc!, animated: true)
    }
}

Forcibly end an active Virtual Agent engagement

To forcibly end a Virtual Agent engagement, call the endChat method. This closes the chat view presented by the SDK and returns control to your application. Any service instances created by the Contact Center SDK for this chat are released.

Objective-C
Swift
id<ZooomCCChatService> zvaService = [[ZoomCCInterface sharedInstance] zvaService];
[zvaService endChat];
let zvaService = ZoomCCInterface.sharedInstance().zvaService()
zvaService.endChat()

Embed chat in iOS apps

To use the Contact Center for web in iOS apps, create a WKUserScript to pass the current environment data. Then transmit a callback. Finally, create a WKWebView and load the WebSDK URL generated in the campaign management page.

Transmit the current environment data

Create a WKUserScript to transmit the current environment data.

Objective-C
Swift

WKUserContentController *userContentController = [[WKUserContentController alloc] init];
NSString * injectScriptStr = @"window.zoomCampaignSdkConfig = window.zoomCampaignSdkConfig || { "
"language : 'user language',"
"firstName: 'user first name',"
"lastName: 'user first name',"
"nickName: 'user nickname',"
"address: 'user address',"
"company: 'user company',"
"email : 'user email',"
"phoneNumber : 'user phone number'};";

WKUserScript *injectScript = [[WKUserScript alloc] initWithSource:injectScriptStr injectionTime:WKUserScriptInjectionTimeAtDocumentStart forMainFrameOnly:true];
[userContentController addUserScript:injectScript];

let userContentController = WKUserContentController()
let webviewcConfig = WKWebViewConfiguration()
webviewcConfig.userContentController = userContentController

//pass the parameters to webview
let injectScriptStr =
"""
    window.zoomCampaignSdkConfig = window.zoomCampaignSdkConfig || {
        language: 'user language',
        firstName: 'user first name',
        lastName: 'user last name',
        nickName: 'user nick name',
        address: 'user address',
        company: 'user company',
        email: 'user email',
        phoneNumber: 'user phonenumber'
    };
"""

let injectScript = WKUserScript(source: injectScriptStr, injectionTime: .atDocumentStart, forMainFrameOnly: true)
userContentController.addUserScript(injectScript)

For the key language in the transmit data, use one of these supported languages:

"en-US"
"da-DK"
"de-DE"
"en-AU"
"en-GB"
"en-NZ"
"es-ES"
"es-MX"
"es-US"
"fr-CA"
"fr-FR"
"id-ID"
"it-IT"
"ja-JP"
"ko-KR"
"nl-NL"
"pl-PL"
"pt-BR"
"pt-PT"
"ro-RO"
"ru-RU"
"sv-SE"
"tr-TR"
"vi-VN"
"zh-CN"
"zh-TW"
"ar-AE"
"ar-SA"
"ca-ES"
"cs-CZ"
"fi-FI"
"he-IL"
"hi-IN"
"ka-GE"
"ms-MY"
"nb-NO"
"th-TH"

Transmit a callback

Create a WKUserScript to transmit a callback function into the Javascript context. Use this callback function when the WebSDK needs to terminate the current session and return to the previous viewController.

Objective-C
Swift
NSString *exitHandlerScriptStr =
    @"window.addEventListener('zoomCampaignSdk:ready', () => {"
      "if (window.zoomCampaignSdk) { "
        "window.zoomCampaignSdk.native = {"
          "exitHandler: {"
            "handle: function() {"
              "window.webkit.messageHandlers.zoomLiveSDKMessageHandler.postMessage('close_web_vc');"
            "}"
          "}"
        "};"
      "}"
    "});";

    WKUserScript *exitScript = [[WKUserScript alloc] initWithSource:exitHandlerScriptStr injectionTime:WKUserScriptInjectionTimeAtDocumentStart forMainFrameOnly:true];
    [userContentController addUserScript:exitScript];
    [userContentController addScriptMessageHandler:self name:@"zoomLiveSDKMessageHandler"];
//pass the exit webview handler callback to webview
let exitHandlerScriptStr =
"""
    window.addEventListener('zoomCampaignSdk:ready', () => {
          if (window.zoomCampaignSdk) {
              window.zoomCampaignSdk.native = {
                  exitHandler: {
                      handle: function() {
                          window.webkit.messageHandlers.zoomLiveSDKMessageHandler.postMessage('close_web_vc');
                    }
                  }
              };
          }
    });
"""

let exitScript = WKUserScript(source: exitHandlerScriptStr, injectionTime: .atDocumentStart, forMainFrameOnly: true)
userContentController.addUserScript(exitScript)

//register self as the javascript message handler named "zoomLiveSDKMessageHandler"
userContentController.add(self, name: "zoomLiveSDKMessageHandler")

In the previous code sample, the instance self is UIViewController or another kind of instance. It should conform to the protocol WKScriptMessageHandler and have the method shown in this next code sample.

Objective-C
Swift
- (void)userContentController:(WKUserContentController *)userContentController didReceiveScriptMessage:(WKScriptMessage *)message
{
    if ([message.name isEqualToString:@"zoomLiveSDKMessageHandler"]) {
        if ([message.body isEqualToString:@"close_web_vc"]) {
            //todo handle current webview controller's pop action, like
            [self.navigationController popViewControllerAnimated:YES];
        }
    }
}
func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
    if message.name == "zoomLiveSDKMessageHandler", let bodyString = message.body as? String {
        if bodyString == "close_web_vc" {
          // Handle current webview controller's pop action, like
          navigationController?.popViewController(animated: true)
        }
    }
}

When the WebSDK needs to close the current viewcontroller, call this Javascript method.

window.zoomCampaignSdk.native.exitHandler.handle();

Since we had a message handler registered named zoomLiveSDKMessageHandler, then this next method would be called within a message. In the callback, add logic to leave the current webview.

Objective-C
Swift
- (void)userContentController:(WKUserContentController *)userContentController didReceiveScriptMessage:(WKScriptMessage *)message
func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage)

Create a `WKWebView` and load the WebSDK URL

Objective-C
Swift
//the instance webviewcConfig is created by step 1.
webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:webviewcConfig];
webView.UIDelegate = self;
webView.navigationDelegate = self;
[self.view addSubview:webView];

NSURL *url = [NSURL URLWithString:@"Zoom contact center target url"];
if (url) {
    [webView loadRequest:[NSURLRequest requestWithURL:url]];
}
//the instance webviewcConfig is created by step 1.
webView = WKWebView(frame: view.bounds, configuration: webviewcConfig)
webView.uiDelegate = self
webView.navigationDelegate = self
view.addSubview(webView)
if let url = URL(string: "Zoom contact center target url")
{
      webView.load(URLRequest(url: url))
}

For native mobile applications using Swift or Objective-C, adapt to the user's language preferences in two ways.

For iOS 16 and above, use the device's regional language setting.

Objective-C
Swift
NSString *currentLanguage = [[NSLocale currentLocale] languageCode];
let currentLanguage = Locale.current.language.languageCode?.identifier ?? "en"

Respect the user's preferred languages set on their device.

Objective-C
Swift
NSArray *preferredLanguages = [[NSUserDefaults standardUserDefaults] objectForKey:@"AppleLanguages"];
let preferredLanguages = UserDefaults.standard.object(forKey: "AppleLanguages") as? [String]

Callbacks

These callbacks are available for both chat and video.

onEngagementVariablesRequired
error
engagementStart
engagementEnd
eventChange
loginStatusChanged
unreadMsgCountChanged (chat only)

`onEngagementVariablesRequired`

Called after login when the engagement application variables are known. Each dictionary can contain variableGroupName, variableName, and attributeName. Use attributeName as the key in ZoomCCItem.engagementVariables.

This callback only reports the variable definitions; the SDK sends matching values when the engagement is created.

service: the current service.
variables: an array of dictionaries describing variables that the current engagement may require. Each dictionary can contain variableGroupName, variableName, or attributeName.

Objective-C
Swift
- (void)onService:(id<ZoomCCService>)service
engagementVariablesRequired:(NSArray<NSDictionary<NSString *, NSString *> *> *)variables;
func onService(_ service: ZoomCCService, engagementVariablesRequired variables: [[String: String]]) {
}

`error`

Sent after a service error.

service — the current service.
error — the service error code. See errors for details.
detail — the error details.

Objective-C
Swift
- (void)onService:(id<ZoomCCService>)service error:(NSUInteger)error  detail:(NSInteger)detail;
func onService(_ service: ZoomCCService, error: UInt, detail: Int) {
}

`engagementStart`

Sent after the service creates an engagement.

service — the current service.
engagementId — the engagement identifier.

Objective-C
Swift
- (void)onService:(id<ZoomCCService>)service engagementStart:(NSString*)engagementId;
func onService(_ service: ZoomCCService, engagementStart engagementId: String) {
}

`engagementEnd`

Sent after the engagement ends.

service — the current service.
engagementId — the engagement identifier.

Objective-C
Swift
- (void)onService:(id<ZoomCCService>)service engagementEnd:(NSString*)engagementId;
func onService(_ service: ZoomCCService, engagementEnd engagementId: String) {
}

`eventChange`

Sent when a change has occurred, for example, due to a user action.

service — the current service.
event — the event that occurred.

Objective-C
Swift
- (void)onService:(id<ZoomCCService>)service eventChange:(ZoomCCSDKEvent)event;
func onService(_ service: ZoomCCService, eventChange event: ZoomCCSDKEvent) {
}

`loginStatusChanged`

Sent when the login status has changed.

service — the current service.
status — the service status. ZoomCCSDKStatus_Login means the logging succeeded.

Objective-C
Swift
- (void)onService:(id<ZoomCCService>)service loginStatusChanged:(ZoomCCSDKStatus)status;
func onService(_ service: ZoomCCService, loginStatusChanged status: ZoomCCSDKStatus) {
}

`unreadMsgCountChanged` (chat only)

Sent when the number of unread messages has changed. Only sent for chat.

service — the current service.
status — the service status. ZoomCCSDKStatus_Login means the logging succeeded.

Objective-C
Swift
- (void)onChatService:(id<ZoomCCChatService>)service unreadMsgCountChanged:(NSUInteger)count;
func onChatService(_ service: ZoomCCChatService, unreadMsgCountChanged count: UInt) {
}

Add standard chat service#

Initialize the standard chat service#

Pass engagement variables (optional)#

Fetch the standard chat service instance#

Show the standard chat view#

Forcibly end an active chat engagement#

Add Virtual Agent chat service#

Initialize the Virtual Agent chat service#

Pass engagement variables (optional)#

Fetch the Virtual Agent chat service instance#

Show the Virtual Agent chat view#

Forcibly end an active Virtual Agent engagement#

Embed chat in iOS apps#

Transmit the current environment data#

Transmit a callback#

Create a WKWebView and load the WebSDK URL#

Callbacks#

onEngagementVariablesRequired#

error#

engagementStart#

engagementEnd#

eventChange#

loginStatusChanged#

unreadMsgCountChanged (chat only)#

Add standard chat service

Initialize the standard chat service

Pass engagement variables (optional)

Fetch the standard chat service instance

Show the standard chat view

Forcibly end an active chat engagement

Add Virtual Agent chat service

Initialize the Virtual Agent chat service

Pass engagement variables (optional)

Fetch the Virtual Agent chat service instance

Show the Virtual Agent chat view

Forcibly end an active Virtual Agent engagement

Embed chat in iOS apps

Transmit the current environment data

Transmit a callback

Create a `WKWebView` and load the WebSDK URL

Callbacks

`onEngagementVariablesRequired`

`error`

`engagementStart`

`engagementEnd`

`eventChange`

`loginStatusChanged`

`unreadMsgCountChanged` (chat only)