Troubleshooting

Common CoPhrase problems and what to do — wrong answers, a silent agent, disconnected channels, delivery failures, and unexpected credit use.

The agent gave a wrong answer

Almost always a knowledge problem, not a model problem. The agent answers from what you gave it; if what you gave it is stale, missing, or contradictory, that is what comes back out.

Work through it in this order:

Check the answer is actually in the knowledge base. Search your knowledge for the fact the agent got wrong. If it isn't there, the agent didn't have it — it wasn't lying, it was filling a gap. Add it.

Check the knowledge isn't stale. Your agent knows your website as of the last crawl. If you changed your pricing page yesterday and haven't re-synced, the agent is still quoting last month's price. Re-sync the source — re-training only bills for pages that actually changed.

Check for contradictions. Two sources saying different things (an old FAQ and a new pricing page) will produce inconsistent answers. Delete or fix the stale one. A curated FAQ can be stale too — being hand-written doesn't make it right.

Write it as an FAQ. A hand-written question-and-answer pair is the most reliable form of knowledge there is: it's stored whole, and it's an exact match for the question your customers actually ask.

See knowledge. If the agent is inventing prices or policies rather than getting them stale, that's a bug — tell us.

The agent didn't reply at all

Silence is usually deliberate. Check these in order:

Cause	What you'll see	Fix
A human took over the thread	The conversation is under human control in the inbox	Hand control back to the agent
Someone replied from the channel's own app	You answered from your phone's WhatsApp/Instagram app, so the agent backed off	Expected. The agent resumes after the pause window, or hand it back explicitly
The contact has the agent switched off	Contact-level "bot off" or do-not-disturb is set	Turn it back on for that contact
The first message was classified as spam	The contact is flagged as spam and hidden from the inbox	Unflag the contact
Approval mode is on	The reply is sitting as a draft waiting for a human	Approve it — or turn approval mode off. See handoff
Out of hours	The agent is holding the reply until your next active window	Expected, if you configured business hours
The runaway cap was hit	The agent has already sent its configured maximum number of messages in this conversation	Raise the cap, or take the thread over
A BYOK key is failing	The agent is paused with an alert on that agent	Fix or replace the provider key. It will not silently fall back to platform inference

A channel disconnected

Why it happens depends on how the channel is connected.

Session-based channels — WhatsApp Web, Telegram personal, Instagram personal, iMessage — are not tokens. They are a live session bound to a real account, exactly like the linked-device list on your phone. That session can die for reasons that have nothing to do with CoPhrase:

Someone logged out the linked device from the phone.
The account was logged into somewhere else, or the password was changed.
The platform invalidated the session (that is their prerogative, and it is not appealable through us).
The phone the account lives on was offline for a long stretch.

The fix is to re-authenticate the connection — scan the QR code again, or re-enter the login code. Nothing else recovers a dead session.

Token-based official channels — Instagram via the official API, Messenger, Telegram bots, Discord, WhatsApp Business API — disconnect when a token is revoked or expires, or when someone removes the app's permission on the platform side. Fix: re-authorize the connection from the dashboard.

Unofficial channels carry account risk

Session-based channels run against a platform's consumer app, not a supported API. Sending aggressively from a cold account is how accounts get restricted or banned — and the account is yours, not ours. Respect the warm-up ramps, and don't connect a brand-new number that has never received a message. If a channel needs to be bulletproof, use the official tier.

"Restricted" is not the same as "banned"

A restricted account is the nastier failure, because it looks like it's working. Replies inside existing conversations still go out, while messages to new contacts silently fail. If new conversations are dropping to zero while existing ones look fine, check the connection health status before you go looking for a bug in the agent.

Messages arrive but no conversation appears

The first message was flagged as spam. New contacts get their first message classified; a spam-flagged contact is hidden from the inbox and the agent stays quiet.
The channel is attached to a different agent. Check which agent that channel connection routes to.

The reply was cut short, or the formatting is gone

Every channel has hard limits, and providers silently truncate rather than erroring. Instagram caps outbound messages at 1,000 characters; Telegram at 4,096. Rich content — buttons, reactions, media types — degrades to plain text on channels that can't render it.

The agent is told the channel's limits before it writes, so it should compose to fit. If you are consistently seeing amputated replies, tighten the persona so the agent writes shorter on that channel. See persona.

"I can't send a message to this contact"

On WhatsApp, Instagram, and Messenger, Meta controls when you're allowed to message someone:

The 24-hour window opens only when the customer messages you. Not when you reply — when they write.
Outside the window on Instagram and Messenger, you cannot send a free-form message at all. You can never message first.
Outside the window on WhatsApp, only pre-approved templates may be sent. Sending a template does not reopen the free-form window — it stays templates-only until the customer replies.

This is a platform rule, not a CoPhrase setting, and there is no way around it.

An image or audio attachment wasn't processed

Providers hand out media links that expire within minutes. If the system was backed up when a message arrived, the link can die before it's fetched, and the item ends up marked as unavailable. It is retried before being given up on. If you see this regularly rather than occasionally, tell us — that is a symptom of something degraded on our side, not normal behavior.

A webhook stopped firing

It was auto-disabled. After enough consecutive failed deliveries we stop delivering and mark the webhook disabled with a reason. Re-enabling it is a deliberate manual action — re-saving the endpoint won't silently re-arm it. Check the delivery log for the response your endpoint was actually returning.
The endpoint isn't reachable. Webhook targets must be public HTTPS URLs. localhost, private IP ranges, and internal hostnames are rejected.

See API and webhooks.

Credits are going faster than expected

Check what you're actually billed for. One agent reply — 1 credit on Pro, 0.25 on Core — not one customer message. Rapid-fire messages answered together are one reply. If usage looks like it's counting customer messages, it isn't; something else is spending them.
Tool actions and web searches add up. Each successful tool action is 0.25 and each web search is 0.5. A chatty agent that books, looks up, and searches on every thread costs more than its replies alone.
Knowledge training is the usual surprise. Crawling a large site the first time is a real cost. Re-syncs only bill for changed pages, so a repeated cost here means the source really is changing.
Check for a runaway thread. A conversation with a huge number of agent turns is worth reading. That is what the per-conversation message cap is for.

See billing.