NowChatService class - iOS

  • Release version: Yokohama
  • Updated January 30, 2025
  • 6 minutes to read

    • The NowChatService class provides Virtual and Live Agent chat capabilities.

    Using this class you can start and stop chat services, start chat sessions, create a chat user interface, and subscribe/unsubscribe to unread messages.

    Table 1. Properties
    Name Description
    configuration Configuration settings provided when the service was initialized.

    Data type: NowServiceConfiguration
    instanceVersion Version of the associated ServiceNow instance, such as vancouver or xanadu.

    Data type: String
    networkService Network service associated with this chat service.

    Data type: NetworkService
    sessionType Type of session.
    Possible values:
    • authenticated
    • guest
    • impersonated
    • unknown

    Data type: SessionType

    NowChatService - init(configuration: NowServiceConfiguration, delegate: NowChatServiceDelegate?, coreServiceProvider: NowCoreServiceProviding? = nil)

    Initializes a new NowChatService instance.

    Table 2. Parameters
    Name Type Description
    configuration NowServiceConfiguration Configuration information needed to properly initialize the service.
    delegate Now​Chat​Service​Delegate Optional. NowChat callback delegate object implementing the NowChatServiceDelegate protocol.

    Default: nil
    coreServiceProvider NowCoreServiceProviding Optional. Object implementing the NowCoreServiceProviding protocol. Provides access to NowChat services.

    Default: nil

    The following code example shows how to call this function.

    guard let coreService = NowSDK.core() else {
  // Error with NowServiceError.sdkNotConfigured
  return
}

guard 
  let instanceUrl = URL(string: "http://sample.service-now.com"), 
  let serviceConfig = NowSDK.makeServiceConfiguration(for: instanceUrl) else {
    // Could not create service – 
    // NowServiceError.serviceConfigurationInvalid
    return
  }
    
let chatService = NowChatService(configuration: serviceConfig, delegate: delegate, coreServiceProvider: coreService)

    NowChatService - makeChatUI(theme: NowChatThemeable, chatConfiguration: NowChatConfiguration? = nil) -> Result<UIViewController, NowChatServiceError>)

    Creates a UIViewController that hosts the chat user interface.

    Although this function creates the chat UI, you must still initiate the chat session by calling the startChat() function. You should make this call as the chat UI becomes visible. For more details, see the associated sample application and the Mobile SDK Developer Guide - iOS.

    Table 3. Parameters
    Name Type Description
    theme NowChatThemeable protocol - iOS Theme information for the chat UI to create.
    chatConfiguration NowChatConfiguration? Optional. Options to apply to the chat session.
    Table 4. Returns
    Type Description
    Object Success: UIViewController object that contains the UI view controller configuration information.

    Failure: NowChatServiceError object.

    Possible errors:
    • chatServiceInvalid
    • coreServiceInvalid
    • guestUserNotAllowed
    • invalidCredentials
    • noSession
    • unknown
    • unsupportedServer

    The following code example shows how to call this function to create the chat UI.

    func makeChatScreen() -> UIViewController? {
  guard let chatService = chatService else { return nil } 

  let closePrompt = NowChatConfiguration.ClosePrompt(header: "Close Window",
    message: "Are you sure you want to close the chat window?",
    acceptButtonTitle: "Yes",
    declineButtonTitle: "No") 

  let attachmentUploadButton = NowChatConfiguration.AttachmentUploadButton(isVisible: false) // default isVisible = true

  let chatConfiguration = NowChatConfiguration(closePrompt: closePrompt,
    disabledFeatures: [.startNewConversation],
    conversationOptions: [.forceNewConversation, .endConversationOnExit],
    uiConfiguration: NowChatConfiguration.UIConfiguration(closeButton: closeButtonImage(name: "arrow.left"), attachmentUploadButton: attachmentUploadButton))

  let result = chatService.makeChatUI(theme: CarrascoChatTheme(chatColors: ChatColors()), chatConfiguration: chatConfiguration)    

  switch result {
    case .success(let chatViewController):
      return chatViewController
    case .failure(let error):
      debugPrint("Chat screen creation failed with error: \(error)") 
      return nil
  }
}

    NowChatService - shutdown()

    Shuts down the chat service, including any active chat sessions.

    After calling this function, the associated NowChatService is inactive and cannot be reused. To establish another chat session, create a new NowChatService instance by calling the NowChat.makeChatService() function.

    Table 5. Parameters
    Name Type Description
    None
    Table 6. Returns
    Type Description
    None

    The following code example shows how to call this function.

    private func resetChat() {
  chatService?.shutdown()
  chatService = nil
  initializeChatService()
  viewState = makeViewState()
}

