Troubleshoot Chatlio in Microsoft Teams

Start with @Chatlio status in your Chatlio channel. It shows whether the widget is on and what controls its availability. If you are still stuck, contact us with your widget name and what you tried.

I cannot find Chatlio in Teams

Chatlio is not in the Teams app store yet. A Teams administrator adds it to your organization from a file.

In the Chatlio dashboard, open the widget’s setup and click Download the app file. Leave the file zipped.
Only a Teams administrator can upload to your organization’s app catalog. If you are not one, send the file to your Teams admin.
As the admin, open Teams and select Apps on the left, then Manage your apps at the bottom of the Apps panel, then Upload an app at the top of the page.
Choose Upload an app to your org’s app catalog and pick the file. Do not choose Upload a custom app, which puts Chatlio in one team only.
In Teams, open Apps and look under Built for your org.

An administrator can also upload the file in the Teams admin center under Teams apps, Manage apps, Upload new app. In a brand-new Microsoft 365 organization that button can be greyed out at first. The admin center says it is setting up app management, which can take up to 30 minutes.

Teams can take a while to list a newly uploaded app. To add it to your team right away, an administrator selects Chatlio under Manage apps in the Teams admin center, then Add to team.

If Chatlio still does not show up in Teams, ask your administrator whether your organization allows custom apps.

“An unknown error occurred.” when I select Add

Teams can show this when you add Chatlio to a team in a very new Microsoft 365 organization. Wait a minute and select Add again.

We saw it in an organization that was a few minutes old. The same click worked a minute later, and the next day Add worked the first time. If it keeps failing, contact us.

The link command does nothing

Chatlio does not answer @Chatlio link <code> in Teams. Look at the widget’s setup in the dashboard instead: it shows Connected to Teams a few seconds after the command arrives. If it does not:

Pick the bot in the mention. Type @Chatlio and choose the Chatlio bot from the picker, not a team or channel with a similar name. The message must read @Chatlio link <code> and nothing else.
Check the code. A code works once and expires after 10 minutes. Getting a new code cancels the old one. Click Get a new code and post the new one.
Use a standard channel, not a private or shared one.
Check the team. Chatlio must be added to the team the channel is in.
One channel, one widget. A channel that is already linked to another Chatlio widget cannot be linked again.
Ask an account administrator. Only an account administrator of your Chatlio account can get a linking code.

Visitor messages do not show up in Teams

Open the widget in the dashboard. If its status reads Removed from Teams, Teams team deleted or Teams channel deleted, see The widget went offline or disappeared from my site.
If setup asks you to link a channel or activate the widget, finish those steps.
To use another channel, click Change channel on the widget’s Channel page.
Send a test message. On the widget’s Widget Install page, select Open test page.

Each visitor is one post in the channel with their messages as replies under it. Teams notifies you about a new post only if you turned on channel notifications for all new posts, or if you are mentioned. To turn them on, hover over the channel in Teams, select More options, then Channel notifications. To be mentioned, turn on Mention your team when a new visitor starts a chat on the widget’s Behavior page.

If one visitor’s messages do not arrive while others do, check whether their address is banned: @Chatlio unban lists the bans. See A visitor says their messages do not arrive.

The widget went offline or disappeared from my site

A Teams widget needs a linked channel. It loses its channel when:

Chatlio was removed from the team, or the team or channel was deleted in Teams. The widget is offline, and visitors see what you chose under When Chatlio is off on the Behavior page, a contact form or no widget. The widget’s status in the dashboard reads Removed from Teams, Teams team deleted or Teams channel deleted. Add Chatlio back to the team (Apps, then Built for your org, then Add), or restore the team or channel in Teams. The widget comes back by itself, in the same channel, with the settings it had. If Chatlio is not listed under Built for your org, download the app file from the widget’s setup and have a Teams admin upload it again.
Someone clicked Change channel. The widget is offline, as above, until you post the link command in the new channel.
Someone clicked Disconnect Teams. Visitors no longer see the widget. Link a channel in the widget’s setup, then click Activate widget.

