Documentation navigation
Documentation

Troubleshooting Chatlio for Slack

Start with /chatlio status in your Chatlio channel. It shows whether the widget is on, whether manual mode and operating hours are on, and how many chats are open. If you are still stuck, contact us with your widget name and what you tried.

This page uses two names for Slack channels:

  • Your Chatlio channel is the main channel you chose during setup. Chatlio announces new chats there.
  • A visitor channel is the channel Chatlio creates for each visitor’s conversation.

Chats don’t arrive in Slack

  1. Open the widget in the dashboard. If it shows Connect your Slack workspace or Setup incomplete, Chatlio lost its connection to Slack. See Chatlio stopped working after a Slack change.
  2. Send a test message. On the widget’s Widget Install page, select Open test page.
  3. Check your Chatlio channel and the new visitor channel for the message.

If the test message does not arrive, check these:

  • The Chatlio app is not in your Chatlio channel. Chatlio can’t announce new chats in a channel it is not a member of, and Slack does not let Chatlio rejoin a private channel by itself. Invite the Chatlio app back to the channel.
  • The Chatlio channel was archived or deleted. Chatlio can’t post to it. Unarchive the channel in Slack, or click Change channel on the widget’s Channel page and pick another channel.
  • Chatlio can’t create visitor channels. Chatlio posts “Chatlio had a problem creating the dedicated channel for this visitor” in your Chatlio channel. The Slack user who installed Chatlio is not allowed to create channels. Ask your Slack admin to let that user create, archive and remove members from channels, or make that user a Slack admin.
  • Slack refused to create a channel. Chatlio posts “Unexpected Slack error creating new channel” in your Chatlio channel and shows that visitor the contact form, so they can leave a message. If it happens again, contact us.
  • The widget was offline. An offline visitor fills in the contact form instead of chatting. The form goes to the email address on the widget’s Behavior page. To see these messages in Slack as well, select Post offline messages to Slack under When Chatlio is off.
  • Only one visitor is missing. Run /chatlio ban list. Chatlio drops messages from a banned IP address without telling the visitor, and a ban covers everyone who shares that address, such as an office network. Remove a ban with /chatlio unban <IP address>.

Visitors don’t get my replies

Chatlio sends a visitor only the messages it can tell are for them:

  • Reply in the visitor channel, not in a thread. Chatlio does not send thread replies to the visitor.
  • Start with the visitor’s handle in your Chatlio channel. For example, @visitor-12 Hello. Other messages in your Chatlio channel stay with your team.
  • Don’t mention a teammate. A message that mentions a Slack user, such as @amy can you take this?, is a note to your team. The visitor does not get it.
  • Send files from the visitor channel. Chatlio does not send files posted in your Chatlio channel. If Chatlio answers a file with “Chatlio needs additional Slack permissions”, approve them on the Permissions page and upload the file again.

If your reply arrives late instead of never, see Replies reach the visitor late.

Replies reach the visitor late

Your website’s Content Security Policy probably blocks the widget’s live connection. That policy is a header that limits what your pages may load. The widget receives replies over a live connection to wss://api.chatlio.com. When the browser blocks it, the widget checks for replies every few seconds instead, so your replies arrive a few seconds late.

To check, open your site in a browser, open the developer console, and look for a Content Security Policy error that names wss://api.chatlio.com.

To fix it, add wss://api.chatlio.com to your policy’s connect-src line, or to default-src if your policy has no connect-src line. A host listed without wss://, such as api.chatlio.com or *.chatlio.com, doesn’t cover it. See Chatlio with Content Security Policy for complete policies.

The widget shows offline when we’re online

With automatic presence, the widget is online while at least one person in your Chatlio channel is active in Slack. Run /chatlio status, then check these:

  • Join your Chatlio channel. Only members of that channel count. Being in a visitor channel is not enough.
  • Set your Slack status to active. Someone who is away in Slack does not count.
  • Use a full Slack account. Guest accounts, bots and deactivated accounts never count.
  • Wait a minute. Chatlio checks presence about every 30 seconds.
  • Check the on/off switch. If someone ran /chatlio off, the widget stays offline until someone runs /chatlio on. The switch is also at the top of the widget’s Behavior page.
  • Check operating hours. With operating hours on, the widget is offline outside your hours. Run /chatlio print-op-hours to see the schedule, or turn it off with /chatlio op-hours-schedule.
  • Check the chat limit. If you set Max concurrent chats on the Behavior page, or ran /chatlio throttle-conversations, new visitors see the offline widget once that many chats are open. End finished chats with /chatlio end so they stop counting.

If presence still looks wrong, select Manual under Presence detection on the widget’s Behavior page, or run /chatlio manual-mode. The widget then stays online until you turn it off.

The widget shows online when nobody is around

  • Manual mode is on. In manual mode, Chatlio ignores your team’s Slack status and keeps the widget online until you turn it off. Run /chatlio manual-mode again, or select Detect presence automatically on the widget’s Behavior page.
  • Someone is still active. Anyone in your Chatlio channel who is active in Slack keeps the widget online, including on Slack’s mobile app. Remove people who do not answer chats from the channel.

To go offline on a schedule, set Operating Hours in the dashboard and turn the schedule on. /chatlio off takes the widget offline right away.

The end-of-chat rating never appears

  1. On the widget’s Appearance page, under Chat end, check that Show chat end screen is Yes and Allow visitor to rate conversations is Yes.
  2. Check how the chat ended. The visitor sees the rating after they select End chat in the widget, or when you end the chat from Slack while their widget is open. The minimize button only hides the widget, so a visitor who closes it that way never sees the rating.
  3. Check your site’s Content Security Policy for wss://api.chatlio.com, as described under Replies reach the visitor late. When that connection is blocked, the end screen and the rating arrive late, a few seconds after the chat ends.

