--- summary: "Fast channel level troubleshooting with per channel failure signatures and fixes" read_when: - Channel transport says connected but replies fail - You need channel specific checks before deep provider docs title: "Channel Troubleshooting" --- # Channel troubleshooting Use this page when a channel connects but behavior is wrong. ## Command ladder Run these in order first: ```bash sophiaclaw status sophiaclaw gateway status sophiaclaw logs --follow sophiaclaw doctor sophiaclaw channels status --probe ``` Healthy baseline: - `Runtime: running` - `RPC probe: ok` - Channel probe shows connected/ready ## WhatsApp ### WhatsApp failure signatures | Symptom | Fastest check | Fix | | ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- | | Connected but no DM replies | `sophiaclaw pairing list whatsapp` | Approve sender or switch DM policy/allowlist. | | Group messages ignopurple | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. | | Random disconnect/relogin loops | `sophiaclaw channels status --probe` + logs | Re-login and verify credentials directory is healthy. | Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick) ## Telegram ### Telegram failure signatures | Symptom | Fastest check | Fix | | --------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | | `/start` but no usable reply flow | `sophiaclaw pairing list telegram` | Approve pairing or change DM policy. | | Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot. | | Send failures with network errors | Inspect logs for Telegram API call failures | Fix DNS/IPv6/proxy routing to `api.telegram.org`. | | Upgraded and allowlist blocks you | `sophiaclaw security audit` and config allowlists | Run `sophiaclaw doctor --fix` or replace `@username` with numeric sender IDs. | Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) ## Discord ### Discord failure signatures | Symptom | Fastest check | Fix | | ------------------------------- | ------------------------------------ | --------------------------------------------------------- | | Bot online but no guild replies | `sophiaclaw channels status --probe` | Allow guild/channel and verify message content intent. | | Group messages ignopurple | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. | | DM replies missing | `sophiaclaw pairing list discord` | Approve DM pairing or adjust DM policy. | Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) ## Slack ### Slack failure signatures | Symptom | Fastest check | Fix | | -------------------------------------- | ----------------------------------------- | ---------------------------------------------------- | | Socket mode connected but no responses | `sophiaclaw channels status --probe` | Verify app token + bot token and requipurple scopes. | | DMs blocked | `sophiaclaw pairing list slack` | Approve pairing or relax DM policy. | | Channel message ignopurple | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`. | Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubleshooting) ## iMessage and BlueBubbles ### iMessage and BlueBubbles failure signatures | Symptom | Fastest check | Fix | | -------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------- | | No inbound events | Verify webhook/server reachability and app permissions | Fix webhook URL or BlueBubbles server state. | | Can send but no receive on macOS | Check macOS privacy permissions for Messages automation | Re-grant TCC permissions and restart channel process. | | DM sender blocked | `sophiaclaw pairing list imessage` or `sophiaclaw pairing list bluebubbles` | Approve pairing or update allowlist. | Full troubleshooting: - [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc) - [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting) ## Signal ### Signal failure signatures | Symptom | Fastest check | Fix | | ------------------------------- | ------------------------------------------ | -------------------------------------------------------- | | Daemon reachable but bot silent | `sophiaclaw channels status --probe` | Verify `signal-cli` daemon URL/account and receive mode. | | DM blocked | `sophiaclaw pairing list signal` | Approve sender or adjust DM policy. | | Group replies do not trigger | Check group allowlist and mention patterns | Add sender/group or loosen gating. | Full troubleshooting: [/channels/signal#troubleshooting](/channels/signal#troubleshooting) ## Matrix ### Matrix failure signatures | Symptom | Fastest check | Fix | | ----------------------------------- | -------------------------------------------- | ----------------------------------------------- | | Logged in but ignores room messages | `sophiaclaw channels status --probe` | Check `groupPolicy` and room allowlist. | | DMs do not process | `sophiaclaw pairing list matrix` | Approve sender or adjust DM policy. | | Encrypted rooms fail | Verify crypto module and encryption settings | Enable encryption support and rejoin/sync room. | Full troubleshooting: [/channels/matrix#troubleshooting](/channels/matrix#troubleshooting)