Channels

Approval and signatures

Every public plugin route is signature-checked. An unsigned plugin route does not exist. A route whose signing secret is missing is refused rather than served unsigned, and an unauthenticated probe sees 404 whether the route is undeclared, pending, or missing a secret.

A guardian has to approve the declaration before the gateway serves it. The approval covers a digest of the declaration: adding a route, changing transport, handshake, verification, or inbound delivery drops the plugin back to pending. Rewording description does not. Editing the file and reinstalling is not enough; the guardian has to approve the new digest. Ask the user to approve pending ingress from the channels settings once the plugin is installed. A plugin must not approve its own ingress.

Third-party verification

A vendor that signs X-Example-Signature has its own scheme. Declare verificationso the gateway runs one HMAC engine and reads the vendor's specifics as data:

{
  "path": "events",
  "kind": "http",
  "description": "Inbound deliveries from Example Courier",
  "verification": {
    "kind": "hmac",
    "algorithm": "sha256",
    "secret": { "field": "courier_webhook_secret" },
    "signature": {
      "header": "X-Example-Signature",
      "encoding": "hex",
      "prefix": "sha256="
    },
    "payload": ["body"],
    "freshness": {
      "header": "X-Example-Timestamp",
      "format": "unix-seconds",
      "toleranceSeconds": 300
    }
  }
}

• The credential serviceis the plugin's directory name. The descriptor names only a field. A manifest cannot point a route at another plugin's secret or at the platform's.
• Store the secret via assistant credentials prompt (or storeCredential from a hook, tool, or route). Never put it in the file.
• payload is the exact bytes the vendor signs, in order: "body", { "header": "..." }, or { "literal": "..." }. A header named in payload but absent from the request fails verification rather than contributing an empty string.
• freshness is a replay window. Declare it when the vendor binds a timestamp. A signature over the body alone stays valid for as long as the secret does.
• Unrecognized fields fail the declaration rather than guessing a scheme.

Delivering inbound messages

Absent inbound, the route is a webhook and nothing more: the gateway forwards the delivery, returns whatever the plugin answered, and the message goes no further.

Present, the plugin's replyis normalized and run through the gateway's inbound pipeline (admission floor, trust verdict, verification and invite intercepts), exactly as a built-in channel's would be. The plugin parses the vendor payload. The declaration tells the gateway where the sender and the conversation sit so the gate can run before anything is forwarded.

A plugin that returns the default envelope declares "inbound": {} and nothing more. The matching route handler replies with:

{
  "message": {
    "content": "hello",
    "conversationExternalId": "chat-123",
    "externalMessageId": "msg-123"
  },
  "actor": {
    "actorExternalId": "+12025550142",
    "displayName": "Alice"
  },
  "source": { "chatType": "dm" }
}

A reply with no sender and no conversation is a plain acknowledgement (delivery receipt, vendor probe). Naming some of those fields and not the rest is invalid and is logged rather than quietly dropped. Override field locations when the vendor's payload is not that shape. Paths are dotted identifiers (message.body), not JSONPath. from may list several paths (first non-empty wins). map / default turn a vendor vocabulary into ours. identity is opaque (default), phone, or email: it decides whether +1 (202) 555-0142 and +12025550142 are the same person. Leave it opaque unless the sender id really is a phone number or email.

The plugin does not get to name the channel (the gateway stamps plugin) or the external-id namespace (every id is prefixed with the plugin's directory name). A plugin cannot inherit Slack's admission floor or another plugin's contacts.

Presentation

The channels list reads the plugin's package.json, not the ingress file. Optional displayName, description, and icon (a Lucide name without the lucide- prefix) do not gate load. A plugin with ingress and a bare package.json still appears, titled from its directory. A plugin whose directory name is already a built-in channel (slack, telegram, …) is skipped so it cannot impersonate one.

Disabled plugins contribute no channel.

Anatomy of a channel

example-courier/
├── package.json
├── channels/
│   └── ingress.json
└── routes/
    └── events.ts

{
  "routes": [
    {
      "path": "events",
      "kind": "http",
      "description": "Inbound events from Example Courier",
      "inbound": {}
    }
  ]
}

// routes/events.ts
export async function POST(request: Request): Promise<Response> {
  const delivery = await request.json();
  return Response.json({
    message: {
      content: delivery.text ?? "",
      conversationExternalId: delivery.chatId,
      externalMessageId: delivery.messageId,
    },
    actor: {
      actorExternalId: delivery.from,
      displayName: delivery.fromName,
    },
  });
}

When should my assistant write a Channel?

Reach for channels/ingress.json when a third party must deliver to the assistant from outside: a vendor webhook, a realtime socket a third party dials, or a channel that should appear next to Slack and Telegram. Use a route alone when the caller is already inside the assistant (an app frontend, a local tool, another plugin). After install, hand the vendor await resolveWebhookUrl({ path: "events" }) and ask the guardian to approve the pending ingress from channels settings.