If the widget does not come back by itself, open its setup, get a code and post @Chatlio link <code> in the channel you want.

Conversations that were open when the channel went away are closed. A visitor who writes again gets a new thread.

Visitors do not get my replies

Reply inside the visitor’s thread, under their conversation card. A new post in the channel is not sent to anyone.
If the conversation has ended, replies in its thread are not delivered, and Chatlio says so in the thread. Chatlio starts a new thread when the visitor writes again.
A conversation nobody ends closes by itself after 12 hours, once it has been quiet for 15 minutes. Check the conversation card: if it says Closed, the conversation is over. See Conversations nobody ends.
Files you attach in Teams do not reach visitors yet. The text of your reply still arrives. Under it, the visitor sees “An attachment could not be delivered:” and the file’s name.
If your message started with @Chatlio and a command word such as reply, email or ban, Chatlio ran it as a command and did not send it to the visitor. See Chatlio answered a message I meant for the visitor.

Separate chats do not turn on, or stopped

A separate chat per visitor needs a one-time approval from a Microsoft 365 administrator. Open the widget’s Teams setup and look under Your Teams connection.

“Microsoft has not recorded the approval.” An administrator has to select Accept on Microsoft’s page, signed in to the same Microsoft organization as the linked team. Microsoft can take a minute to record it. Click Check again. If it still says so, click Allow separate chats and approve again.
“Microsoft has not recorded the approval.” right after approving. Microsoft can take a minute to show a new approval. Teams setup waits and checks again by itself for a minute and a half.
“Chatlio could not find its app in the linked team.” Add Chatlio to the team the linked channel is in, then click Check again. If your organization uploaded the Chatlio app before separate chats existed, a Teams administrator updates it with the current app file (Download the app file in the same box): in the Teams admin center, open Manage apps, select Chatlio, and under New version select Upload file. Teams does not update an uploaded app from inside Teams, and the team keeps its old copy. To replace it, remove Chatlio from the team in Teams (the widget goes offline), then in the Teams admin center select Chatlio under Manage apps, select Add to team and pick the team. The widget comes back by itself.
“Chatlio is in the linked team as a custom app.” Someone uploaded the app file straight into the team instead of into your organization’s app catalog. Microsoft only puts an app from the catalog into a new chat. A Teams administrator uploads the app file to the catalog (in Teams: Apps, Manage your apps, Upload an app, Upload an app to your org’s app catalog), removes Chatlio from the team, and adds it again from Built for your org. Then click Check again.
“Microsoft did not answer.” Click Check again in a minute.
“Microsoft refused to create a visitor chat.” Visitors are still answered: their conversations continue as threads in the linked channel. The approval may have been withdrawn, or the Chatlio app removed from your organization. Click Check again. If the notice stays, click Allow separate chats and approve again.
Microsoft’s page says the request needs an administrator. You are signed in to Microsoft without administrator rights. Send that page’s address to a Microsoft 365 administrator, and click Check again after they accept.

A conversation closed by itself

Chatlio closes a conversation that nobody ended once it is more than 12 hours old and neither side has written for 15 minutes. The card changes to Closed, Chatlio sends the transcript email and the transcript webhook as after @Chatlio end, and nothing is posted in the thread. A visitor who writes again gets a new thread.

Chatlio does not answer a command

Start the message with the mention. Type @Chatlio and pick the Chatlio bot from the picker. A typed @Chatlio that you did not pick works only when a command from the command list follows it.
Send a new message. Editing an old message into a command does nothing.
Use the whole word, alone. @Chatlio off is a command. @Chatlio off for lunch is not, and in a visitor’s thread it is sent to the visitor as a reply.
Post in the linked channel or a visitor’s thread. Chatlio ignores other channels of the team.
@Chatlio discard and @Chatlio end answer when the conversation has closed, a moment after you send them.
Run the command again. Most commands are safe to repeat. For @Chatlio end and @Chatlio discard, check the conversation card first: if it says Closed, the conversation already ended.