func initializeChatService() {
  NowChat.makeChatService(instanceUrl: instanceUrl, delegate: self) { [weak self] result in
    guard let self = self else { return }
            
    switch result {
    case .success(let service):
      self.chatService = service
    case .failure(let error):
      debugPrint("Creating the chat service failed with error: \(error)")
    }
    self.viewState = self.makeViewState()
}

func makeViewState() -> ViewState {
  ViewState(chatEnabled: chatService != nil,
    menuItems: menuItems)
}

    NowChatService - startChat(contextData: [String: Any]? = nil, _ completion: @escaping (Result<Void, NowChatServiceError>) -> Void)

    Starts a chat session and executes a completion block after chat session has started.

    Table 7. Parameters
    Name Type Description
    contextData [String: Any]? Optional. Dictionary containing chat context variables that are passed into the chat session.

    For additional information on chat context variables, see Live agent chat context variables.
    completion Object Completion block to execute after the chat session has started.
    Table 8. Returns
    Type Description
    void or String
    Return values for the completion block:
    • Success: void
    • Error: NowChatServiceError
    Possible errors:
    • chatServiceInvalid
    • coreServiceInvalid
    • guestUserNotAllowed
    • invalidCredentials
    • noSession
    • unknown
    • unsupportedServer

    The following code example shows how to call this function without context data.

    func startChat() {
  guard let chatService = chatService else {
    debugPrint("Chat service is invalid")
    viewState = makeViewState()
    return
  }
  chatService.startChat { [weak self] result in
    if case .failure(let error) = result {
      debugPrint("Chat session initialization failed with error: \(error)")
      self?.resetChat()
    }
  }
}

func makeViewState() -> ViewState {
  ViewState(chatEnabled: chatService != nil,
    menuItems: menuItems)
}

    The following code example shows how to call this function with context data.

    func startChat() {
  guard let chatService = chatService else {
    debugPrint("Chat service is invalid")
    viewState = makeViewState()
    return
  }

  let contextData = ["sys_id": "123456789", "table_name": "wm_task", "active": true] as [String: Any]
  chatService.startChat(contextData: contextData) { [weak self] result in
    if case .failure(let error) = result {
      debugPrint("Chat session initialization failed with error: \(error)")
      self?.resetChat()
    }
  }
}

func makeViewState() -> ViewState {
  ViewState(chatEnabled: chatService != nil,
    menuItems: menuItems)
}

    NowChatService - subscribeToUnreadMessageCount(pollingInterval: TimeInterval, completion: @escaping (Int) -> Void)

    Subscribes to the unread message count listener.

    Table 9. Parameters
    Name Type Description
    pollingInterval TimeInterval Frequency at which to poll the web service for the unread chat message count.

    Unit: Seconds
    completion @escaping (Int) -> Void) Completion handler to call to report the unread chat message count.

    Int: Number of unread chat messages.
    Table 10. Returns
    Type Description
    None

    The following code example shows how to call this function.

    …
if viewModel.isPolling {
  viewModel.unsubscribeFromUnreadMessageCount()
  viewState.pollingInterval = ""
} else {
  viewModel.subscribeToUnreadMessageCount(pollingInterval: timeInterval)
}
…

func subscribeToUnreadMessageCount(pollingInterval: TimeInterval) {
  chatService.subscribeToUnreadMessageCount(pollingInterval: pollingInterval) { [weak self] count in
    self?.unreadMessageCount = count
  }
  isPolling = true
}

    NowChatService - unsubscribeFromUnreadMessageCount()

    Unsubscribes from receiving the unread message count listener.

    Table 11. Parameters
    Name Type Description
    None
    Table 12. Returns
    Type Description
    None

    The following code example shows how to call this function.

    …