Operator avatars don’t show

  1. On the widget’s Behavior page, under Avatars and agent labels, check Avatar display. Do not show avatars, use default agent label hides operator photos on purpose. To show them, choose one of the Use Slack profile avatar and name when chatting options.
  2. Wait for the first reply. Slack avatars and names show after an operator responds. Before a chat starts, the widget shows the team avatar, or the photo of an active operator, depending on your choice.
  3. Check your site’s Content Security Policy. Operator photos load from avatars.slack-edge.com and secure.gravatar.com. An img-src line that lists only certain hosts blocks them. Use img-src * data:, as in Chatlio with Content Security Policy.

If the widget shows a blank round button or the minimize arrow is missing, your img-src line doesn’t allow data:. Add data: to it.

/chatlio commands don’t work

  • “Not a Chatlio channel, Chatlio commands don’t work here.” Run commands in your Chatlio channel or in a visitor channel. Chatlio also answers this when the widget is not fully set up. See Chatlio stopped working after a Slack change.
  • Slack does not offer /chatlio. Your installation may be missing the slash command permission. Open the Permissions page. If Add slash commands, for example, /chatlio help shows Approval needed, click Upgrade Slack permissions to access all Chatlio features. Until then, you can type a command as a message, such as @chatlio status.
  • “No visitor chat found in this channel.” Commands such as /chatlio end, /chatlio email and /chatlio info act on one visitor. Run them in that visitor’s channel, not in your Chatlio channel.
  • “You cannot end the conversation in the main Chatlio channel.” Run /chatlio end or /chatlio discard in the visitor channel.
  • “To use the transcript feature Chatlio needs permission to access your Slack history.” /chatlio email and /chatlio send-to-webhook need permission to read the visitor channel, and so does /chatlio end when you send transcripts automatically. Follow the link in the message to the Permissions page and approve the permissions.
  • “Your current plan does not include this feature.” Some commands depend on your plan. See pricing, or change your plan under Account in the dashboard.
  • Chatlio answers with the help text. Chatlio did not recognize the command. Check the spelling against the command list.

Chatlio stopped working after a Slack change

Chatlio connects to Slack as the Slack user who installed it. If that connection stops working, Chatlio takes the widget back to setup, and the dashboard shows Connect your Slack workspace or Setup incomplete for it. This happens when:

  • Someone removed the Chatlio app from your Slack workspace or revoked its access.
  • The Slack user who installed Chatlio was deactivated, or became a single-channel guest.
  • The Chatlio channel was archived or deleted.

To reconnect:

  1. Open the widget in the dashboard.
  2. Click Add Chatlio to Slack and approve Chatlio in your workspace.
  3. Choose your Chatlio channel again.

Chatlio keeps the same widget, so the embed code on your site does not change.

To avoid this, install Chatlio as a Slack user who won’t leave, for example a dedicated @livechat_admin user. That user must be allowed to create channels and to remove members from public channels.

Other Slack changes can turn off parts of Chatlio without taking it offline:

  • Chatlio posts “ACTION REQUIRED: Chatlio channel is private”. You made your Chatlio channel private. Open the Permissions page and follow the instructions there. Slack does not let you make the channel public again, so to go back to a public channel, click Change channel on the widget’s Channel page and pick another one.
  • Transcripts, files or slash commands stopped working. Open the Permissions page. Any row that shows Approval needed is a feature Chatlio has no permission for yet. Click Upgrade Slack permissions to access all Chatlio features, and approve as the same Slack user who installed Chatlio. Otherwise the page says “It appears you authenticated a different Slack user than the one used to sign up for Chatlio.”
  • The Permissions page says Slack is changing its API. Your installation predates Slack’s current app model. Click Upgrade your Chatlio Slack integration now and approve the reinstallation.

A conversation ended that nobody ended

Chatlio ends a conversation and archives its visitor channel when:

  • An operator runs /chatlio end or /chatlio discard.
  • The last person leaves the visitor channel, for example with /leave.
  • The conversation started more than 12 hours ago and the visitor has sent nothing in the last 15 minutes. Chatlio checks every 30 minutes.

Except for /chatlio discard, each of these runs your post-chat actions, such as emailing the transcript. If the visitor writes again, Chatlio unarchives their channel, so you see the earlier messages.

When the visitor selects End chat in the widget, Chatlio posts a note in the visitor channel that the visitor ended the conversation, and leaves the channel open. Run /chatlio end or /leave there to archive it.

Too many channels

Chatlio creates a public channel for each visitor and archives it when the conversation ends, so it leaves your channel list. The Slack user who installed Chatlio leaves each new channel right away, so their sidebar stays clean.

  • Visitor channels stay in the channel list. Chatlio posts “A team preference prevented the authenticated user from archiving” a channel. Ask your Slack admin to let the user who installed Chatlio archive channels.
  • Archived Chatlio channels are piling up in your workspace. Contact us. We can set Chatlio to reuse its archived channels instead of creating new ones. A reused channel gets the new visitor’s name, and Chatlio posts “:recycle: RECYCLING CHANNEL :recycle:” in it when it still holds an earlier chat.
  • Your channel is not in the list during setup. The list leaves out #general, #random, archived channels, and channels another Chatlio widget already uses. In a workspace with a very large number of channels, the list can also stop before your channel. Create a new channel on the same page with Create and select channel.
  • The dashboard asks you to upgrade to add a channel. Each widget uses its own Chatlio channel, and your plan sets how many you can have. Upgrade your plan, or delete a widget you no longer use.