Skip to main content
Version: 5.9.0

Troubleshooting

Guide to diagnosing and fixing problems when integrating and running the ChatCenterUI SDK.

Enable verbose logging

For every scenario below, enable ChatLoggerConfig(logLevel: .all) — without it the SDK does not output network requests or WebSocket events (logLevel: .off is the default). See Logger settings for details.

First, check the channel configuration in the admin workplace

Many issues observed in the SDK are caused not by app code but by channel configuration on the server. Before diving into the checklists below, verify the admin workplace settings:

Symptom in the SDKWhat to check in the admin workplace
Push notifications do not arrive / arrive only in some environmentsiOS channel setup → APNs, Push notification templates
Chat shows "out of business hours" / auto-replyChannel working hours
Personal data collection notification, consent, or survey does not arriveClient notifications, Personal data collection notifications, Client surveys
Thread is routed to the wrong agent or botThread segmentation, Routing
Notifications are not shown on all clientsNotifications in web chat and mobile apps

Full overview of the admin workplace — Admin workplace.

SDK does not initialize​

Symptoms​

  • App crashes when creating ChatCenterUISDK
  • SDK is created, but methods do not work

Checklist​

  1. Is the framework linked correctly?

    • The ChatCenterUI.xcframework is added in General → Frameworks and Libraries with Embed & Sign
    • When using CocoaPods, the project is opened via .xcworkspace, not .xcodeproj

  2. Is providerUid correct?

    • Value obtained from edna during integration
    • No extra whitespace or line breaks

  3. Does ChatTransportConfig contain valid URLs?

    // URLs must be full, including the protocol
    let transport = ChatTransportConfig(
        rest: "https://your-host.edna.io",
        webSocket: "wss://your-host.edna.io/socket",
        dataStore: "https://your-host.edna.io/files"
    )

    // Or for cloud clients (without https://):
    let transport = ChatTransportConfig(cloudHost: "your-host.edna.io")

  4. Is the SDK instance retained?

    • ChatCenterUISDK must be stored as a property — otherwise ARC will release it as soon as the method returns, and the delegate, UIApplication notification observers, and WebSocket will fall apart
    // Wrong — the SDK is released when the method returns
    func setup() {
        let sdk = ChatCenterUISDK(...)
    }

    // Correct — the SDK lives for the entire app lifetime
    var chatCenterSDK: ChatCenterUISDK?
    func setup() {
        chatCenterSDK = ChatCenterUISDK(...)
    }

Chat does not load​

Symptoms​

  • getChat() throws an error
  • The chat screen shows a loading indicator indefinitely
  • A connection error is displayed

Checklist​

  1. Is the user authorized?

    // getChat() throws ChatCenterUIError.userNotAuthorized if you forget:
    chatCenterSDK.authorize(user: ChatUser(identifier: "user_id"))

  2. Is the server reachable?

    • Open the REST URL in a browser — expected response is HTTP 200 or 401/403 (auth required); 5xx or a timeout means the server is unreachable
    • Verify that the device or simulator has network access
    • When using a VPN, make sure traffic is routed correctly

  3. Is the SSL certificate valid?

    • For test servers with a self-signed certificate: 
      var networkConfig = ChatNetworkConfig()
      networkConfig.sslPinning.allowUntrustedSSLCertificate = true // for testing only!
      let chatConfig = ChatConfig(transportConfig: transport, networkConfig: networkConfig)
    • For production, use sslPinning.trustedCertificates with backup certificates

  4. Does the API version match the server? The default .api17 works with ChatCenter 6.x and later. The exact value for your server is in the API versions table.

Messages are not sent​

Symptoms​

  • A message shows the Not delivered status
  • send(message:) throws an error
  • Messages disappear

