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

package/README.md

@@ -67,6 +67,7 @@ agentkit secret set OPENAI_API_KEY --from-local-env
 agentkit deploy
 agentkit deploy status
 agentkit channels test support-telegram --message "hello"
+agentkit channels connect webhook n8n-webhook
 agentkit transcribe smoke --provider groq
 agentkit chat-ui --deploy
 ```

package/docs/guides/add-channel.md

@@ -6,7 +6,7 @@ Add a hosted messaging channel to an Agent Capsule, create the hosted channel re
 
 ## When To Use It
 
-Use this when the agent should receive messages from website chat, Telegram, WhatsApp, or Discord through AgentKit-owned channel infrastructure.
+Use this when the agent should receive messages from website chat, Telegram, WhatsApp, Discord, Slack, or a generic webhook through AgentKit-owned channel infrastructure.
 
 ## Commands
 
@@ -19,7 +19,10 @@ agentkit channels add telegram support-telegram
 agentkit channels connect discord support-discord
 agentkit channels connect discord server-discord --mode bot
 agentkit channels connect slack support-slack
+agentkit channels connect webhook n8n-webhook
 agentkit channels add whatsapp support-whatsapp --provider zapster
+agentkit channels connect whatsapp support-uazapi --provider uazapi
+agentkit channels connect whatsapp main-whatsapp --provider evolution
 agentkit channels setup support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
@@ -31,15 +34,16 @@ Use `--api <url>` only when the owner gives you a non-default AgentKit Cloud API
 
 ## Files Created Or Edited
 
-- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, `whatsappChannel`, `discordChannel`, or `slackChannel`.
+- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, `whatsappChannel`, `discordChannel`, `slackChannel`, or `webhookChannel`.
 - `.agentkit/deploy.json`: written by `agentkit deploy`; used by `agentkit channels ...`.
 - No user Turso tables: AgentKit owns channel resources, dedupe, identities, queue state, and delivery logs.
 - Website channel clients must send `AGENTKIT_WEBSITE_CHANNEL_TOKEN` as `Authorization: Bearer <token>` or `X-AgentKit-Channel-Token`.
+- Generic webhook clients must send `AGENTKIT_WEBHOOK_SECRET` as `Authorization: Bearer <token>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>`.
 
 ## Minimal Working Example
 
 ```ts