if viewModel.isPolling {
  viewModel.unsubscribeFromUnreadMessageCount()
  viewState.pollingInterval = ""
} else {
  viewModel.subscribeToUnreadMessageCount(pollingInterval: timeInterval)
}
…
func unsubscribeFromUnreadMessageCount() {
  chatService.unsubscribeFromUnreadMessageCount()
  isPolling = false
  unreadMessageCount = 0
}

    NowChatService - updateTheme(theme: NowChatThemeable)

    Updates the NowChat UI theme with the specified UI theme. Use this function to update the chat UI theme after it has been initially set using the makeChatUI() function such as when changing the theme from light to dark.

    Table 13. Parameters
    Name Type Description
    theme NowChatThemeable Theme to update the chat UI with.
    Table 14. Returns
    Type Description
    None

    The following code example shows how to update a light UI theme to the dark UI theme using the updateTheme() function.

    struct LightNowChatColoring: NowChatColoring {
  let nowUIColor: NowUIColoring = LightNowUIColor()
  let brand = UIColor.now_color(withHexString: "#032D42")
  let primary = UIColor.now_color(withHexString: "#00566E")
  let secondary = UIColor.now_color(withHexString: "#002832")
  let destructive = UIColor.now_color(withHexString: "#E52239")
  let textPrimary = UIColor.now_color(withHexString: "#10171A")
  let textSecondary = UIColor.now_color(withHexString: "#232E33")
  let textTertiary = UIColor.now_color(withHexString: "#37444A")
  let textActionable = UIColor.now_color(withHexString: "#ffffff")
  let screenHeaderText = UIColor.now_color(withHexString: "#ffffff")
  let backgroundPrimary = UIColor.now_color(withHexString: "#ffffff")
  let backgroundSecondary = UIColor.now_color(withHexString: "#F5F6F7")
  let backgroundTertiary = UIColor.now_color(withHexString: "#E2E5E7")
  let backgroundPrimaryActionable = UIColor.now_color(withHexString: "#10171A")
  let backgroundSecondaryActionable = UIColor.now_color(withHexString: "#232E33")
  let brandBackground = UIColor.now_color(withHexString: "#BDDEE7")
  let borderTertiary = UIColor.now_color(withHexString: "#d3d6dc")
  let separatorPrimary = UIColor.now_color(withHexString: "#859095")
  let separatorTertiary = UIColor.now_color(withHexString: "#CFD5D7")
  let alertCritical0 = UIColor.now_color(withHexString: "#F9C8CE")
  let alertCritical3 = UIColor.now_color(withHexString: "#E52239")
  let shadow = UIColor.now_color(withHexString: "#10171A")
  let linkPrimary = UIColor.now_color(withHexString: "#1955BE")
  let linkSecondary = UIColor.now_color(withHexString: "#113A82")
  let notification = UIColor.now_color(withHexString: "#E52239")
  let highlightBlue = UIColor.now_color(withHexString: "#C4DBFE")
  let highlightGray = UIColor.now_color(withHexString: "#DCDDDE")
}

struct DarkNowChatColoring: NowChatColoring {
  let nowUIColor: NowUIColoring = DarkNowUIColor()
  let brand = UIColor.now_color(withHexString: "#032D42")
  let primary = UIColor.now_color(withHexString: "#6CBBD0")
  let secondary = UIColor.now_color(withHexString: "#99C6D2")
  let destructive = UIColor.now_color(withHexString: "#E46775")
  let textPrimary = UIColor.now_color(withHexString: "#FFFFFF")
  let textSecondary = UIColor.now_color(withHexString: "#E2E5E7")
  let textTertiary = UIColor.now_color(withHexString: "#BCC3C7")
  let textActionable = UIColor.now_color(withHexString: "#050809")
  let backgroundPrimary = UIColor.now_color(withHexString: "#050809")
  let backgroundSecondary = UIColor.now_color(withHexString: "#161F23")
  let backgroundTertiary = UIColor.now_color(withHexString: "#1D272B")
  let backgroundPrimaryActionable = UIColor.now_color(withHexString: "#FFFFFF")
  let backgroundSecondaryActionable = UIColor.now_color(withHexString: "#BCC3C7")
  let brandBackground = UIColor.now_color(withHexString: "#002934")
  let separatorPrimary = UIColor.now_color(withHexString: "#97A2A6")
  let separatorTertiary = UIColor.now_color(withHexString: "#4F5C62")
  let borderTertiary = UIColor.now_color(withHexString: "#454d5b")
  let screenHeaderText = UIColor.now_color(withHexString: "#FFFFFF")
  let alertCritical0 = UIColor.now_color(withHexString: "#7B1D28")
  let alertCritical3 = UIColor.now_color(withHexString: "#E46775")
  let shadow = UIColor.now_color(withHexString: "#10171A")
  let notification = UIColor.now_color(withHexString: "#E46775")
  let linkPrimary = UIColor.now_color(withHexString: "#339EFC")
  let linkSecondary = UIColor.now_color(withHexString: "#70BBFD")
  let highlightBlue = UIColor.now_color(withHexString: "#004652")
  let highlightGray = UIColor.now_color(withHexString: "#363D3D")
}

struct LightNowChatTheme: NowChatThemeable {
  let color: NowChatColoring = LightNowChatColoring()
}

struct DarkNowChatTheme: NowChatThemeable {
  let color: NowChatColoring = DarkNowChatColoring()
}

func chatService(_ chatService: NowChat.NowChatService, systemThemeDidChange traitCollection: UITraitCollection) {
  // The systemThemeDidChange delegate method can be used to call updateTheme() to apply theme changes when the system theme changes.
  debugPrint("System Theme did change")
  chatService.updateTheme(theme: traitCollection.userInterfaceStyle == .dark ? DarkNowChatTheme() : LightNowChatTheme())
}