Channels

Channels Module: Step-by-Step Tutorial

Use channels for reliable message delivery. Start with terminal, then add Slack or Telegram when needed.

Step 1: Inspect supported channel kinds

mosaic --project-state channels capabilities
mosaic --project-state channels resolve --channel terminal local

Step 2: Add a terminal channel (no credentials)

mosaic --project-state channels add --name local-terminal --kind terminal
mosaic --project-state channels list
mosaic --project-state channels status

Step 3: Validate delivery path

mosaic --project-state channels test <channel_id>
mosaic --project-state channels send <channel_id> --text "channels tutorial ok"
mosaic --project-state channels logs --channel <channel_id> --tail 20
mosaic --project-state channels logs --channel <channel_id> --tail 20 --summary

Step 4: Add Slack webhook channel

mosaic --project-state channels add \
  --name team-slack \
  --kind slack_webhook \
  --endpoint https://hooks.slack.com/services/XXX/YYY/ZZZ \
  --token-env MOSAIC_SLACK_BEARER

mosaic --project-state channels test <slack_channel_id>

Token stays in environment only. Endpoint is stored in channel config.

Step 5: Add Telegram bot channel

export MOSAIC_TELEGRAM_BOT_TOKEN=<your_bot_token>

mosaic --project-state channels add \
  --name team-telegram \
  --kind telegram_bot \
  --chat-id <chat_id> \
  --token-env MOSAIC_TELEGRAM_BOT_TOKEN

mosaic --project-state channels test <telegram_channel_id>
mosaic --project-state channels send <telegram_channel_id> --text "telegram send ok"

Step 6: Update channel defaults and credentials reference

mosaic --project-state channels update <channel_id> --name ops-primary
mosaic --project-state channels update <channel_id> --default-title "Mosaic Alert"
mosaic --project-state channels login <channel_id> --token-env MOSAIC_NEW_TOKEN
mosaic --project-state channels rotate-token-env --all --to MOSAIC_NEW_TOKEN

Step 7: Export/import channel registry

mosaic --project-state channels export --out channels-backup.json
mosaic --project-state channels import --file channels-backup.json --dry-run
mosaic --project-state channels import --file channels-backup.json --replace

Step 8: Cleanup flow

mosaic --project-state channels logout <channel_id>
mosaic --project-state channels remove <channel_id>

Operations acceptance checklist

• channels test succeeds on your primary channel.
• channels send records events with no persistent errors.
• channels status reports healthy channel counts.
• channels logs --summary shows expected success/failed distribution.
• channels logs has expected delivery trail.