#Troubleshooting & FAQ

This page is grouped by what you are seeing. Use your browser's find-in-page (Ctrl/Cmd+F) to jump straight to it. If a word is unclear, see the Glossary. A few of these need a setting only the Owner can see — if that's not you, the fix is simply to let them know.

#Webhook & connection issues

#Meta says webhook verification failed

• Your site must be reachable over HTTPS — Meta refuses to verify a plain HTTP callback URL.
• Double-check the Verify token was copied exactly, with no leading/trailing spaces — copy it fresh from the channel's page rather than retyping it.
• Confirm the Site URL matches the domain you're actually testing on (see Subdirectory installs, in the Platform & Setup guide, if you're not at the domain root).

#Messages arrive in the Inbox, but there's never an AI reply

Check, in order:

1. Does the channel have an assistant, and does that assistant have a knowledge base and is it switched on? Without one, Threadline records the message but has nothing to answer from. See Assistants.
2. If you're the Owner, is Settings → System green? An amber warning means your cron job isn't running — see Cron Setup. If you're an Admin or Agent, this page isn't visible to you — ask your Owner to check it.
3. If you're the Owner, is there a banner on Settings → AI Providers saying a key failed? See below. Otherwise, ask your Owner.
4. Open the conversation in the Inbox — a failed AI attempt still shows as a message bubble marked "Failed," with the specific reason attached.

#A request to Threadline's webhook URL returns 429 Too Many Requests

This is intentional rate limiting (120 requests/minute per IP address) on the public webhook endpoints, meant to absorb a flood of garbage or replayed requests without falling over. Genuine WhatsApp/Telegram traffic for a single business won't come close to this limit — if you're hitting it, check whether something is looping (a misconfigured webhook retry, a monitoring tool polling the URL, etc).

#Instagram, Messenger & the website widget

#The AI never sends an image reply on Instagram

This is a genuine platform limitation, not a bug: Instagram's Messaging API has no confirmed way for Threadline's Instagram credentials to upload and send an outbound image. Threadline automatically falls back to a text-only reply on Instagram in this case — inbound images from customers are unaffected and still received normally. Messenger and WhatsApp both support outbound images with no such gap; see Connecting Instagram.

#The website widget doesn't appear on my site at all

A strict Content-Security-Policy header on your own site is the most common cause — it can silently block the widget's <script> tag from loading, or block its requests back to Threadline, with nothing visible except a missing chat bubble. Check your browser's developer console for a CSP violation, then add your Threadline domain to your site's script-src and connect-src directives. See Connecting the Website Widget.

#Webhooks & Lead Forms

#A webhook endpoint never receives any deliveries

Check the endpoint's delivery log first (Webhooks → the endpoint) — if every attempt shows as failed with a connection error rather than simply missing, the most likely cause is your own server or firewall blocking outbound requests from Threadline's server, not an error on Threadline's side. Confirm the endpoint URL is publicly reachable from outside your network, and that nothing (a firewall rule, an IP allowlist, a reverse proxy) rejects requests that don't originate from a browser. See Webhooks.

#A lead form never gets offered to any customer

The most common cause is simply forgetting to attach the form to a knowledge base or a channel — a form with neither set is saved but never triggers for anyone. Open the form in Lead Forms and confirm it's attached and marked Active. See Lead Forms.

#A returning customer isn't asked the lead form again

That's expected: each customer is asked a given form only once, even across new conversations. Attach a different form if you want returning customers asked new questions. See Lead Forms.

#AI provider issues

All four fixes below live under Settings → AI Providers, which only the Owner can see. If you're an Admin or Agent, the most useful thing you can do is confirm the symptom and pass it along.

#The bot always replies "I don't have enough information to answer that question"

This is the deliberate fallback the AI is instructed to use whenever nothing in the knowledge base is relevant enough to the question — not a bug, and something you can act on yourself. If it's happening on questions your content should cover, see Knowledge Base Best Practices, and try the same question in Playground to see exactly what was retrieved and its confidence score.

#A banner says "this key failed on its last use"

The provider rejected the API key on the most recent real request — usually because it was revoked, regenerated on the provider's own dashboard, or mistyped. The Owner needs to generate a fresh key from the provider and re-save it on Settings → AI Providers; the banner clears automatically once a request succeeds.

#The AI stopped answering and everyone's account admin/agent got an email about a quota

The Owner's AI provider account ran out of credits — Threadline detects this distinctly from an outage or a bad key. The Owner needs to add billing/credits on the provider's own dashboard (OpenAI, Anthropic, or Google AI Studio); there's nothing to configure inside Threadline itself.