See the command list.

Chatlio answered a message I meant for the visitor

A message that starts with @Chatlio and then reply, question-group, ask-for-info, identify, email, send-to-webhook, ban or unban is a command, whatever follows. @Chatlio email me the details asks Chatlio to email the transcript and answers that “me the details” is not a valid email address.

To write to the visitor, reply in their thread without mentioning Chatlio. You never need the mention for a normal reply.

“This command is only available inside a Chatlio visitor thread”

Commands such as @Chatlio reply, @Chatlio question-group, @Chatlio screenshot, @Chatlio identify, @Chatlio ban and @Chatlio discard act on one visitor, so run them as a reply inside that visitor’s thread, not as a new post in the channel. @Chatlio email and @Chatlio send-to-webhook answer “No conversation found” for the same reason.

“This conversation has ended”

You ran a command in the thread of a conversation that is already over. Run it as a new post in the Chatlio channel, or in the visitor’s current thread if they have started a new conversation.

A visitor says their messages do not arrive

Their IP address may be banned. A banned visitor is not told: their widget looks normal and what they send goes nowhere. A ban covers everyone who shares that address, such as an office network.

@Chatlio unban lists the banned addresses for the widget.
@Chatlio unban <ip> lifts a ban. The visitor’s next message arrives as usual.

“Teams transcripts need Chat History Storage”

@Chatlio email and @Chatlio send-to-webhook send the transcript Chatlio has stored, and so do the transcript email and the transcript webhook at the end of a conversation. That needs Chat History Storage. New accounts start with it on. On an existing account it is off until an account admin turns it on in the dashboard, under Account & users. While it is off, the two commands answer “Teams transcripts need Chat History Storage. Turn it on under Account” with a link to that page, and Chatlio sends no transcript at the end of a conversation.

After you turn it on, a transcript has the text of the messages sent from then on. An earlier message in the same conversation shows as “[Message content is no longer retained]”.

@Chatlio send-to-webhook also needs a webhook address on the widget’s Behavior page, under Webhooks and post-chat actions.

A saved reply was sent that nobody sent

The saved reply has trigger phrases and Send automatically on, and the visitor’s message contained one of the phrases. Chatlio says so in the thread: “Chatlio matched and automatically sent a saved reply”. To stop it, edit the reply on the widget’s Saved Replies page and turn Send automatically off, or make the trigger phrases more specific. A phrase matches anywhere in the message and ignores upper and lower case.

“No saved replies found”

Chatlio looks for a saved reply whose label or shortcut matches what you typed after reply. Type @Chatlio replies to list them, or add one on the widget’s Saved Replies page. Question groups work the same way with @Chatlio question-groups.

The visitor did not get my screenshot request

@Chatlio screenshot needs the widget to be on and the visitor to still have your site open. Chatlio answers “Chatlio is off” when the widget is off, and “Visitor seems to be offline” when the visitor has left. The visitor can also decline. Chatlio says so in the thread.

The widget shows online when nobody is around

New Teams widgets are online whenever Chatlio is on. Automatic availability from Teams presence is not available yet, so Chatlio does not read your team’s presence in Teams. 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 widget stays offline

Open the widget in the dashboard. If its status reads Removed from Teams, Teams team deleted or Teams channel deleted, see The widget went offline or disappeared from my site.
Run @Chatlio status to see what is in control.
With operating hours on, the widget is offline outside your hours. @Chatlio on overrides this until the next start or end of your hours.
If someone ran @Chatlio off, run @Chatlio on or @Chatlio auto.
After Change channel, the widget is offline until you post the link command in the new channel.

Troubleshooting Chatlio for Microsoft Teams