@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/docs/guides/channel-security.md

@@ -2,48 +2,44 @@
 
 ## Goal
 
-Keep channel webhooks, delivery logs, provider sends, and managed secrets safe by default.
+Configure website, Telegram, WhatsApp, Discord, Slack, and generic webhook channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
 
 ## When To Use It
 
-Use this before adding a channel provider, changing webhook validation, adding delivery logging, or enabling real-provider smoke tests.
+Use this when a coding agent adds or changes channels in an Agent Capsule, enables audio transcription, inspects deliveries, or prepares a hosted deploy that receives provider webhooks.
 
 ## Commands
 
 ```sh
 agentkit inspect
 agentkit channels status <name>
+agentkit channels doctor <name>
+agentkit channels deliveries list <name> --since 24h
 agentkit channels deliveries show <delivery-id>
-bun test packages/agentkit/src/runtime/channels/adapters.test.ts
-bun test packages/agentkit/src/runtime/deploy.test.ts
 ```
 
-Real-provider gates are opt-in:
-
-```sh
-AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
-AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
-```
-
-Telegram smoke also requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
-
-Zapster smoke also requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
-
 ## Files Created Or Edited
 
-- `agentkit.config.ts`: secret names only.
-- Managed hosted secrets: production secret values, no readback.
-- Delivery records: hashes, statuses, provider event IDs, redacted metadata.
+- `agentkit.config.ts`: channel names, provider choices, audio/buffer config, and secret names only.
+- `.env.schema`: local secret names only when the capsule needs a local provider or local smoke.
+- `.env`: local-only secret values; do not commit it.
+- Hosted managed secrets: production secret values with no readback.
 
 ## Safety Rules
 
 - Public webhook URLs are not permission grants.
-- Validate provider authenticity when the provider supports it.
-- Do not store channel plumbing in the user's Turso database.
-- Do not store raw webhook bodies in delivery records; store a SHA-256 hash.
-- Redact bearer tokens, bot tokens, signing secrets, provider API tokens, and phone numbers.
-- Inject only channel-declared secrets into adapter code.
-- Prefer acknowledging Telegram/WhatsApp over retry storms when a channel-level limit is exceeded.
+- Keep provider tokens, webhook secrets, bot tokens, transcription keys, and bearer tokens out of source files.
+- Put secret names in `agentkit.config.ts`; put local values in ignored `.env`; upload production values with `agentkit secret set` or `agentkit secret sync`.
+- Do not store raw webhook bodies, raw audio, or provider secret values in tools, prompts, evals, fixtures, or delivery notes.
+- Do not expose Discord interaction tokens or bot tokens. Interaction tokens are reply tokens, not public identifiers.
+- Do not expose Slack bot tokens or signing secrets. Slack signing secrets authenticate webhook origin; Slack bot tokens authorize outbound replies.
+- Do not expose `AGENTKIT_WEBHOOK_SECRET`. Generic webhook clients must authenticate with bearer/header token auth or an HMAC signature over the exact raw body.
+- Do not remove `EVOLUTION_WEBHOOK_TOKEN` from Evolution WhatsApp webhooks. Evolution provider docs expose webhook delivery setup but no webhook signing-secret contract, so AgentKit requires a secret token query parameter and rejects requests without it.
+- Keep `EVOLUTION_API_BASE_URL` on a public HTTPS origin. AgentKit rejects localhost, private network, link-local, and metadata-service hosts for Evolution outbound and media-download requests.
+- Inspect delivery IDs, hashes, redacted metadata, and statuses instead of raw provider payloads.
+- Keep channel plumbing out of the agent's application database. The user's Turso tables are for the agent's business data.
+- Enable audio transcription only when the capsule declares a transcription provider and bounded `limits`.
+- Keep channel buffer limits bounded so bursty client messages cannot create unbounded runs or provider spend.
 
 ## Minimal Working Example
 
@@ -54,28 +50,128 @@ telegramChannel({
 });
 ```
 
-The config contains secret names only. Hosted responses report:
+With audio transcription:
+
+```ts
+export default defineAgent({
+  // ...
+  transcription: {
+    provider: "groq",
+    model: "whisper-large-v3-turbo",
+    secret: "GROQ_API_KEY",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    telegramChannel({
+      name: "support-telegram",
+      audio: { mode: "transcribe" },
+    }),
+  ],
+});
+```
+
+The config contains secret names only. Hosted responses report status, not values:
 
 ```txt
 TELEGRAM_BOT_TOKEN: set
 TELEGRAM_WEBHOOK_SECRET: missing
