Messaging Adapters

fleet-bot communicates through messaging adapters. Each adapter implements the same interface, so commands work identically regardless of which messaging platform you use.

Available adapters

Telegram

The default adapter. Uses the Telegram Bot API with long polling.

Config (/etc/fleet/bot.json):

{
  "adapters": {
    "telegram": {
      "botToken": "123456:ABC-DEF...",
      "allowedSenderIds": [221714512],
      "alertChatIds": [221714512]
    }
  }
}

• botToken — Bot token from @BotFather
• allowedSenderIds — User IDs authorised to issue commands. If you use the bot in a group/channel, this must list the operator’s user ID(s). When empty, the adapter default-denies — only the operator’s private (1:1) chat is accepted and the bot refuses to start on a configured group/channel chat.
• allowedChatIds — Optional chat-level allowlist: chat IDs the bot will listen to. Independent of allowedSenderIds (which gates who may run commands).
• alertChatIds — Where to send automated alerts

The adapter polls for updates and routes messages to the command handler. Outbound messages support text, photos, documents, and inline keyboard buttons.

BlueBubbles (iMessage)

Connects to a BlueBubbles server running on macOS to send and receive iMessages.

Config (key is imessage):

{
  "adapters": {
    "imessage": {
      "serverUrl": "https://bb.example.com",
      "password": "your-api-password",
      "webhookSecret": "a-strong-random-secret",
      "allowedNumbers": ["+447..."],
      "cfAccessClientId": "...",
      "cfAccessClientSecret": "..."
    }
  }
}

• serverUrl — BlueBubbles server URL
• password — API password configured in BlueBubbles
• webhookSecret — Optional dedicated key for verifying inbound webhook signatures. Falls back to password when unset; set a distinct value so a leak of the API password can’t be used to forge inbound webhooks.
• allowedNumbers — Phone numbers authorised to use the bot
• cfAccessClientId / cfAccessClientSecret — Optional Cloudflare Access credentials if the server is behind a Cloudflare tunnel

The adapter registers a webhook with the BlueBubbles server and listens for incoming messages. Each inbound webhook is verified with an HMAC-SHA256 signature (constant-time compared) and rejected if it is a replay or its signed timestamp is outside a 10-minute window. Outbound messages are sent via the BlueBubbles REST API.

Note

BlueBubbles requires a Mac running the BlueBubbles server app. iMessage must be signed in on that Mac.

Running multiple adapters

You can enable both adapters simultaneously. Configure both in bot.json and the bot will start both, routing messages from either platform to the same command handler.

The Adapter interface

Both adapters implement this Go interface:

type Adapter interface {
    Name() string
    Start(ctx context.Context, inbox chan<- InboundMessage) error
    Send(chatID string, msg OutboundMessage) error
    SendAlert(text string) error
    Stop() error
}

See Custom Adapter for how to implement your own.