#A conversation shows "Failed" and mentions a provider outage

Threadline automatically retries a failed reply up to 3 times, waiting roughly 30 seconds, then 2 minutes, then 5 minutes between attempts, before giving up. If the provider recovers within that window, the customer simply gets their reply a little late with no action needed from anyone. If all retries are exhausted, active admins/agents get a notification, and the conversation shows a "Failed" message in the Inbox so a human can step in in the meantime.

#Knowledge base & documents

#A document is stuck on "Processing" and never finishes

Almost always a stalled cron job on the server. If you're the Owner, check Settings → System for the scheduler warning, and see Cron Setup in the Platform & Setup guide — document processing (like message sending) runs on the same scheduled job. If you're not the Owner, let them know documents are stuck; there's nothing to fix from inside your own Account.

#A document failed with "no extractable text found"

The file has no real, selectable text layer — typically a scanned PDF that's actually just a picture of a page, a password-protected PDF, or a genuinely empty file. Run it through OCR first, or re-export it as a text-based PDF/DOCX.

#A URL document failed for being too large

URL-sourced documents are capped at 20MB fetched content, the same limit as a direct file upload — this protects the server from an unexpectedly huge linked file exhausting available memory. Link a smaller page, or copy the relevant text and use "Paste text" instead.

#An upload was rejected even though it's the right file type

Threadline checks a file's actual content, not just its extension — a renamed or corrupted file that doesn't genuinely match its claimed type (for example, a script or executable renamed to end in .pdf) is rejected rather than trusted. If a real PDF/DOCX/TXT/MD file is rejected, try re-saving/re-exporting it, since the original may be corrupted.

#Conversations & escalation

#A customer asked for a human, but the AI kept replying

Threadline detects common phrasings ("talk to a human," "speak to an agent," etc, in English) and flags the conversation for a human automatically — check Settings → Escalation for whether "Automatically switch to human" is turned on. If it's off, the AI keeps answering (by design, so the customer isn't left with no response at all) while the conversation is still flagged for a human to pick up whenever they're free.

#How do I take a conversation over from the AI myself?

Open it in the Inbox and use the takeover action — the AI stops replying to that conversation immediately, and everything you send from then on goes out as you, not the bot.

#I'm not receiving escalation alert emails

First check Settings → Escalation — the "Email notifications" toggle is per-Account, so you can confirm it yourself. If it's on and still nothing arrives, the Owner's mail server isn't set up (Settings → Mail Driver, Owner-only) — let them know.

#Inbox & team

#A conversation was handed over but nobody was assigned

With Automatically assign agents on and two or more agents, the AI assigns only when it finds a clear match between the question and an agent's designation. Otherwise the conversation waits under Waiting. Give your agents clearer designations on the Agents page. See Your Team.

#A saved reply still shows {{contact.name}}

That customer has no value saved for that detail. The code is left as written on purpose, so you notice before sending. Add the detail in the contact panel, or type it yourself. See Inbox.

#I mentioned a teammate in a note but they got no email

Check that you picked their name from the list that appears after typing @. If you did, the platform's email may not be set up. Tell the Owner.

#The "waiting" badge does not go away

Only a reply to the customer clears it. A note for your team does not.

#Contacts & Broadcast

#An import left some rows out

The message after the import says why. The usual reasons are a missing phone number, the same number twice in the file, a value that does not fit its field type, or your plan's contacts limit. See Contacts.

#People lost their opt-in after I imported a list again

Importing people who are already in the channel with the opt-in box unticked clears their opt-in. Import the list again with the box ticked, if those people did agree.

#A campaign cannot be sent

A person you ticked by hand has not opted in. Untick them, or mark them opted in on the Contacts page if they agreed. On WhatsApp you also need an approved template.

#A campaign is still sending the next day

The number reached Meta's limit for 24 hours, or its warm-up budget for the day. The rest goes out when there is room. See Broadcast.

#A campaign was paused by itself

WhatsApp lowered the number's quality rating to yellow or red. Review your audience and message, then open the campaign and click Resume.

#A template was rejected

Use Check template before submitting. It finds the common causes, such as variables out of order or text that starts or ends with a variable. Meta's own reason is shown in Meta's dashboard.

#Automations

#An automation did not run

Check that it is Active, that the contact matches its filters, and that it has not already run 5 times for that contact in the last hour. Then open Run history. See Automations.

#A "Send a message" step failed

