Channel Connection Issues
This page covers channel connection failures in the desktop app. Each entry is a problem, its cause, and the fix. For the channel concept and the tier model, see Channels.
Status stuck on idle
Section titled “Status stuck on idle”Problem: you entered credentials but the channel status never moves from idle to connected.
Cause: the credential is wrong, or the channel never received the inbound traffic it needs to confirm a connection.
Fix:
- Re-check the token or credential against the provider console. A single trailing space breaks it.
- For channels that connect outbound (such as a bot polling for updates), connection should establish shortly after you save. If it does not, the token is the first suspect.
- For channels that depend on inbound delivery (webhooks), the status confirms only once a message arrives. Send a test message, then watch the status.
Bot token or scope errors
Section titled “Bot token or scope errors”Problem: the channel reports an authorization or permission error.
Cause: the token is valid but lacks the scopes or intents the channel needs, or it belongs to the wrong app or bot.
Fix:
- Recreate or re-copy the token from the provider, making sure it is the bot token and not an unrelated app secret.
- Grant the required scopes or gateway intents. Each setup guide lists what its channel needs, for example Discord gateway intents or Slack bot scopes. See Channels: Slack and Channels: Discord.
- After changing scopes, reconnect so the new permissions take effect.
Webhook not received
Section titled “Webhook not received”Problem: a webhook-based channel never sees inbound messages.
Cause: the provider cannot reach your endpoint, the signing secret does not match, or the payload shape is unexpected.
Fix:
- Confirm the inbound URL the provider posts to is reachable from the public internet. A desktop on a private network needs remote access or a tunnel for an external provider to reach it.
- Match the signing secret on both sides exactly.
- Send a test event from the provider console and watch for it to arrive. See Channels: Webhook.
WhatsApp or Signal bridge problems
Section titled “WhatsApp or Signal bridge problems”Problem: WhatsApp or Signal connects, then drops, or never finishes pairing.
Cause: these channels run a local bridge runtime. WhatsApp uses a bridge with QR or session pairing; Signal uses a signal-cli runtime with a registration or link step. A bridge that did not finish pairing, or that lost its session, will not deliver messages.
Fix:
- Complete the pairing step fully. For WhatsApp, scan the QR or restore the session; for Signal, finish registration or linking. See Channels: WhatsApp and Channels: Signal.
- If a session expired, re-pair from the channel settings.
- Keep the app running. A local bridge needs the host process alive to relay messages.
Pairing failures
Section titled “Pairing failures”Problem: a device or account pairing flow does not complete.
Cause: an interrupted handshake, an expired code, or a clock skew between the two ends.
Fix: restart the pairing flow to get a fresh code, complete it promptly, and make sure both the host and the device have a roughly correct clock.
Messages arrive but nothing happens
Section titled “Messages arrive but nothing happens”Problem: inbound messages reach the channel but no assistant responds.
Cause: the channel is connected but not routed to an assistant or team.
Fix: route the channel to an assistant so inbound messages open or continue a conversation with it. Then confirm a model provider is connected, because a routed channel still needs a working model to reply.