+GROQ_API_KEY: set
+```
+
+Discord slash-command mode uses a public key rather than a shared webhook secret:
+
+```ts
+discordChannel({
+  name: "support-discord",
+  secrets: ["DISCORD_PUBLIC_KEY"],
+});
+```
+
+AgentKit validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against the raw body, returns `type: 1` for Discord `PING`, and sends follow-up replies with `allowed_mentions: { parse: [] }`.
+
+Discord bot mode uses a bot token and Gateway connection:
+
+```ts
+discordChannel({
+  name: "server-discord",
+  mode: "bot",
+  secrets: ["DISCORD_BOT_TOKEN"],
+});
 ```
 
+Bot mode requires Message Content Intent in the Discord Developer Portal and channel permissions for `View Channel`, `Read Message History`, and `Send Messages`. AgentKit must redact `DISCORD_BOT_TOKEN` anywhere delivery, queue, buffer, or doctor output is returned.
+
+Slack Events API uses a bot token and signing secret:
+
+```ts
+slackChannel({
+  name: "support-slack",
+  secrets: ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"],
+});
+```
+
+AgentKit validates `X-Slack-Signature` and `X-Slack-Request-Timestamp` against the raw body, rejects stale timestamps, answers Slack `url_verification` with the literal challenge, skips bot/subtype messages, and sends replies with Slack control mentions escaped.
+
+Generic webhooks use an AgentKit shared secret:
+
+```ts
+webhookChannel({
+  name: "n8n-webhook",
+  secrets: ["AGENTKIT_WEBHOOK_SECRET"],
+});
+```
+
+AgentKit validates `Authorization: Bearer <secret>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature` against the raw body before parsing business fields. Payloads must include `event_id` for replay protection. `external_id` is hashed before storage.
+
+Evolution WhatsApp uses a self-hosted API key and an AgentKit webhook token:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "evolution",
+  secrets: [
+    "EVOLUTION_API_BASE_URL",
+    "EVOLUTION_API_KEY",
+    "EVOLUTION_INSTANCE_NAME",
+    "EVOLUTION_WEBHOOK_TOKEN",
+  ],
+});
+```
+
+AgentKit configures Evolution's webhook URL with `?token=<EVOLUTION_WEBHOOK_TOKEN>`, validates the token on ingress, redacts Evolution secret values, and rejects unsafe Evolution API base URLs before sending messages or downloading audio media.
+
 ## Verification
 
 ```sh
-bun test packages/agentkit/src/runtime/channels/adapters.test.ts
-bun test packages/agentkit/src/runtime/deploy.test.ts
-npm run typecheck
+npm run agentkit -- inspect
+npm run agentkit -- deploy doctor
+npm run agentkit -- channels status <name>
+npm run agentkit -- channels doctor <name>
+```
+
+For a synthetic channel smoke after deploy:
+
+```sh
+npm run agentkit -- channels test <name> --message "hello"
+npm run agentkit -- channels deliveries list <name> --since 1h
 ```
 
 ## Troubleshooting
 
 Secret value appears in output:
-Stop and add a regression test before changing behavior. Delivery APIs must never return secret values.
+Stop and remove the value from source, fixtures, prompts, evals, and delivery notes. Hosted delivery APIs must not return secret values.
 
 Phone number appears in delivery logs:
-Redact it to a stable partial form such as `5511******9999`.
+Use the redacted delivery metadata and avoid pasting full phone numbers into committed fixtures.
+
+`channel_secret_missing`:
+Set the named hosted secret with `agentkit secret set <NAME> --from-local-env` or `agentkit secret sync --from-local`.
+
+`channel_signature_invalid`:
+Check that the provider webhook secret/token configured in the provider dashboard matches the hosted secret name declared by the channel. For Discord slash-command mode, check that `DISCORD_PUBLIC_KEY` matches the application's public key. For Discord bot mode, check that `DISCORD_BOT_TOKEN` is set and Message Content Intent is enabled.
 
-Webhook accepts invalid signatures:
-Fix `verifyWebhook` for the adapter before enabling provider setup docs.
+Raw audio appears in files or logs:
+Remove it. AgentKit may pass transcript text into the normalized agent message after successful transcription, but raw audio belongs outside committed capsule files.

package/docs/guides/connect-discord.md

