Start with the System check.
Then read the channel's own error.
The most common problems, the exact message Omnithread shows for them, and what to do.
01Three places to look first
- Setup > System check. Every red or yellow line says what to fix (PHP, extensions, cron, HTTPS, storage, key).
- Setup > Channels. The health of each channel and its last error. Open the channel and run Test connection.
- The channel's Webhook log (chat channels). If a test message is not there, the provider never reached your CRM.
02E-mail
New mail does not arrive
The Perfex cron must run every 5 minutes; the System check shows when it last ran Omnithread. Check that the mailbox is Active and its health is not Not working. A big first import arrives over several cron runs.
"The user name or password was not accepted."
Use the full e-mail address as the user name. For Gmail create an app password (steps) or use Sign in with Google. Microsoft 365 and Outlook.com need Sign in with Microsoft.
"This server accepts only Microsoft sign-in."
Choose Sign in with Microsoft for the mailbox (steps).
"The server refused the connection." or "The server did not answer in time."
Check the server name and port, and ask your host whether outgoing connections to that port are allowed. Many shared hosts block outgoing mail ports until you ask.
"This port expects SSL/TLS" or "This port expects STARTTLS or no encryption"
Use 993 (IMAP) or 465 (SMTP) with SSL/TLS, or 143 and 587 with STARTTLS.
"The secure connection failed."
Check the encryption setting. Switch off Check the server certificate only if your own server uses a self-signed certificate.
"This server address points to this server, the cloud metadata service or a private network"
Use the mail server's public name. If it really is on your private network, switch on Allow mail servers on the local network in Settings > E-mail.
Google or Microsoft: "Sign-in with Google or Microsoft is not set up yet."
Paste the client ID and secret of your own app in Settings > Mailbox sign-in and save.
Google or Microsoft shows a redirect address error
The redirect address in your Google or Microsoft app must be exactly the one shown in Settings > Mailbox sign-in, including https:// and your CRM's domain.
"The sign-in of this mailbox has expired or was withdrawn." or "The mail server did not accept the sign-in."
Open the mailbox and press Sign in again. For Microsoft 365, IMAP and authenticated SMTP must be switched on for the mailbox.
"No Sent folder is set for this mailbox, so no copy was saved on the server."
Run Test connection in the mailbox and pick the Sent folder in the folder mapping.
03WhatsApp, Messenger and Instagram
Meta's "Verify and save" fails
Your CRM must be reachable on a public https:// address, and the verify token in Meta must be exactly the one saved in step 1. The webhook log shows the attempt as Refused with The verify token did not match when the token differs.
Requests show "Refused": "The request was not signed with this channel's app secret."
Paste the App secret of the Meta app that sends the webhooks (App settings > Basic), save, then Replay the refused request if its content was kept, or ask the customer to write again.
Nothing reaches the webhook log
Check that the callback address is saved in your Meta app and that it is subscribed to messages (Messenger also messaging_postbacks). Your Meta app may also need the access Meta requires before it delivers messages from people without a role in the app.
"The 24-hour reply window has closed."
On WhatsApp send an approved template (Setup > WhatsApp templates, Sync from Meta). On Messenger and Instagram wait until the customer writes again.
"This Facebook Page has no Instagram professional account linked to it." / "This Page is linked to the Instagram account …"
Link the Instagram professional account to the Page, or enter the Instagram account ID that Test connection shows.
04Telegram and SMS
"Telegram did not accept the bot token."
Copy the token again from @BotFather (/token) and save.
"Telegram refused this site's webhook address"
Telegram needs a public https:// address. Fix it, then run Test connection again; it registers the address.
Messages from a Telegram group do not arrive
By design: only private chats with the bot are read.
Twilio requests are refused
Twilio signs the exact address it calls. Paste the address exactly as Omnithread shows it, and make sure your Perfex base URL is the public https:// address customers' providers reach (not an internal or other domain).
"SMS replies cannot carry files."
Send the text alone. Pictures customers send by MMS still arrive.
"Enter the Account SID (starts with AC), the auth token, and a Twilio number or Messaging Service SID."
All three are needed; the number in E.164 form, for example +15550100099.
05Website chat
The chat button does not appear
Check that The chat is on, that the embed line is on the page before </body>, and that the page's address is in Websites that may show the chat exactly (https:// and www matter). A Content-Security-Policy on your website must allow your CRM's address.
"This chat is not available on this website."
The page's address is not in the allowed list, or the chat is switched off.
"Too many chats were started from your network."
The limit of 10 new chats per hour from one network address was reached, for example during your own testing. Wait an hour.
06Replies and tickets
A reply shows "Not delivered"
Open it to read the provider's reason, fix it (for example the channel's token), then press Try again.
"This reply needs approval before it is sent."
The staff member works under reply approval; use Send for approval. See Reply approval.
"Your ticket reply could not be sent to the customer's channel"
The author needs Write, reply and add notes, must not be under approval and must be able to open the conversation; a closed WhatsApp window also blocks it. Answer from the inbox instead.
"Perfex did not create the record."
Check the lead status and source, or the ticket department, in Settings > Tickets and leads.
07Staff, setup and storage
A staff member has no Omnithread menu, or does not see a channel
Give the Omnithread permissions (list) and tick the person or their role under Who can use it on the channel. Mailboxes must also be marked Shared mailbox.
"The stored password cannot be read (the encryption key changed)."
The key file uploads/omnithread/omnithread-key.php was lost or replaced. Restore it from your backup, or enter the passwords and tokens again.
System check: "Folder not writable"
Let the web server user write to uploads/omnithread/ (or your storage folder), then run the check again.
System check: "The encryption key is stored in the database"
uploads/ was not writable at the first activation. The module works; the key is simply in the database. Make uploads/omnithread writable, then deactivate and activate the module to move the same key into a file. See The encryption key.
Reports are empty
Choose a longer period or fewer filters. Reports cover only channels you may see, and the cron must run to fill the summary tables.
08AI
"AI is switched off in Settings."
Switch on the AI assistant in Settings > AI assistant and save.
"The monthly AI limit … is reached." / "Your daily AI limit … is reached."
Raise the limits in Settings > AI assistant (0 = no limit), or wait for the next month or day.
"The AI provider did not accept the API key." / "The AI provider does not know this model."
Paste a valid key and the exact model name from your provider, save, then press Test the AI connection.
"The AI endpoint address is not allowed …"
A custom OpenAI-compatible endpoint must be a public internet address. For a model on this server or your local network, choose Ollama (local).
09Still stuck
See Support for what to send so we can help quickly.