plugin.yaml

name: sendblue-platform
label: iMessage via Sendblue
kind: platform
version: 0.9.0
description: >
  Sendblue iMessage/SMS/RCS gateway adapter for Hermes Agent. Runs a
  self-hosted aiohttp webhook server (signature verification, 1 MiB body
  cap, dedup ring) and relays messages between iMessage chats and the
  Hermes agent through the Sendblue API. Supports media send/receive
  (image, voice, video, document), group chats, iMessage send styles,
  typing indicators, read receipts, tapback reactions, a /quota usage
  intercept, an opt-in polling fallback, and a daily send cap.
author: beardthelion
# ``requires_env`` / ``optional_env`` entries drive the ``hermes gateway
# setup`` wizard (this plugin's setup_fn). They also surface in the ``hermes
# config`` UI only when the plugin is bundled upstream under
# ``<repo>/plugins/platforms``; a user install under ``~/.hermes/plugins`` is
# configured through the wizard, not that injector.
requires_env:
  - name: SENDBLUE_API_KEY_ID
    description: "Sendblue API key ID (Sendblue dashboard > API Keys)"
    prompt: "Sendblue API key ID"
    url: "https://sendblue.com/"
    # Sendblue's GET endpoints authenticate on the key ID alone, so treat it
    # as secret-bearing and mask it in prompts.
    password: true
  - name: SENDBLUE_API_SECRET
    description: "Sendblue API secret paired with the key ID"
    prompt: "Sendblue API secret"
    url: "https://sendblue.com/"
    password: true
optional_env:
  - name: SENDBLUE_NUMBER
    description: "The Sendblue-provisioned sending number in E.164 form (e.g. +15551234567)"
    prompt: "Sendblue number (E.164)"
    password: false
  - name: SENDBLUE_WEBHOOK_PUBLIC_URL
    description: "Public HTTPS URL Sendblue posts inbound messages to (e.g. a Tailscale Funnel URL ending in the webhook path)"
    prompt: "Public webhook URL"
    password: false
  - name: SENDBLUE_WEBHOOK_SECRET
    description: "Shared signing secret for inbound webhook verification (sb-signing-secret header). Leave unset only if you accept unsigned webhooks."
    prompt: "Webhook signing secret"
    password: true
  - name: SENDBLUE_WEBHOOK_HOST
    description: "Webhook bind host (default: 127.0.0.1; set 0.0.0.0 when the reverse proxy or tunnel terminates on another host)"
    prompt: "Webhook host"
    password: false
  - name: SENDBLUE_WEBHOOK_PORT
    description: "Webhook listen port (default: 8665)"
    prompt: "Webhook port"
    password: false
  - name: SENDBLUE_WEBHOOK_PATH
    description: "Webhook receive path (default: /sendblue-gateway/receive)"
    prompt: "Webhook path"
    password: false
  - name: SENDBLUE_ALLOWED_USERS
    description: "Comma-separated E.164 numbers allowed to message the agent"
    prompt: "Allowed numbers (comma-separated)"
    password: false
  - name: SENDBLUE_ALLOW_ALL_USERS
    description: "Allow any sender to talk to the agent (dev only — disables the allowlist)"
    prompt: "Allow all users? (true/false)"
    password: false
  - name: SENDBLUE_HOME_CHANNEL
    description: "Default chat (E.164 number or group ID) for cron / notification delivery"
    prompt: "Home channel (or empty)"
    password: false
  - name: SENDBLUE_HOME_CHANNEL_NAME
    description: "Display name for the home channel (default: Home)"
    prompt: "Home channel name (or empty)"
    password: false
  - name: SENDBLUE_HOME_CHANNEL_THREAD_ID
    description: "Optional thread ID for home-channel delivery"
    prompt: "Home channel thread ID (or empty)"
    password: false
  - name: SENDBLUE_SEND_READ_RECEIPTS
    description: "Mark inbound messages read / send read receipts (true/false, default true)"
    prompt: "Send read receipts?"
    password: false
  - name: SENDBLUE_DEFAULT_SEND_STYLE
    description: "Default iMessage send style (e.g. invisible, gentle, loud, slam)"
    prompt: "Default send style (or empty)"
    password: false
  - name: SENDBLUE_MULTI_BUBBLE_SPLIT
    description: "Split long replies into multiple message bubbles (true/false)"
    prompt: "Multi-bubble split?"
    password: false
  - name: SENDBLUE_DAILY_CAP
    description: "Daily outbound message cap (0 = unlimited)"
    prompt: "Daily send cap"
    password: false
  - name: SENDBLUE_STATUS_CALLBACK_URL
    description: "Optional status callback URL passed to Sendblue on sends"
    prompt: "Status callback URL (or empty)"
    password: false
  - name: SENDBLUE_POLLING_ENABLED
    description: "Enable the polling fallback that catches webhook-missed messages (true/false, default false)"
    prompt: "Enable polling fallback?"
    password: false
  - name: SENDBLUE_POLLING_INTERVAL_SECONDS
    description: "Polling interval in seconds when polling is enabled (default 60, floored at 10)"
    prompt: "Polling interval seconds"
    password: false
  - name: SENDBLUE_POLLING_LOOKBACK_SECONDS
    description: "How far back each poll looks for missed messages (default 300, floored at 60)"
    prompt: "Polling lookback seconds"
    password: false