@@ -0,0 +1,178 @@
+# Connect Discord
+
+## Goal
+
+Connect Discord to a hosted AgentKit channel. Discord has two supported modes:
+
+- `interactions`: slash commands through Discord's Interactions Endpoint URL.
+- `bot`: normal server messages through a Discord Bot user connected to the Gateway.
+
+Use `bot` mode when the agent should answer messages without a slash command.
+
+## Commands
+
+Slash-command mode:
+
+```sh
+agentkit deploy
+agentkit secret set DISCORD_PUBLIC_KEY --stdin
+agentkit channels connect discord support-discord
+agentkit channels test support-discord --message "hello"
+agentkit channels deliveries list support-discord
+```
+
+Bot/server-message mode:
+
+```sh
+agentkit deploy
+agentkit secret set DISCORD_BOT_TOKEN --stdin
+agentkit channels connect discord server-discord --mode bot
+agentkit channels test server-discord --message "hello"
+agentkit channels deliveries list server-discord
+```
+
+## Minimal Config
+
+Slash commands:
+
+```ts
+discordChannel({ name: "support-discord" })
+```
+
+Normal server messages:
+
+```ts
+discordChannel({
+  name: "server-discord",
+  mode: "bot",
+})
+```
+
+Full example:
+
+```ts
+import { defineAgent, discordChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [
+    discordChannel({
+      name: "server-discord",
+      mode: "bot",
+      buffer: {
+        mode: "debounce",
+        quietWindowMs: 1500,
+        maxWaitMs: 8000,
+        maxMessages: 20,
+        maxChars: 8000,
+      },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Discord audio transcription is not supported in V1. Do not add `audio` to a Discord channel.
+
+## Slash Command Setup
+
+Use this when users should run `/ask message:<text>`.
+
+Required secret:
+
+```txt
+DISCORD_PUBLIC_KEY
+```
+
+`agentkit channels connect discord support-discord` creates or refreshes the hosted channel, validates the public key, runs an AgentKit synthetic smoke, and prints the human setup step.
+
+Expected webhook URL:
+
+```txt
+https://<deploy-host>/channels/support-discord/discord/discord/webhook
+```
+
+In the Discord Developer Portal:
+
+1. Open the application.
+2. Copy the application's public key into the hosted secret named `DISCORD_PUBLIC_KEY`.
+3. Paste the AgentKit webhook URL into `Interactions Endpoint URL`.
+4. Register a slash command with a string option named `message`, `text`, `prompt`, `question`, `query`, or `input`.
+
+AgentKit answers Discord's `PING` handshake with `{ "type": 1 }`. Normal command webhooks are acknowledged with a deferred response and the retryable channel worker sends the final answer as an interaction follow-up.
+
+## Bot Setup
+
+Use this when the agent should behave like a server member and answer normal messages.
+
+Required secret:
+
+```txt
+DISCORD_BOT_TOKEN
+```
+
+`agentkit channels connect discord server-discord --mode bot` creates or refreshes the hosted channel, validates the bot token secret is present, runs an AgentKit synthetic Gateway smoke, and prints the human setup step.
+
+In the Discord Developer Portal:
+
+1. Create or open the Discord application.
+2. Open the Bot page.
+3. Reset/copy the bot token and save it as hosted secret `DISCORD_BOT_TOKEN`.
+4. Enable Message Content Intent on the Bot page.
+5. Install the app into the server with bot permissions.
+6. Grant the bot `View Channel`, `Read Message History`, and `Send Messages` in the channels it should answer.
+
+Hosted AgentKit runs a Discord Gateway worker for bot-mode channels. Discord sends `MESSAGE_CREATE` events, AgentKit ignores messages authored by bots, maps each human message to a channel conversation, runs the agent, and replies in the same Discord channel with `allowed_mentions: { parse: [] }`.
+
+For server hygiene, install or grant the bot only in channels where it should answer. Bot mode processes every readable non-bot text message the Gateway sends for that bot.
+
+## Safety Rules
+
+- Keep `DISCORD_PUBLIC_KEY` and `DISCORD_BOT_TOKEN` as managed hosted secrets; do not put values in prompts, fixtures, or source files.
+- Discord interaction tokens and bot tokens must never appear in delivery, queue, buffer, or doctor API responses.
+- Slash-command validation uses `X-Signature-Ed25519` and `X-Signature-Timestamp` against the exact raw request body.
+- Bot mode requires Discord Message Content Intent; without it, Discord sends empty message content and AgentKit skips the event.
+- Outbound Discord sends use `allowed_mentions: { parse: [] }` so agent text cannot accidentally ping users or roles.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Discord should not receive a real reply. Dry-run deliveries are recorded as `adapter_stubbed`.
+
+## Verification
+
+```sh
+agentkit channels status server-discord
+agentkit channels test server-discord --message "hello"
+agentkit channels deliveries list server-discord
+agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list server-discord
+```
+
+Expected bot-mode flow:
+
+1. A user sends a normal message in a Discord server channel where the bot has access.
+2. Discord sends `MESSAGE_CREATE` over the Gateway.
+3. AgentKit records an inbound delivery and enqueues the channel job.
+4. The channel queue runs the agent.
+5. AgentKit sends a bot message through `/channels/<channel_id>/messages`.
+6. Delivery status becomes `provider_sent` for a real provider send or `adapter_stubbed` in dry-run mode.
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `DISCORD_PUBLIC_KEY` for slash-command mode or `DISCORD_BOT_TOKEN` for bot mode as a hosted managed secret.
+
+Bot does not answer normal messages:
+Confirm the channel was created with `--mode bot`, `DISCORD_BOT_TOKEN` is set, Message Content Intent is enabled in the Discord Developer Portal, and the bot has channel permissions to view, read history, and send messages.
+
+Bot answers nothing and delivery events show empty content:
+Discord Message Content Intent is missing, disabled, or not approved for the application.
+
+Discord Developer Portal rejects the slash-command endpoint:
+Confirm the deployed interaction channel is online, `DISCORD_PUBLIC_KEY` matches the application's public key, and the endpoint returns `{ "type": 1 }` for Discord's signed `PING` request.
+
+No answer appears after a queued delivery:
+Run `agentkit channels deliveries list <name>`, inspect the inbound delivery, and drain/check the channel queue.

package/docs/guides/connect-slack.md

@@ -0,0 +1,126 @@
+# Connect Slack
+
+## Goal
+
+Connect Slack to a hosted AgentKit channel through Slack Events API.
+
+V1 supports:
+
+- `app_mention` events in channels.
+- `message.im` direct messages.
+- Replies through `chat.postMessage`.
+
+Slack Socket Mode, file events, audio transcription, app-management automation, and all-channel message listening are not supported in V1.
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit secret set SLACK_BOT_TOKEN --stdin
+agentkit secret set SLACK_SIGNING_SECRET --stdin
+agentkit channels connect slack support-slack
+agentkit channels test support-slack --message "hello"
+agentkit channels deliveries list support-slack
+```
+
+## Minimal Config
+
+```ts
+import { defineAgent, slackChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [slackChannel({ name: "support-slack" })],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+## Slack App Setup
+
+Required hosted secrets:
+
+```txt
+SLACK_BOT_TOKEN
+SLACK_SIGNING_SECRET
+```
+
+Expected webhook URL:
+
+```txt
+https://<deploy-host>/channels/support-slack/slack/slack/webhook
+```
+
+In Slack app configuration:
+
+1. Open **Basic Information** and copy the Signing Secret into hosted secret `SLACK_SIGNING_SECRET`.
+2. Open **OAuth & Permissions** and add bot scopes:
+   - `app_mentions:read`
+   - `im:history`
+   - `chat:write`
+3. Install or reinstall the app to the workspace.
+4. Copy the Bot User OAuth Token into hosted secret `SLACK_BOT_TOKEN`.
+5. Open **Event Subscriptions**.
+6. Enable events and paste the AgentKit webhook URL as the Request URL.
+7. Subscribe to bot events:
+   - `app_mention`
+   - `message.im`
+
+AgentKit answers Slack `url_verification` challenges with the literal challenge string after signature validation.
+
+## Runtime Behavior
+
+Slack signs each request with `X-Slack-Signature` and `X-Slack-Request-Timestamp`. AgentKit verifies the signature against the raw body and rejects stale timestamps before normalizing events.
+
+For channel mentions, AgentKit maps the conversation to the Slack thread and replies in that thread. For direct messages, AgentKit maps the conversation to the Slack DM channel and user.
+
+AgentKit skips Slack bot/subtype messages to avoid reply loops. Outbound Slack delivery uses `chat.postMessage` with `parse: "none"`, disabled link-name expansion, disabled unfurls, and escaped Slack control mentions.
+
+## Safety Rules
+
+- Keep `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` as managed hosted secrets; do not put values in prompts, fixtures, evals, or source files.
+- Do not configure `audio` on `slackChannel`; Slack audio is not supported in V1.
+- Keep bot scopes narrow. V1 does not require broad channel-history scopes for all-channel listening.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Slack should not receive a real reply.
+- Delivery logs return hashes and redacted metadata, never raw Slack request bodies or token values.
+
+## Verification
+
+```sh
+agentkit channels status support-slack
+agentkit channels test support-slack --message "hello"
+agentkit channels deliveries list support-slack
+agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list support-slack
+```
+
+Expected flow:
+
+1. A user mentions the Slack app or sends it a direct message.
+2. Slack sends a signed Events API request.
+3. AgentKit records an inbound delivery and enqueues the channel job.
+4. The channel queue runs the agent.
+5. AgentKit sends a Slack reply through `chat.postMessage`.
+6. Delivery status becomes `provider_sent` for a real provider send or `adapter_stubbed` in dry-run mode.
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` as hosted managed secrets.
+
+Slack rejects the Request URL:
+Confirm the deployed channel is online, `SLACK_SIGNING_SECRET` matches the Slack app, and the endpoint can answer Slack's signed `url_verification` challenge.
+
+No channel mention arrives:
+Confirm Event Subscriptions includes `app_mention`, the app is installed in the workspace, and the app has access to the channel where it is mentioned.
+
+No direct message arrives:
+Confirm Event Subscriptions includes `message.im` and the app has `im:history`.
+
+No answer appears after a queued delivery:
+Run `agentkit channels deliveries list support-slack`, inspect the inbound delivery, and drain/check the channel queue.

