Add a Generic Webhook / HTTP Adapter for Arbitrary Chat Platforms

Open
#96 1 comment 18 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@roboeve is already working on this.

Since Oct 12, 2026.

  • #1033 by @roboeve — open

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
typescript
Domain
api, backend

Research direction

Start from the proposed Chat configuration and createGenericAdapter entry point, then review how the SDK currently represents inbound events and sends responses. Define the adapter's scope around webhook payload mapping, optional verification and filtering, and developer-provided outgoing HTTP behavior; done means a documented generic adapter can support arbitrary HTTP-capable platforms without platform-specific parsing.

Written by the indexing model from the issue text.

Description

enhancement
Problem Statement

Many popular or emerging messaging channels do not yet have dedicated adapters in the SDK. Like -

  1. WhatsApp (via open-source HTTP bridges such as WAHA or Beeper)
  2. Meta Ray-Ban smart glasses (which surface conversations through Meta/WhatsApp channels)
  3. Telegram (via its webhook-capable Bot API)
  4. Matrix / Element
  5. Various self-hosted, enterprise, or niche messengers
  6. Any future or custom platform that supports inbound HTTP webhooks and can receive responses via HTTP POST

Without a generic mechanism, supporting these platforms requires either waiting for official adapter packages or forking/maintaining custom platform-specific integrations — which undermines the "write once, run anywhere" value proposition of the SDK.

Proposed Solution

Introduce a built-in generic webhook / HTTP adapter (or a lightweight "raw HTTP" adapter) in the core Chat SDK or as a first-party package (e.g., @chat-adapter/webhook or @chat-adapter/generic).
This adapter would allow developers to connect the same bot logic to any HTTP-capable platform by defining:

  1. How incoming HTTP payloads are parsed and mapped to Chat SDK events (e.g., extracting message text, sender ID, channel/thread info)
  2. How outgoing Chat SDK responses are transformed and sent back (e.g., via HTTP POST, specific JSON shape, headers, etc.)
Alternatives Considered

No response

Use Case
import { Chat } from "chat";
import { createGenericAdapter } from "@chat-adapter/generic";  // or built-in

const bot = new Chat({
  userName: "mybot",
  adapters: {
    custom: createGenericAdapter({
      // Core webhook handling
      path: "/webhook/my-platform",               // Vercel / server route
      verification: {
        secret: process.env.WEBHOOK_SECRET,       // optional HMAC / token check
      },

      // Required mappings (examples)
      incoming: {
        getText: (payload) => payload?.message?.text || payload?.body,
        getSenderId: (payload) => payload?.from?.id || payload?.sender,
        getChannelId: (payload) => payload?.thread?.id || payload?.chatId,
        // Optional: getMessageId, isFromBot, etc.
      },

      outgoing: async (channelId, content, options) => {
        // Developer provides the send logic (fetch/axios/etc.)
        await fetch("https://api.platform.com/messages", {
          method: "POST",
          headers: { Authorization: `Bearer ${process.env.PLATFORM_TOKEN}` },
          body: JSON.stringify({
            chat_id: channelId,
            text: content.text,
            // ... platform-specific fields
          }),
        });
      },

      // Optional extras
      platformName: "WhatsApp",                     // for logs/metrics
      shouldHandle: (req) => req.headers["user-agent"]?.includes("WhatsApp"), // filter
    }),
  },
  // ... other config (state, model, etc.)
});
Priority

Nice to have

Contribution
  • I am willing to help implement this feature
Additional Context

No response

Dominant language
TypeScript
Stars
2.5k
Forks
355
Avg merge
2d 15h
Merged PRs (30d)
42

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from vercel/chat

All issues in vercel/chat

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.