On WhatsApp, Instagram and Messenger, a free-form message can only be sent within 24 hours of the customer's last message. Use Send a WhatsApp template for anything sent later.

#The customer got an automation message and an AI answer

The AI stays quiet only when the automation starts with a send step. Move the send step to the top, or add Pause the AI.

#I cannot switch from Canvas back to List

An automation with branches can only be shown on the canvas. The list can show a single straight line of steps.

#Deals

#Deals, Automations or API access is missing from the menu

Your plan does not include that feature. See Plans & Billing.

#I cannot delete a stage or a pipeline

A stage must be empty before it can be deleted, so move its deals first. The default pipeline, and a pipeline that still has deals, cannot be deleted.

#WhatsApp links & lead ads

#A WhatsApp link gets clicks but no conversations

People open the link but do not press send, or they delete the reference code from the message. Also check that the number saved on the link is the number of the channel you chose. See WhatsApp Links.

#No lead ad leads are arriving

The connection must be switched on, Meta must have approved the leads_retrieval permission, and the Page must be subscribed to leadgen. See Meta Lead Ads.

#API

#The API answers 401, 403, 429 or 422

401 means the token is wrong or revoked. 403 means the token is not allowed to do that. 429 means more than 60 requests in a minute. 422 on a text message means the 24-hour window has closed, so send a template. See Integrations & API.

#Inbox, templates and statuses

#A conversation vanished from my list

It may be Snoozed (open the Snoozed tab), Resolved, or filtered out by a label or channel. A snoozed conversation returns by itself at the time you chose, or when the customer writes. See Inbox.

#I can only choose a template, not type a reply

The 24-hour reply window is closed (48 hours on WeChat). Pick an approved template, or wait for the customer to write. See WhatsApp Templates.

#My template is stuck on Pending or Rejected

Pending usually clears within a day; click Sync from Meta to refresh. For Rejected, the reason is shown on the card: click Fix, change the text (often a missing example or a variable at the very start or end) and Resubmit.

#An auto reply did not fire

Check it is Enabled, its channel matches, the keyword really appears in the message, and a rule with a lower priority number is not answering first. See Auto Replies.

#SMS and email

#SMS shows Sent but never Delivered, or customers cannot reply

Your SMS provider may not send delivery reports or replies (the table on the SMS page shows which). For providers that do, the inbound address must be pasted into the provider's dashboard.

#An email campaign cannot be launched

Add your business address under Settings, Workspace, and make sure the subject and the email are filled in. See Email.

#Emails land in spam or bounce

Send through a proper service with your domain set up (SPF and DKIM), keep your list clean, and check the campaign report for Bounced recipients. See Email.

#Texts or emails say my plan's monthly limit has been used up

Your plan caps SMS or emails per month. It starts again next month; upgrade for more. See Plans & Billing.

#Stores, leads and social

#My store shows an error or orders are missing

Open Stores: the card shows the store's last message. Press Edit, enter fresh keys, then Test and Sync now. See Online Stores.

#An order or cart does not show beside the conversation

Orders are matched by the customer's phone number or email. If they used a different one in the shop, there is no match.

#A Lead finder search failed

The message says why: quota used up, key refused, place not found, or your lead credits ran out. See Lead Finder.

#I cannot add a lead to a campaign

Leads from the Lead finder or a store have consent off on purpose. Record that they agreed first. See Contacts.

#A social post failed or an account says Token expired

Open the post: each account shows the network's reason. For an expired token press Reconnect. See Social Media.

#Account, data and billing

#I did not get my data export

Check spam and the bell. The page shows "Building your export…" until ready. The link works for 72 hours; request a new one if it expired. See Data and Security.

#My promo code was refused

The message under the box says why: not found, switched off, expired, used up, not valid for this plan, or already used by your workspace. See Plans & Billing.

#I do not see Reports, Assistants or Media library

They are Admin areas. Agents do not see them. See Your Team.

#Installation, plans & access

#You're sent to the plans page, or your Agents see "Your account is inactive"

Your Account has no live subscription — it was never started, it ended after being cancelled, or the payment gateway reports it gone. As the Admin, choose a plan under Settings → Plans (see Plans & Billing). If that doesn't look right, ask the Owner to check your Account.

#A menu item such as Broadcast is missing or locked

On a SaaS install, some features only come with plans that include them. Check what your current plan includes, or upgrade, under Settings → Plans (see Plans & Billing). The Owner can also review or change what each plan includes under Pricing Plans, in the Platform & Setup guide's SaaS Setup page.