package/docs/guides/connect-telegram.md

@@ -27,6 +27,12 @@ TELEGRAM_BOT_TOKEN
 TELEGRAM_WEBHOOK_SECRET
 ```
 
+If Telegram audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually:
+
+```txt
+GROQ_API_KEY
+```
+
 ## Files Created Or Edited
 
 - `agentkit.config.ts`: `telegramChannel({ name: "support-telegram" })`.
@@ -51,6 +57,67 @@ export default defineAgent({
 });
 ```
 
+To answer once after a burst of Telegram messages, enable channel buffering:
+
+```ts
+telegramChannel({
+  name: "support-telegram",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+## Auto Transcribe Telegram Audio
+
+Telegram voice notes arrive as OGG/Opus. In V1, use Groq for the most obvious Telegram voice-note path because the AgentKit Groq adapter accepts `audio/ogg`.
+
+```ts
+import { defineAgent, telegramChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "openai", model: "gpt-5.4-mini" },
+  instructions: "./prompts/instructions.md",
+  transcription: {
+    provider: "groq",
+    model: "whisper-large-v3-turbo",
+    secret: "GROQ_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    telegramChannel({
+      name: "support-telegram",
+      audio: {
+        mode: "transcribe",
+      },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Processing order:
+
+1. AgentKit validates `X-Telegram-Bot-Api-Secret-Token`.
+2. Telegram `voice` or `audio` payloads become normalized audio messages.
+3. AgentKit records `audio_received` and enqueues a channel job before acknowledging Telegram.
+4. The retryable channel worker calls Telegram `getFile`, downloads the file with `TELEGRAM_BOT_TOKEN`, and does not log the token.
+5. AgentKit sends the audio bytes to the configured transcription provider using the user's managed secret.
+6. The agent run receives a text message with the transcript.
+
+OpenAI transcription can be used for Telegram files that arrive as MP3, MP4, MPEG, MPGA, M4A, WAV, or WEBM. Telegram voice notes are usually OGG/Opus, so they should use Groq in V1 unless the provider payload is converted before it reaches AgentKit.
+
 ## Setup Behavior
 
 `agentkit channels setup support-telegram` is read-only and prints the webhook URL.
@@ -61,6 +128,8 @@ export default defineAgent({
 - `secret_token`: `TELEGRAM_WEBHOOK_SECRET`;
 - `allowed_updates`: `["message"]`.
 
+Against AgentKit Cloud, `--apply` runs through the Cloud API and uses managed hosted secrets. The legacy local fallback only uses `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET` from the shell when the Cloud API does not expose channel setup.
+
 ## Safety Rules
 
 - Use `--apply` only when real Telegram secrets are present.
@@ -72,13 +141,15 @@ export default defineAgent({
 ```sh
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
+agentkit channels test-audio support-telegram --fixture voice-note
+agentkit transcribe smoke --provider groq
 agentkit channels deliveries show <delivery-id>
 ```
 
 Expected webhook URL shape:
 
 ```txt
-https://<deploy-host>/channels/chn_<id>/telegram/webhook
+https://<deploy-host>/channels/support-telegram/telegram/telegram/webhook
 ```
 
 ## Troubleshooting
@@ -91,3 +162,9 @@ The incoming Telegram secret token does not match `TELEGRAM_WEBHOOK_SECRET`.
 
 `channel_payload_invalid`:
 The update is malformed or is not a supported private text message.
+
+`transcription_secret_missing`:
+Set `GROQ_API_KEY` or the custom secret named in `transcription.secret` as a managed hosted secret.
+
+`transcription_audio_format_unsupported`:
+The configured transcription provider does not accept the Telegram file format. Use Groq for OGG/Opus voice notes in V1. `agentkit inspect` warns when a Telegram channel uses `audio.mode: "transcribe"` with OpenAI transcription.