-import { defineAgent, discordChannel, slackChannel, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -52,9 +56,12 @@ export default defineAgent({
     websiteChannel({ name: "website-chat" }),
     telegramChannel({ name: "support-telegram" }),
     whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
+    whatsappChannel({ name: "support-uazapi", provider: "uazapi" }),
+    whatsappChannel({ name: "main-whatsapp", provider: "evolution" }),
     discordChannel({ name: "support-discord" }),
     discordChannel({ name: "server-discord", mode: "bot" }),
     slackChannel({ name: "support-slack" }),
+    webhookChannel({ name: "n8n-webhook" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -95,6 +102,57 @@ agentkit channels buffers retry support-whatsapp <conversation-id>
 
 Discord supports buffering for slash-command interactions and bot-mode server messages, but it does not support `audio` in V1.
 
+## Generic Webhooks
+
+Use `webhookChannel` when n8n, Make, Zapier, Pipedream, or a custom server should push a text event into the agent.
+
+```ts
+webhookChannel({
+  name: "n8n-webhook",
+})
+```
+
+After deploy:
+
+```sh
+agentkit channels connect webhook n8n-webhook
+```
+
+The hosted webhook URL is:
+
+```txt
+https://<deploy-host>/channels/n8n-webhook/webhook
+```
+
+Send canonical JSON:
+
+```json
+{
+  "event_id": "evt_123",
+  "external_id": "customer_123",
+  "message": "hello from n8n"
+}
+```
+
+`event_id` is required for replay protection. `external_id` is optional but recommended; AgentKit hashes it before storing the channel identity and uses it to continue the same conversation. If `external_id` is omitted, the event id becomes the conversation identity and each event is treated as its own conversation.
+
+Authenticate with a shared secret:
+
+```sh
+curl -X POST https://<deploy-host>/channels/n8n-webhook/webhook \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer <AGENTKIT_WEBHOOK_SECRET>' \
+  -d '{"event_id":"evt_123","external_id":"customer_123","message":"hello from n8n"}'
+```
+
+For HMAC auth, compute `HMAC-SHA256(raw JSON body, AGENTKIT_WEBHOOK_SECRET)` and send:
+
+```txt
+X-AgentKit-Webhook-Signature: sha256=<hex digest>
+```
+
+Generic webhooks are inbound-only in V1. The agent run is queued and delivery logs show the result; AgentKit does not call back into n8n unless the agent has a separate tool that does so.
+
 ## Auto Transcribe Audio
 
 Use `transcription` at the agent level and `audio.mode: "transcribe"` on each Telegram or WhatsApp channel that should accept voice notes or audio files.
@@ -125,6 +183,16 @@ export default defineAgent({
       provider: "zapster",
       audio: { mode: "transcribe" },
     }),
+    whatsappChannel({
+      name: "support-uazapi",
+      provider: "uazapi",
+      audio: { mode: "transcribe" },
+    }),
+    whatsappChannel({
+      name: "main-whatsapp",
+      provider: "evolution",
+      audio: { mode: "transcribe" },
+    }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -149,6 +217,8 @@ Processing order:
 5. The transcription adapter sends the file to the configured transcription provider.
 6. The agent receives a text message containing the transcript.
 
+Zapster audio downloads from trusted HTTPS Zapster media URLs. UAZAPI audio downloads through UAZAPI `/message/download` with base64 return enabled. Evolution audio downloads through Evolution API `/chat/getBase64FromMediaMessage/{instance}` with base64 return enabled. AgentKit does not fetch arbitrary UAZAPI or Evolution webhook media hosts.
+
 V1 keeps the raw audio in memory for the request path and delivery metadata only records redacted status/error fields. `rawAudioTtlSeconds` is part of the manifest contract for future object-storage retention, but V1 does not persist raw audio by default.
 
 ## Safety Rules
@@ -167,6 +237,7 @@ npm run typecheck
 bun test
 agentkit inspect
 agentkit channels list
+agentkit channels test n8n-webhook --message "hello"
 agentkit channels test support-telegram --message "hello"
 agentkit channels test-audio support-telegram --fixture voice-note
 agentkit transcribe smoke --provider groq
@@ -175,7 +246,7 @@ agentkit channels buffers list support-telegram
 ```
 
 Expected hosted status includes `NAME`, `TYPE`, `PROVIDER`, `STATUS`, and `LAST_EVENT`. Secret output is name plus `set` or `missing`, never the value.
-Outbound provider success is `provider_sent`. Explicit dry-run mode is `adapter_stubbed`, which means the provider was not called.
+Outbound provider success is `provider_sent`. `adapter_stubbed` means no outbound provider call was made, either because explicit dry-run mode is enabled or the channel is inbound-only.
 
 ## Troubleshooting
 

package/docs/guides/channel-security.md

@@ -2,7 +2,7 @@
 
 ## Goal
 
-Configure website, Telegram, WhatsApp, Discord, and Slack channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
+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
 
@@ -33,6 +33,9 @@ agentkit channels deliveries show <delivery-id>
 - 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`.
@@ -112,6 +115,34 @@ slackChannel({
 
 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

package/docs/guides/connect-whatsapp-evolution.md

@@ -0,0 +1,121 @@
+# Connect WhatsApp Through Evolution API
+
+## Goal
+
+Connect a self-hosted Evolution API WhatsApp instance to a hosted AgentKit WhatsApp channel.
+
+## When To Use It
+
+Use this after `whatsappChannel({ name: "main-whatsapp", provider: "evolution" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit channels connect whatsapp main-whatsapp --provider evolution
+agentkit channels status main-whatsapp
+agentkit channels test main-whatsapp --message "hello"
+agentkit channels deliveries list main-whatsapp
+agentkit channels buffers list main-whatsapp
+```
+
+Required secrets:
+
+```txt
+EVOLUTION_API_BASE_URL
+EVOLUTION_API_KEY
+EVOLUTION_INSTANCE_NAME
+EVOLUTION_WEBHOOK_TOKEN
+```
+
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+## Minimal Working Example
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "my-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [whatsappChannel({ name: "main-whatsapp", provider: "evolution" })],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+## Setup Behavior
+
+`agentkit channels connect whatsapp main-whatsapp --provider evolution` creates or updates the hosted channel, verifies managed secrets, calls Evolution API `POST /webhook/set/{instance}`, confirms the configured webhook through `GET /webhook/find/{instance}`, then runs a synthetic inbound smoke.
+
+Expected webhook URL shape:
+
+```txt
+https://<deploy-host>/channels/main-whatsapp/whatsapp/evolution/webhook
+```
+
+AgentKit registers the webhook URL with the required token query parameter:
+
+```txt
+https://<deploy-host>/channels/main-whatsapp/whatsapp/evolution/webhook?token=<EVOLUTION_WEBHOOK_TOKEN>
+```
+
+`EVOLUTION_API_BASE_URL` must be the public HTTPS origin for the Evolution API server, for example `https://evolution.example.com`. AgentKit rejects HTTP, localhost, private-network, link-local, metadata, and credential-bearing base URLs before sending `EVOLUTION_API_KEY`.
+
+## Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the Evolution channel.
+
+```ts
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+  audio: {
+    mode: "transcribe",
+  },
+})
+```
+
+Evolution audio webhooks become normalized audio messages. The retryable channel worker downloads media through Evolution API `POST /chat/getBase64FromMediaMessage/{instance}` and sends the bytes to AgentKit's configured transcription provider.
+
+## Safety Rules
+
+- Keep phone numbers redacted in logs by default.
+- Do not store Evolution API keys or webhook tokens in `agentkit.config.ts`.
+- `EVOLUTION_WEBHOOK_TOKEN` is required because AgentKit V1 does not rely on an Evolution webhook body-signature contract.
+- AgentKit ignores `fromMe` messages to avoid reply loops.
+- Text replies call Evolution API `POST /message/sendText/{instance}` with the `apikey` header and a body containing `number` and `text`.
+- Real provider success is recorded as `provider_sent` only when Evolution returns a provider message id.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Evolution should not receive a real message. Dry-run deliveries are recorded as `adapter_stubbed`, not sent.
+
+## Verification
+
+```sh
+agentkit channels setup main-whatsapp --apply
+agentkit channels status main-whatsapp
+agentkit channels test main-whatsapp --message "hello"
+agentkit channels test-audio main-whatsapp --fixture voice-note
+agentkit channels deliveries list main-whatsapp
+agentkit channels deliveries show <delivery-id>
+```
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN` as hosted managed secrets.
+
+`channel_signature_invalid`:
+The Evolution webhook query token does not match.
+
+`channel_provider_setup_invalid`:
+`EVOLUTION_API_BASE_URL` is not an allowed public HTTPS base URL.
+
+`channel_provider_setup_failed`:
+AgentKit could not configure or verify the Evolution webhook through `/webhook/set/{instance}` and `/webhook/find/{instance}`.
+
+`channel_audio_download_unavailable`:
+Evolution did not return base64 media data from `/chat/getBase64FromMediaMessage/{instance}`, or the audio payload did not include a provider message id.

package/docs/guides/connect-whatsapp-uazapi.md

@@ -0,0 +1,126 @@
+# Connect WhatsApp Through UAZAPI
+
+## Goal
+
+Connect a UAZAPI WhatsApp instance to a hosted AgentKit WhatsApp channel.
+
+## When To Use It
+
+Use this after `whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit channels connect whatsapp support-whatsapp --provider uazapi
+agentkit channels status support-whatsapp
+agentkit channels test support-whatsapp --message "hello"
+agentkit channels deliveries list support-whatsapp
+agentkit channels buffers list support-whatsapp
+```
+
+Required secrets:
+
+```txt
+UAZAPI_BASE_URL
+UAZAPI_TOKEN
+```
+
+Optional hardening secret:
+
+```txt
+UAZAPI_WEBHOOK_TOKEN
+```
+
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+## Minimal Working Example
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+## Setup Behavior
+
+`agentkit channels connect whatsapp support-whatsapp --provider uazapi` creates or updates the hosted channel, verifies managed secrets, calls UAZAPI `/webhook`, confirms the configured webhook is listed by UAZAPI, then runs a synthetic inbound smoke.
+
+Expected webhook URL shape:
+
+```txt
+https://<deploy-host>/channels/support-whatsapp/whatsapp/uazapi/webhook
+```
+
+If the channel declares `UAZAPI_WEBHOOK_TOKEN`, AgentKit registers the webhook URL with the token query parameter:
+
+```txt
+https://<deploy-host>/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>
+```
+
+`UAZAPI_BASE_URL` must be an HTTPS UAZAPI instance URL, for example `https://api.uazapi.com`. AgentKit rejects localhost, private-network, link-local, metadata, and credential-bearing base URLs before sending `UAZAPI_TOKEN`.
+
+## Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the UAZAPI channel.
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "uazapi",
+  audio: {
+    mode: "transcribe",
+  },
+})
+```
+
+UAZAPI audio webhooks become normalized audio messages. The retryable channel worker downloads media through UAZAPI `/message/download` using `return_base64: true`; AgentKit does not fetch arbitrary webhook-provided media URLs.
+
+## Safety Rules
+
+- Keep phone numbers redacted in logs by default.
+- Do not store UAZAPI tokens in `agentkit.config.ts`.
+- Use optional `UAZAPI_WEBHOOK_TOKEN` when the endpoint should require a secret query token in addition to the public route.
+- UAZAPI does not expose a documented webhook body-signature contract in AgentKit V1; treat the optional query token as the hardening layer.
+- AgentKit ignores `fromMe` and `wasSentByApi` messages to avoid reply loops.
+- Text replies call UAZAPI `POST /send/text` with the `token` header and a body containing `number`, `text`, `readchat`, `async`, `track_source`, and `track_id`.
+- Real provider success is recorded as `provider_sent` only when UAZAPI returns a provider message id.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when UAZAPI should not receive a real message. Dry-run deliveries are recorded as `adapter_stubbed`, not sent.
+
+## Verification
+
+```sh
+agentkit channels setup support-whatsapp --apply
+agentkit channels status support-whatsapp
+agentkit channels test support-whatsapp --message "hello"
+agentkit channels test-audio support-whatsapp --fixture voice-note
+agentkit channels deliveries list support-whatsapp
+agentkit channels deliveries show <delivery-id>
+```
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `UAZAPI_BASE_URL` and `UAZAPI_TOKEN` as hosted managed secrets. If the channel declares `UAZAPI_WEBHOOK_TOKEN`, set that managed secret too.
+
+`channel_signature_invalid`:
+The optional UAZAPI webhook query token does not match.
+
+`channel_provider_setup_invalid`:
+`UAZAPI_BASE_URL` is not an allowed HTTPS public base URL.
+
+`channel_provider_setup_failed`:
+AgentKit could not configure or verify the UAZAPI webhook through `/webhook`.
+
+`channel_audio_download_unavailable`:
+UAZAPI did not return base64 media data from `/message/download`, or the audio payload did not include a provider message id.

package/docs/guides/debug-channel.md

@@ -2,7 +2,7 @@
 
 ## Goal
 
-Diagnose website, Telegram, WhatsApp, Discord, or Slack channel setup, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
+Diagnose website, Telegram, WhatsApp, Discord, Slack, or generic webhook channel setup, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
 
 ## When To Use It
 
@@ -69,7 +69,7 @@ Expected `show` output includes signature status, dedupe key, queue/run state, o
 
 - Inspect delivery IDs, hashes, statuses, and redacted metadata rather than raw provider payloads.
 - Never paste provider secrets into fixtures or prompts.
-- Treat `adapter_stubbed` as a dry-run send, not proof that a client received a message.
+- Treat `adapter_stubbed` as "no outbound provider call happened", not proof that a client received a message. It can mean explicit dry-run mode or an inbound-only channel such as a generic webhook.
 - Before replaying or flushing buffered conversations, confirm the channel name and conversation ID.
 - Keep local `.env` values ignored and upload hosted production values through AgentKit secret commands.
 
@@ -117,7 +117,7 @@ The provider retried an already-processed event. No second agent run should be c
 The message is accepted and waiting inside a per-conversation channel buffer. It should move to `queued` after the quiet window, max wait, max message count, or max character count.
 
 `adapter_stubbed`:
-The adapter built the outbound request in explicit dry-run mode. The provider was not called.
+The adapter completed without calling an outbound provider. This can happen in explicit dry-run mode or for an inbound-only channel such as a generic webhook.
 
 `provider_sent`:
 The provider API accepted the outbound request and returned a provider message ID.

package/docs/llms-full.txt

@@ -60,8 +60,8 @@ agentkit conversations list
 agentkit conversations show <conversation-id>
 agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
-agentkit channels add <website|telegram|whatsapp|discord|slack> <name> [--provider zapster|meta] [--mode interactions|bot] [--api <url>]
-agentkit channels connect <website|telegram|whatsapp|discord|slack> <name> [--provider zapster|meta] [--mode interactions|bot] [--api <url>]
+agentkit channels add <website|telegram|whatsapp|discord|slack|webhook> <name> [--provider zapster|meta|uazapi|evolution] [--mode interactions|bot] [--api <url>]
+agentkit channels connect <website|telegram|whatsapp|discord|slack|webhook> <name> [--provider zapster|meta|uazapi|evolution] [--mode interactions|bot] [--api <url>]
 agentkit channels setup <name> [--apply] [--api <url>]
 agentkit channels status <name> [--api <url>]
 agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
@@ -344,7 +344,7 @@ Channels are hosted inbound/outbound conversation transports. They are separate
 Use these helpers in `agentkit.config.ts`:
 
 ```ts
-import { defineAgent, discordChannel, slackChannel, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -357,9 +357,11 @@ export default defineAgent({
     websiteChannel({ name: "website-chat" }),
     telegramChannel({ name: "support-telegram" }),
     whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
+    whatsappChannel({ name: "support-uazapi", provider: "uazapi" }),
     discordChannel({ name: "support-discord" }),
     discordChannel({ name: "server-discord", mode: "bot" }),
     slackChannel({ name: "support-slack" }),
+    webhookChannel({ name: "n8n-webhook" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -398,6 +400,8 @@ Useful guides:
 - Connect Discord: `docs/guides/connect-discord.md`
 - Connect Slack: `docs/guides/connect-slack.md`
 - Connect Telegram: `docs/guides/connect-telegram.md`
+- Connect WhatsApp through Evolution API: `docs/guides/connect-whatsapp-evolution.md`
+- Connect WhatsApp through UAZAPI: `docs/guides/connect-whatsapp-uazapi.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Debug a channel: `docs/guides/debug-channel.md`
 - Channel security: `docs/guides/channel-security.md`
@@ -417,6 +421,22 @@ ZAPSTER_INSTANCE_ID
 ZAPSTER_WEBHOOK_ID
 ```
 
+UAZAPI WhatsApp required secrets:
+
+```txt
+UAZAPI_BASE_URL
+UAZAPI_TOKEN
+```
+
+Evolution API WhatsApp required secrets:
+
+```txt
+EVOLUTION_API_BASE_URL
+EVOLUTION_API_KEY
+EVOLUTION_INSTANCE_NAME
+EVOLUTION_WEBHOOK_TOKEN
+```
+
 Discord slash-command required secret:
 
 ```txt
@@ -429,6 +449,24 @@ Discord bot-mode required secret:
 DISCORD_BOT_TOKEN
 ```
 
+Generic webhook required secret:
+
+```txt
+AGENTKIT_WEBHOOK_SECRET
+```
+
+Generic webhook payloads should be canonical JSON:
+
+```json
+{
+  "event_id": "evt_123",
+  "external_id": "customer_123",
+  "message": "hello from n8n"
+}
+```
+
+Use `Authorization: Bearer <AGENTKIT_WEBHOOK_SECRET>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>` where the HMAC is SHA-256 over the exact raw JSON body. The hosted URL is `/channels/<name>/webhook`.
+
 Common channel verification:
 
 ```sh
@@ -436,9 +474,12 @@ agentkit inspect
 agentkit deploy
 agentkit channels list
 agentkit channels add telegram support-telegram
+agentkit channels connect whatsapp main-whatsapp --provider evolution
+agentkit channels connect whatsapp support-whatsapp --provider uazapi
 agentkit channels connect discord support-discord
 agentkit channels connect discord server-discord --mode bot
 agentkit channels connect slack support-slack
+agentkit channels connect webhook n8n-webhook
 agentkit channels setup support-telegram
 agentkit channels test support-telegram --message "hello"
 agentkit channels test-audio support-telegram --fixture voice-note
@@ -447,7 +488,7 @@ agentkit channels deliveries list support-telegram
 agentkit channels deliveries show <delivery-id>
 ```
 
-`channels connect` creates or refreshes the channel resource, validates secrets, runs provider setup when supported, then runs the official synthetic smoke. `channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`.
+`channels connect` creates or refreshes the channel resource, validates secrets, runs provider setup when supported, then runs the official synthetic smoke. `channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`. `channels setup <uazapi-whatsapp-name> --apply` calls UAZAPI `/webhook` and requires `UAZAPI_BASE_URL` plus `UAZAPI_TOKEN`. `channels setup <evolution-whatsapp-name> --apply` calls Evolution API `/webhook/set/{instance}` and requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN`.
 
 Discord slash-command mode validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against `DISCORD_PUBLIC_KEY`, answers signed `PING` requests with `type: 1`, acknowledges slash commands with a deferred response, then sends the final answer as an interaction follow-up. Discord bot mode uses `DISCORD_BOT_TOKEN`, Discord Gateway `MESSAGE_CREATE`, Message Content Intent, and `/channels/<channel_id>/messages` bot replies. Discord channels support buffering but do not support `audio` in V1.
 
@@ -456,10 +497,14 @@ Default tests are offline. Real provider smoke tests are opt-in:
 ```sh
 AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
 AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
+AGENTKIT_RUN_UAZAPI_CHANNEL_TESTS=1 bun test
+AGENTKIT_RUN_EVOLUTION_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`.
+UAZAPI smoke also requires `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, and `AGENTKIT_UAZAPI_TO`.
+Evolution smoke also requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `AGENTKIT_EVOLUTION_TO`.
 
 ## Tool Contract
 

package/docs/llms.txt

@@ -24,6 +24,8 @@ Task guides:
 - Connect Discord: `docs/guides/connect-discord.md`
 - Connect Slack: `docs/guides/connect-slack.md`
 - Connect Telegram: `docs/guides/connect-telegram.md`
+- Connect WhatsApp through Evolution API: `docs/guides/connect-whatsapp-evolution.md`
+- Connect WhatsApp through UAZAPI: `docs/guides/connect-whatsapp-uazapi.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Follow channel webhook and delivery-log safety rules: `docs/guides/channel-security.md`
 - Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`
@@ -55,9 +57,12 @@ agentkit conversations show <conversation-id>
 agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
 agentkit channels add telegram support-telegram
+agentkit channels connect whatsapp main-whatsapp --provider evolution
+agentkit channels connect whatsapp support-whatsapp --provider uazapi
 agentkit channels connect discord support-discord
 agentkit channels connect discord server-discord --mode bot
 agentkit channels connect slack support-slack
+agentkit channels connect webhook n8n-webhook
 agentkit channels setup support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.21",
   "private": false,
   "type": "module",
   "repository": {