> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Channel Troubleshooting

# Channel troubleshooting

Use this page when a channel connects but behavior is wrong.

## Command ladder

Run these in order first:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi status
agdi gateway status
agdi logs --follow
agdi doctor
agdi 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 | `agdi pairing list whatsapp` | Approve sender or switch DM policy/allowlist. |
| Group messages ignored | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. |
| Random disconnect/relogin loops | `agdi channels status --probe` + logs | Re-login and verify credentials directory is healthy. |

Full troubleshooting: [/channels/whatsapp#troubleshooting](https://agdiai-597e782f.mintlify.site/channels/whatsapp.md#troubleshooting)

## Telegram

### Telegram failure signatures

| Symptom | Fastest check | Fix |
| - | - | - |
| `/start` but no usable reply flow | `agdi 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`. |
| `setMyCommands` rejected at startup | Inspect logs for `BOT_COMMANDS_TOO_MUCH` | Reduce plugin/skill/custom Telegram commands or disable native menus. |
| Upgraded and allowlist blocks you | `agdi security audit` and config allowlists | Run `agdi doctor --fix` or replace `@username` with numeric sender IDs. |

Full troubleshooting: [/channels/telegram#troubleshooting](https://agdiai-597e782f.mintlify.site/channels/telegram.md#troubleshooting)

## Discord

### Discord failure signatures

| Symptom | Fastest check | Fix |
| - | - | - |
| Bot online but no guild replies | `agdi channels status --probe` | Allow guild/channel and verify message content intent. |
| Group messages ignored | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. |
| DM replies missing | `agdi pairing list discord` | Approve DM pairing or adjust DM policy. |

Full troubleshooting: [/channels/discord#troubleshooting](https://agdiai-597e782f.mintlify.site/channels/discord.md#troubleshooting)

## Slack

### Slack failure signatures

| Symptom | Fastest check | Fix |
| - | - | - |
| Socket mode connected but no responses | `agdi channels status --probe` | Verify app token + bot token and required scopes. |
| DMs blocked | `agdi pairing list slack` | Approve pairing or relax DM policy. |
| Channel message ignored | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`. |

Full troubleshooting: [/channels/slack#troubleshooting](https://agdiai-597e782f.mintlify.site/channels/slack.md#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 | `agdi pairing list imessage` or `agdi pairing list bluebubbles` | Approve pairing or update allowlist. |

Full troubleshooting:

* [/channels/imessage#troubleshooting](https://agdiai-597e782f.mintlify.site/channels/imessage.md#troubleshooting)
* [/channels/bluebubbles#troubleshooting](https://agdiai-597e782f.mintlify.site/channels/bluebubbles.md#troubleshooting)

## Signal

### Signal failure signatures

| Symptom | Fastest check | Fix |
| - | - | - |
| Daemon reachable but bot silent | `agdi channels status --probe` | Verify `signal-cli` daemon URL/account and receive mode. |
| DM blocked | `agdi 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](https://agdiai-597e782f.mintlify.site/channels/signal.md#troubleshooting)

## Matrix

### Matrix failure signatures

| Symptom | Fastest check | Fix |
| - | - | - |
| Logged in but ignores room messages | `agdi channels status --probe` | Check `groupPolicy` and room allowlist. |
| DMs do not process | `agdi 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 setup and config: [Matrix](https://agdiai-597e782f.mintlify.site/channels/matrix.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.