Checklist​

  1. What error is thrown? Catch the specific ChatCenterUISendMessageError case and match it to the cause — the case table and a handling example are in the Error reference. The most common case when sending programmatically is .webSocketNotActive (chat is closed, WebSocket is disconnected).

  2. Is the WebSocket connection active?

    • When sending from the background: set chatConfig.keepSocketActive = true and chatConfig.shouldUseRemoteConfig = false (otherwise the server config will override the local value). See the warning in SDK settings.
    • Check that the device has network connectivity.

  3. Does the attachment size exceed the limit? For images, the SDK checks the size before sending and throws ChatCenterUISendMessageError.messageImageTooLarge if the limit is exceeded. The default limit is 30 MB; the server can override it. To get the exact value for your tenant, contact edna support.

  4. send(message:) does not throw, but the message was not delivered? The method only confirms delivery to the WebSocket, not to the server. REST failures (history and file uploads) are reported separately via the didReceiveNetwork(error:) delegate; WebSocket disconnects are not reported to the delegate (see SDK delegate).

Push notifications do not arrive​

Symptoms​

  • The device does not receive push notifications from ChatCenter
  • A push arrives, but the chat does not open

Checklist​

  1. Was the device token passed via ChatCenterUISDK.setDeviceToken(_:)? Full call example is in the Notifications section.

  2. Were notification permissions requested via UNUserNotificationCenter.requestAuthorization? Without this, APNs will not issue a token.

  3. Are push notifications configured on the edna server? The APNs key (.p8) or certificate (.p12), Bundle ID, and environment type (sandbox/production) are set in the admin workplace — see iOS mobile chat setup → Push notification configuration. The APNs payload template (the aps fields and placeholders) is in Push notification templates. If you do not have access to the admin workplace, contact support@edna.io.

  4. Is the notification from ChatCenter and not from your app?

    if let userInfo = userInfo as? [String: Any],
       ChatCenterUISDK.isChatCenterNotification(userInfo) {
        // This is a notification from the ChatCenterUI SDK
    }

  5. Is notification handling implemented? Both methods are declared as throws(ChatCenterUIError) — make sure to use try:

    • Chat is open → try chatCenterSDK.handleNotification(userInfo: userInfo) (the context is not injected into an already-open chat — see Notifications)
    • Chat is closed → try chatCenterSDK.getChat(userInfo: userInfo) + present the view controller

See the Notifications section for details.

Theme / customization issues​

Symptoms​

  • Styles are applied with a delay (the default theme is visible on the first frame)
  • The light theme works, but the dark one does not
  • The font in message bubbles does not change

Checklist​

  1. Is the theme set before getChat()? The theme is read when the chat is opened.
  2. Is the assignment order of theme and darkTheme correct? Assign chatCenterSDK.darkTheme after chatCenterSDK.theme. Assigning theme resets darkTheme — if you set the dark theme first, the light theme will overwrite it.
  3. The font in bubbles is typography.message, not typography.body (see the token map in Typography).

A detailed design-system FAQ is in Design system troubleshooting.

Slow chat loading​

Symptoms​

  • In the SDK logs (logLevel: .all), the REST history request (api/client/history, or history for servers with newRoutesEnabled: false) takes more than 1–2 seconds
  • The delay is reproducible in the demo app on the same server data

Checklist​

  1. Check the network latency to the server. Enable ChatLoggerConfig(logLevel: .all) and compare the time of the REST history request (api/client/history or history) against the typical latency to the server.
  2. History page size on scroll-up. With shouldUseRemoteConfig = false, reduce chatConfig.historyLoadingCount (default — 30). With shouldUseRemoteConfig = true the value is set by the server — configure it via edna support.
  3. Do not recreate ChatTheme before every chat opening — store it as a property and reuse it.

Diagnosing with the demo app​

  1. Reproduce the problem in the demo app using your server data.
  2. If it reproduces, the cause is in the SDK or on the server; send an isolated project to support@edna.io. Before sending, replace the real providerUid and server URLs with placeholders (see Reporting an issue).
  3. If the demo app does not reproduce the problem, the cause is in your project settings or the way the SDK is integrated.
Last updated on