chat 4.18.0 → 4.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -0
- package/dist/index.d.ts +87 -9
- package/dist/index.js +57 -10
- package/dist/index.js.map +1 -1
- package/docs/adapters.mdx +56 -0
- package/docs/error-handling.mdx +1 -1
- package/docs/guides/code-review-hono.mdx +3 -3
- package/docs/guides/discord-nuxt.mdx +3 -2
- package/docs/guides/slack-nextjs.mdx +3 -2
- package/docs/meta.json +3 -4
- package/docs/slash-commands.mdx +4 -4
- package/docs/{state/index.mdx → state.mdx} +24 -12
- package/docs/usage.mdx +5 -0
- package/package.json +1 -1
- package/docs/adapters/discord.mdx +0 -217
- package/docs/adapters/gchat.mdx +0 -237
- package/docs/adapters/github.mdx +0 -222
- package/docs/adapters/index.mdx +0 -129
- package/docs/adapters/linear.mdx +0 -206
- package/docs/adapters/meta.json +0 -13
- package/docs/adapters/slack.mdx +0 -314
- package/docs/adapters/teams.mdx +0 -287
- package/docs/adapters/telegram.mdx +0 -161
- package/docs/state/ioredis.mdx +0 -81
- package/docs/state/memory.mdx +0 -52
- package/docs/state/meta.json +0 -4
- package/docs/state/postgres.mdx +0 -98
- package/docs/state/redis.mdx +0 -100
package/docs/adapters/gchat.mdx
DELETED
|
@@ -1,237 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Google Chat
|
|
3
|
-
description: Configure the Google Chat adapter with service account authentication and optional Pub/Sub.
|
|
4
|
-
type: integration
|
|
5
|
-
prerequisites:
|
|
6
|
-
- /docs/getting-started
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Installation
|
|
10
|
-
|
|
11
|
-
```sh title="Terminal"
|
|
12
|
-
pnpm add @chat-adapter/gchat
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
## Usage
|
|
16
|
-
|
|
17
|
-
The adapter auto-detects credentials from `GOOGLE_CHAT_CREDENTIALS` or `GOOGLE_CHAT_USE_ADC` environment variables:
|
|
18
|
-
|
|
19
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
20
|
-
import { Chat } from "chat";
|
|
21
|
-
import { createGoogleChatAdapter } from "@chat-adapter/gchat";
|
|
22
|
-
|
|
23
|
-
const bot = new Chat({
|
|
24
|
-
userName: "mybot",
|
|
25
|
-
adapters: {
|
|
26
|
-
gchat: createGoogleChatAdapter(),
|
|
27
|
-
},
|
|
28
|
-
});
|
|
29
|
-
|
|
30
|
-
bot.onNewMention(async (thread, message) => {
|
|
31
|
-
await thread.post("Hello from Google Chat!");
|
|
32
|
-
});
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Google Chat setup
|
|
36
|
-
|
|
37
|
-
### 1. Create a GCP project
|
|
38
|
-
|
|
39
|
-
1. Go to [console.cloud.google.com](https://console.cloud.google.com)
|
|
40
|
-
2. Click the project dropdown then **New Project**
|
|
41
|
-
3. Enter project name and click **Create**
|
|
42
|
-
|
|
43
|
-
### 2. Enable required APIs
|
|
44
|
-
|
|
45
|
-
Go to **APIs & Services** then **Library** and enable:
|
|
46
|
-
|
|
47
|
-
- **Google Chat API**
|
|
48
|
-
- **Google Workspace Events API** (for receiving all messages)
|
|
49
|
-
- **Cloud Pub/Sub API** (for receiving all messages)
|
|
50
|
-
|
|
51
|
-
### 3. Create a service account
|
|
52
|
-
|
|
53
|
-
1. Go to **IAM & Admin** then **Service Accounts**
|
|
54
|
-
2. Click **Create Service Account**
|
|
55
|
-
3. Enter name and description
|
|
56
|
-
4. Click **Create and Continue**
|
|
57
|
-
5. Skip the optional steps, click **Done**
|
|
58
|
-
|
|
59
|
-
### 4. Create service account key
|
|
60
|
-
|
|
61
|
-
1. Click on your service account
|
|
62
|
-
2. Go to **Keys** tab
|
|
63
|
-
3. Click **Add Key** then **Create new key**
|
|
64
|
-
4. Select **JSON** and click **Create**
|
|
65
|
-
5. Copy the entire JSON content as `GOOGLE_CHAT_CREDENTIALS`
|
|
66
|
-
|
|
67
|
-
<Callout type="info">
|
|
68
|
-
If your organization has the `iam.disableServiceAccountKeyCreation` constraint enabled, you need to relax it or add an exception for your project in **IAM & Admin** then **Organization Policies**.
|
|
69
|
-
</Callout>
|
|
70
|
-
|
|
71
|
-
### 5. Configure Google Chat app
|
|
72
|
-
|
|
73
|
-
1. Go to the [Chat API configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)
|
|
74
|
-
2. Click **Configuration** and fill in:
|
|
75
|
-
- **App name**: Your bot's display name
|
|
76
|
-
- **Avatar URL**: URL to your bot's avatar
|
|
77
|
-
- **Description**: What your bot does
|
|
78
|
-
- **Interactive features**: Enable **Receive 1:1 messages** and **Join spaces and group conversations**
|
|
79
|
-
- **Connection settings**: Select **App URL**
|
|
80
|
-
- **App URL**: `https://your-domain.com/api/webhooks/gchat`
|
|
81
|
-
- **Visibility**: Choose who can discover your app
|
|
82
|
-
3. Click **Save**
|
|
83
|
-
|
|
84
|
-
### 6. Add bot to a space
|
|
85
|
-
|
|
86
|
-
1. Open Google Chat
|
|
87
|
-
2. Create or open a Space
|
|
88
|
-
3. Click the space name then **Manage apps & integrations**
|
|
89
|
-
4. Click **Add apps**, search for your app, and click **Add**
|
|
90
|
-
|
|
91
|
-
## Pub/Sub for all messages (optional)
|
|
92
|
-
|
|
93
|
-
By default, Google Chat only sends webhooks for @mentions. To receive all messages in a space, set up Workspace Events with Pub/Sub.
|
|
94
|
-
|
|
95
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
96
|
-
createGoogleChatAdapter({
|
|
97
|
-
pubsubTopic: process.env.GOOGLE_CHAT_PUBSUB_TOPIC,
|
|
98
|
-
impersonateUser: process.env.GOOGLE_CHAT_IMPERSONATE_USER,
|
|
99
|
-
});
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
`GOOGLE_CHAT_PUBSUB_TOPIC` and `GOOGLE_CHAT_IMPERSONATE_USER` are also auto-detected from env vars, so you can omit them from config if the env vars are set.
|
|
103
|
-
|
|
104
|
-
### 1. Create Pub/Sub topic
|
|
105
|
-
|
|
106
|
-
1. Go to **Pub/Sub** then **Topics**
|
|
107
|
-
2. Click **Create Topic**
|
|
108
|
-
3. Enter topic ID (e.g., `chat-events`)
|
|
109
|
-
4. Uncheck **Add a default subscription**
|
|
110
|
-
5. Click **Create**
|
|
111
|
-
6. Copy the full topic name as `GOOGLE_CHAT_PUBSUB_TOPIC` (format: `projects/your-project-id/topics/chat-events`)
|
|
112
|
-
|
|
113
|
-
### 2. Grant Chat service account access
|
|
114
|
-
|
|
115
|
-
1. Go to your Pub/Sub topic
|
|
116
|
-
2. Click **Permissions** tab
|
|
117
|
-
3. Click **Add Principal**
|
|
118
|
-
4. Enter `chat-api-push@system.gserviceaccount.com`
|
|
119
|
-
5. Select role **Pub/Sub Publisher**
|
|
120
|
-
6. Click **Save**
|
|
121
|
-
|
|
122
|
-
### 3. Create push subscription
|
|
123
|
-
|
|
124
|
-
1. Go to **Pub/Sub** then **Subscriptions**
|
|
125
|
-
2. Click **Create Subscription**
|
|
126
|
-
3. Select your topic
|
|
127
|
-
4. Set **Delivery type** to Push
|
|
128
|
-
5. Set **Endpoint URL** to `https://your-domain.com/api/webhooks/gchat`
|
|
129
|
-
6. Click **Create**
|
|
130
|
-
|
|
131
|
-
### 4. Enable domain-wide delegation
|
|
132
|
-
|
|
133
|
-
Domain-wide delegation is required for creating Workspace Events subscriptions and initiating DMs.
|
|
134
|
-
|
|
135
|
-
**Step 1 — Enable delegation on the service account:**
|
|
136
|
-
|
|
137
|
-
1. Go to **IAM & Admin** then **Service Accounts**
|
|
138
|
-
2. Click on your service account
|
|
139
|
-
3. Check **Enable Google Workspace Domain-wide Delegation** and save
|
|
140
|
-
4. Copy the **Client ID** (a numeric ID, not the email)
|
|
141
|
-
|
|
142
|
-
**Step 2 — Authorize in Google Admin Console:**
|
|
143
|
-
|
|
144
|
-
1. Go to [Google Admin Console](https://admin.google.com)
|
|
145
|
-
2. Go to **Security** then **Access and data control** then **API controls**
|
|
146
|
-
3. Click **Manage Domain Wide Delegation** then **Add new**
|
|
147
|
-
4. Enter the numeric **Client ID** from Step 1
|
|
148
|
-
5. Add OAuth scopes (comma-separated, on one line):
|
|
149
|
-
```
|
|
150
|
-
https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.spaces.create
|
|
151
|
-
```
|
|
152
|
-
6. Click **Authorize**
|
|
153
|
-
|
|
154
|
-
**Step 3 — Set environment variable:**
|
|
155
|
-
|
|
156
|
-
Set `GOOGLE_CHAT_IMPERSONATE_USER` to an admin user email in your domain (e.g., `admin@yourdomain.com`).
|
|
157
|
-
|
|
158
|
-
## Configuration
|
|
159
|
-
|
|
160
|
-
All options are auto-detected from environment variables when not provided.
|
|
161
|
-
|
|
162
|
-
| Option | Required | Description |
|
|
163
|
-
|--------|----------|-------------|
|
|
164
|
-
| `credentials` | No* | Service account credentials JSON. Auto-detected from `GOOGLE_CHAT_CREDENTIALS` |
|
|
165
|
-
| `useApplicationDefaultCredentials` | No | Use Application Default Credentials. Auto-detected from `GOOGLE_CHAT_USE_ADC` |
|
|
166
|
-
| `pubsubTopic` | No | Pub/Sub topic for Workspace Events. Auto-detected from `GOOGLE_CHAT_PUBSUB_TOPIC` |
|
|
167
|
-
| `impersonateUser` | No | User email for domain-wide delegation. Auto-detected from `GOOGLE_CHAT_IMPERSONATE_USER` |
|
|
168
|
-
| `auth` | No | Custom auth object (advanced) |
|
|
169
|
-
| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
|
|
170
|
-
|
|
171
|
-
*Either `credentials`, `GOOGLE_CHAT_CREDENTIALS` env var, `useApplicationDefaultCredentials`, or `GOOGLE_CHAT_USE_ADC=true` is required.
|
|
172
|
-
|
|
173
|
-
## Environment variables
|
|
174
|
-
|
|
175
|
-
```bash title=".env.local"
|
|
176
|
-
GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}
|
|
177
|
-
|
|
178
|
-
# Optional: for receiving all messages
|
|
179
|
-
GOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project/topics/chat-events
|
|
180
|
-
GOOGLE_CHAT_IMPERSONATE_USER=admin@yourdomain.com
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
## Features
|
|
184
|
-
|
|
185
|
-
| Feature | Supported |
|
|
186
|
-
|---------|-----------|
|
|
187
|
-
| Mentions | Yes |
|
|
188
|
-
| Reactions (add/remove) | Yes (via Workspace Events) |
|
|
189
|
-
| Cards (Google Chat Cards) | Yes |
|
|
190
|
-
| Modals | No |
|
|
191
|
-
| Streaming | Post+Edit fallback |
|
|
192
|
-
| DMs | Yes (requires delegation) |
|
|
193
|
-
| Ephemeral messages | Yes (native) |
|
|
194
|
-
| File uploads | Yes |
|
|
195
|
-
| Typing indicator | No |
|
|
196
|
-
| Message history | Yes |
|
|
197
|
-
|
|
198
|
-
## Limitations
|
|
199
|
-
|
|
200
|
-
- **Typing indicators**: Not supported by Google Chat API. `startTyping()` is a no-op.
|
|
201
|
-
- **Adding reactions**: The Google Chat API doesn't support service account (app) authentication for adding reactions. To use `addReaction()` or `removeReaction()`, you need domain-wide delegation with `impersonateUser` configured — but the reaction appears as coming from the impersonated user, not the bot.
|
|
202
|
-
|
|
203
|
-
### Message history (`fetchMessages`)
|
|
204
|
-
|
|
205
|
-
Fetching message history requires domain-wide delegation with the `impersonateUser` config option set. The impersonated user must have access to the spaces you want to read from. See the [Pub/Sub setup](#4-enable-domain-wide-delegation) above for configuring delegation and OAuth scopes.
|
|
206
|
-
|
|
207
|
-
## Troubleshooting
|
|
208
|
-
|
|
209
|
-
### No webhook received
|
|
210
|
-
|
|
211
|
-
- Verify the App URL is correct in Google Chat configuration
|
|
212
|
-
- Check that the Chat API is enabled
|
|
213
|
-
- Ensure the service account has the necessary permissions
|
|
214
|
-
|
|
215
|
-
### Pub/Sub not working
|
|
216
|
-
|
|
217
|
-
- Verify `chat-api-push@system.gserviceaccount.com` has Pub/Sub Publisher role
|
|
218
|
-
- Check that the push subscription URL is correct
|
|
219
|
-
- Verify domain-wide delegation is configured with correct scopes
|
|
220
|
-
- Check `GOOGLE_CHAT_IMPERSONATE_USER` is a valid admin email
|
|
221
|
-
|
|
222
|
-
### "Permission denied" for Workspace Events
|
|
223
|
-
|
|
224
|
-
- Ensure domain-wide delegation is configured
|
|
225
|
-
- Verify the OAuth scopes are exactly as specified
|
|
226
|
-
- Check that the impersonated user has access to the spaces
|
|
227
|
-
|
|
228
|
-
### "Insufficient Permission" for DMs
|
|
229
|
-
|
|
230
|
-
- DMs require domain-wide delegation with `chat.spaces` and `chat.spaces.create` scopes
|
|
231
|
-
- Scope changes can take up to 24 hours to propagate
|
|
232
|
-
|
|
233
|
-
### Button clicks not received
|
|
234
|
-
|
|
235
|
-
- Verify **Interactive features** is enabled in the Google Chat app configuration
|
|
236
|
-
- Check that the App URL is correctly set and accessible
|
|
237
|
-
- Button clicks go to the same webhook URL as messages
|
package/docs/adapters/github.mdx
DELETED
|
@@ -1,222 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: GitHub
|
|
3
|
-
description: Configure the GitHub adapter to respond to @mentions in PR and issue comment threads.
|
|
4
|
-
type: integration
|
|
5
|
-
prerequisites:
|
|
6
|
-
- /docs/getting-started
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
The GitHub adapter treats issue and pull request comments as messages, and issues/PRs as threads.
|
|
10
|
-
|
|
11
|
-
## Installation
|
|
12
|
-
|
|
13
|
-
```sh title="Terminal"
|
|
14
|
-
pnpm add @chat-adapter/github
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Usage
|
|
18
|
-
|
|
19
|
-
The adapter auto-detects credentials from `GITHUB_TOKEN` (or `GITHUB_APP_ID`/`GITHUB_PRIVATE_KEY`), `GITHUB_WEBHOOK_SECRET`, and `GITHUB_BOT_USERNAME` environment variables:
|
|
20
|
-
|
|
21
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
22
|
-
import { Chat } from "chat";
|
|
23
|
-
import { createGitHubAdapter } from "@chat-adapter/github";
|
|
24
|
-
|
|
25
|
-
const bot = new Chat({
|
|
26
|
-
userName: "my-bot",
|
|
27
|
-
adapters: {
|
|
28
|
-
github: createGitHubAdapter(),
|
|
29
|
-
},
|
|
30
|
-
});
|
|
31
|
-
|
|
32
|
-
bot.onNewMention(async (thread, message) => {
|
|
33
|
-
await thread.post("Hello from GitHub!");
|
|
34
|
-
});
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
## Authentication
|
|
38
|
-
|
|
39
|
-
### Option A: Personal Access Token
|
|
40
|
-
|
|
41
|
-
Best for personal projects, testing, or single-repo bots.
|
|
42
|
-
|
|
43
|
-
1. Go to [Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
|
|
44
|
-
2. Create a new token with `repo` scope
|
|
45
|
-
3. Set `GITHUB_TOKEN` environment variable
|
|
46
|
-
|
|
47
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
48
|
-
createGitHubAdapter({
|
|
49
|
-
token: process.env.GITHUB_TOKEN!,
|
|
50
|
-
});
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### Option B: GitHub App (recommended)
|
|
54
|
-
|
|
55
|
-
Better rate limits, security, and supports multiple installations.
|
|
56
|
-
|
|
57
|
-
**1. Create the app:**
|
|
58
|
-
|
|
59
|
-
1. Go to [Settings > Developer settings > GitHub Apps > New GitHub App](https://github.com/settings/apps/new)
|
|
60
|
-
2. Set **Webhook URL** to `https://your-domain.com/api/webhooks/github`
|
|
61
|
-
3. Generate and set a **Webhook secret**
|
|
62
|
-
4. Set permissions:
|
|
63
|
-
- Repository > Issues: Read & write
|
|
64
|
-
- Repository > Pull requests: Read & write
|
|
65
|
-
- Repository > Metadata: Read-only
|
|
66
|
-
5. Subscribe to events: Issue comment, Pull request review comment
|
|
67
|
-
6. Click **Create GitHub App**
|
|
68
|
-
7. Note the **App ID** and click **Generate a private key**
|
|
69
|
-
|
|
70
|
-
**2. Install the app:**
|
|
71
|
-
|
|
72
|
-
1. Go to your app's settings then **Install App**
|
|
73
|
-
2. Click **Install** and choose repositories
|
|
74
|
-
3. Note the **Installation ID** from the URL:
|
|
75
|
-
```
|
|
76
|
-
https://github.com/settings/installations/12345678
|
|
77
|
-
^^^^^^^^
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
**Single-tenant:**
|
|
81
|
-
|
|
82
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
83
|
-
createGitHubAdapter({
|
|
84
|
-
appId: process.env.GITHUB_APP_ID!,
|
|
85
|
-
privateKey: process.env.GITHUB_PRIVATE_KEY!,
|
|
86
|
-
installationId: parseInt(process.env.GITHUB_INSTALLATION_ID!),
|
|
87
|
-
});
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
**Multi-tenant (omit `installationId`):**
|
|
91
|
-
|
|
92
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
93
|
-
createGitHubAdapter({
|
|
94
|
-
appId: process.env.GITHUB_APP_ID!,
|
|
95
|
-
privateKey: process.env.GITHUB_PRIVATE_KEY!,
|
|
96
|
-
});
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
The adapter automatically extracts installation IDs from webhooks and caches API clients per-installation.
|
|
100
|
-
|
|
101
|
-
## Webhook setup
|
|
102
|
-
|
|
103
|
-
For repository or organization webhooks:
|
|
104
|
-
|
|
105
|
-
1. Go to repository/org **Settings** then **Webhooks** then **Add webhook**
|
|
106
|
-
2. Set **Payload URL** to `https://your-domain.com/api/webhooks/github`
|
|
107
|
-
3. Set **Content type** to `application/json` (required — the default `application/x-www-form-urlencoded` does not work)
|
|
108
|
-
4. Set **Secret** to match your `webhookSecret`
|
|
109
|
-
5. Select events: Issue comments, Pull request review comments
|
|
110
|
-
|
|
111
|
-
<Callout type="warn">
|
|
112
|
-
GitHub App webhooks are configured during app creation. Make sure to select `application/json` as the content type.
|
|
113
|
-
</Callout>
|
|
114
|
-
|
|
115
|
-
## Thread model
|
|
116
|
-
|
|
117
|
-
GitHub has two types of comment threads:
|
|
118
|
-
|
|
119
|
-
| Type | Tab | Thread ID format |
|
|
120
|
-
|------|-----|-----------------|
|
|
121
|
-
| PR-level | Conversation | `github:{owner}/{repo}:{prNumber}` |
|
|
122
|
-
| Review comments | Files Changed | `github:{owner}/{repo}:{prNumber}:rc:{commentId}` |
|
|
123
|
-
|
|
124
|
-
## Reactions
|
|
125
|
-
|
|
126
|
-
Supports GitHub's reaction emoji:
|
|
127
|
-
|
|
128
|
-
| SDK emoji | GitHub reaction |
|
|
129
|
-
|-----------|----------------|
|
|
130
|
-
| `thumbs_up` | 👍 (+1) |
|
|
131
|
-
| `thumbs_down` | 👎 (-1) |
|
|
132
|
-
| `laugh` | 😄 |
|
|
133
|
-
| `confused` | 😕 |
|
|
134
|
-
| `heart` | ❤️ |
|
|
135
|
-
| `hooray` | 🎉 |
|
|
136
|
-
| `rocket` | 🚀 |
|
|
137
|
-
| `eyes` | 👀 |
|
|
138
|
-
|
|
139
|
-
## Configuration
|
|
140
|
-
|
|
141
|
-
All options are auto-detected from environment variables when not provided.
|
|
142
|
-
|
|
143
|
-
| Option | Required | Description |
|
|
144
|
-
|--------|----------|-------------|
|
|
145
|
-
| `token` | No* | Personal Access Token. Auto-detected from `GITHUB_TOKEN` |
|
|
146
|
-
| `appId` | No* | GitHub App ID. Auto-detected from `GITHUB_APP_ID` |
|
|
147
|
-
| `privateKey` | No | GitHub App private key (PEM). Auto-detected from `GITHUB_PRIVATE_KEY` |
|
|
148
|
-
| `installationId` | No | Installation ID (omit for multi-tenant). Auto-detected from `GITHUB_INSTALLATION_ID` |
|
|
149
|
-
| `webhookSecret` | No** | Webhook secret. Auto-detected from `GITHUB_WEBHOOK_SECRET` |
|
|
150
|
-
| `userName` | No | Bot username for @mention detection. Auto-detected from `GITHUB_BOT_USERNAME` (default: `"github-bot"`) |
|
|
151
|
-
| `botUserId` | No | Bot's numeric user ID (auto-detected if not provided) |
|
|
152
|
-
| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
|
|
153
|
-
|
|
154
|
-
*Either `token`/`GITHUB_TOKEN` or `appId`+`privateKey`/`GITHUB_APP_ID`+`GITHUB_PRIVATE_KEY` is required.
|
|
155
|
-
|
|
156
|
-
**`webhookSecret` is required — either via config or `GITHUB_WEBHOOK_SECRET` env var.
|
|
157
|
-
|
|
158
|
-
## Environment variables
|
|
159
|
-
|
|
160
|
-
```bash title=".env.local"
|
|
161
|
-
# Personal Access Token auth
|
|
162
|
-
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
|
|
163
|
-
|
|
164
|
-
# OR GitHub App auth
|
|
165
|
-
GITHUB_APP_ID=123456
|
|
166
|
-
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
|
|
167
|
-
GITHUB_INSTALLATION_ID=12345678 # Optional for multi-tenant
|
|
168
|
-
|
|
169
|
-
# Required
|
|
170
|
-
GITHUB_WEBHOOK_SECRET=your-webhook-secret
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
## Features
|
|
174
|
-
|
|
175
|
-
| Feature | Supported |
|
|
176
|
-
|---------|-----------|
|
|
177
|
-
| Mentions | Yes |
|
|
178
|
-
| Reactions (add/remove) | Yes |
|
|
179
|
-
| Cards | GFM Markdown |
|
|
180
|
-
| Modals | No |
|
|
181
|
-
| Streaming | No |
|
|
182
|
-
| DMs | No |
|
|
183
|
-
| File uploads | No |
|
|
184
|
-
| Typing indicator | No |
|
|
185
|
-
| Message history | Yes |
|
|
186
|
-
| Multi-tenant | Yes (GitHub App) |
|
|
187
|
-
|
|
188
|
-
## Limitations
|
|
189
|
-
|
|
190
|
-
- **No typing indicators** — GitHub doesn't support typing indicators
|
|
191
|
-
- **No streaming** — Messages posted in full (editing supported for updates)
|
|
192
|
-
- **No DMs** — GitHub doesn't have direct messages
|
|
193
|
-
- **No modals** — GitHub doesn't support interactive modals
|
|
194
|
-
- **Action buttons** — Rendered as text; use link buttons for clickable actions
|
|
195
|
-
|
|
196
|
-
## Troubleshooting
|
|
197
|
-
|
|
198
|
-
### "Invalid signature" error
|
|
199
|
-
|
|
200
|
-
- Verify `GITHUB_WEBHOOK_SECRET` matches your webhook configuration
|
|
201
|
-
- Ensure the request body isn't modified before verification
|
|
202
|
-
|
|
203
|
-
### "Invalid JSON" error
|
|
204
|
-
|
|
205
|
-
- Change webhook **Content type** to `application/json`
|
|
206
|
-
|
|
207
|
-
### Bot not responding to mentions
|
|
208
|
-
|
|
209
|
-
- Verify webhook events are configured (issue_comment, pull_request_review_comment)
|
|
210
|
-
- Check the webhook URL is correct and accessible
|
|
211
|
-
- Ensure the `userName` config matches your bot's GitHub username
|
|
212
|
-
|
|
213
|
-
### "Installation ID required" error
|
|
214
|
-
|
|
215
|
-
- This occurs when making API calls outside webhook context in multi-tenant mode
|
|
216
|
-
- Use a persistent state adapter (Redis) to store installation mappings
|
|
217
|
-
- The first interaction must come from a webhook to establish the mapping
|
|
218
|
-
|
|
219
|
-
### Rate limiting
|
|
220
|
-
|
|
221
|
-
- PATs have lower rate limits than GitHub Apps
|
|
222
|
-
- Consider switching to a GitHub App for production use
|
package/docs/adapters/index.mdx
DELETED
|
@@ -1,129 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Overview
|
|
3
|
-
description: Platform-specific adapters for Slack, Teams, Google Chat, Discord, Telegram, GitHub, and Linear.
|
|
4
|
-
type: overview
|
|
5
|
-
prerequisites:
|
|
6
|
-
- /docs/getting-started
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
Adapters handle webhook verification, message parsing, and API calls for each platform. Install only the adapters you need.
|
|
10
|
-
|
|
11
|
-
## Feature matrix
|
|
12
|
-
|
|
13
|
-
### Messaging
|
|
14
|
-
|
|
15
|
-
| Feature | [Slack](/docs/adapters/slack) | [Teams](/docs/adapters/teams) | [Google Chat](/docs/adapters/gchat) | [Discord](/docs/adapters/discord) | [Telegram](/docs/adapters/telegram) | [GitHub](/docs/adapters/github) | [Linear](/docs/adapters/linear) |
|
|
16
|
-
|---------|-------|-------|-------------|---------|---------|--------|--------|
|
|
17
|
-
| Post message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
18
|
-
| Edit message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
19
|
-
| Delete message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
20
|
-
| File uploads | ✅ | ✅ | ❌ | ✅ | ⚠️ Single file | ❌ | ❌ |
|
|
21
|
-
| Streaming | ✅ Native | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ❌ | ❌ |
|
|
22
|
-
|
|
23
|
-
### Rich content
|
|
24
|
-
|
|
25
|
-
| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear |
|
|
26
|
-
|---------|-------|-------|-------------|---------|----------|--------|--------|
|
|
27
|
-
| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown |
|
|
28
|
-
| Buttons | ✅ | ✅ | ✅ | ✅ | ⚠️ Inline keyboard callbacks | ❌ | ❌ |
|
|
29
|
-
| Link buttons | ✅ | ✅ | ✅ | ✅ | ⚠️ Inline keyboard URLs | ❌ | ❌ |
|
|
30
|
-
| Select menus | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
31
|
-
| Tables | ✅ Block Kit | ✅ GFM | ⚠️ ASCII | ✅ GFM | ⚠️ ASCII | ✅ GFM | ✅ GFM |
|
|
32
|
-
| Fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
33
|
-
| Images in cards | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
|
|
34
|
-
| Modals | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
|
35
|
-
|
|
36
|
-
### Conversations
|
|
37
|
-
|
|
38
|
-
| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear |
|
|
39
|
-
|---------|-------|-------|-------------|---------|----------|--------|--------|
|
|
40
|
-
| Slash commands | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
|
|
41
|
-
| Mentions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
42
|
-
| Add reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
43
|
-
| Remove reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |
|
|
44
|
-
| Typing indicator | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
|
|
45
|
-
| DMs | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
|
|
46
|
-
| Ephemeral messages | ✅ Native | ❌ | ✅ Native | ❌ | ❌ | ❌ | ❌ |
|
|
47
|
-
|
|
48
|
-
### Message history
|
|
49
|
-
|
|
50
|
-
| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear |
|
|
51
|
-
|---------|-------|-------|-------------|---------|----------|--------|--------|
|
|
52
|
-
| Fetch messages | ✅ | ✅ | ✅ | ✅ | ⚠️ Cached | ✅ | ✅ |
|
|
53
|
-
| Fetch single message | ✅ | ❌ | ❌ | ❌ | ⚠️ Cached | ❌ | ❌ |
|
|
54
|
-
| Fetch thread info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
55
|
-
| Fetch channel messages | ✅ | ✅ | ✅ | ✅ | ⚠️ Cached | ✅ | ❌ |
|
|
56
|
-
| List threads | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
|
|
57
|
-
| Fetch channel info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
|
|
58
|
-
| Post channel message | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
|
|
59
|
-
|
|
60
|
-
<Callout type="info">
|
|
61
|
-
⚠️ indicates partial support — the feature works with limitations. See individual adapter pages for details.
|
|
62
|
-
</Callout>
|
|
63
|
-
|
|
64
|
-
## Packages
|
|
65
|
-
|
|
66
|
-
| Platform | Package |
|
|
67
|
-
|----------|---------|
|
|
68
|
-
| [Slack](/docs/adapters/slack) | `@chat-adapter/slack` |
|
|
69
|
-
| [Microsoft Teams](/docs/adapters/teams) | `@chat-adapter/teams` |
|
|
70
|
-
| [Google Chat](/docs/adapters/gchat) | `@chat-adapter/gchat` |
|
|
71
|
-
| [Discord](/docs/adapters/discord) | `@chat-adapter/discord` |
|
|
72
|
-
| [Telegram](/docs/adapters/telegram) | `@chat-adapter/telegram` |
|
|
73
|
-
| [GitHub](/docs/adapters/github) | `@chat-adapter/github` |
|
|
74
|
-
| [Linear](/docs/adapters/linear) | `@chat-adapter/linear` |
|
|
75
|
-
|
|
76
|
-
## Community adapters
|
|
77
|
-
|
|
78
|
-
Beyond the Vercel-maintained adapters listed above, you can build adapters for any messaging platform. Community adapters use the same `Adapter` interface and get full access to Chat SDK features like cards, actions, streaming, and state management.
|
|
79
|
-
|
|
80
|
-
| Tier | Description |
|
|
81
|
-
|------|-------------|
|
|
82
|
-
| Vercel-maintained | Published under `@chat-adapter/*` by Vercel |
|
|
83
|
-
| Community official | Built and maintained by the platform company itself (e.g., Resend building a Resend adapter) |
|
|
84
|
-
| Community | Built by third-party developers |
|
|
85
|
-
|
|
86
|
-
Community adapters are expected to meet the same testing bar as first-party adapters — unit tests for all public methods, integration tests for end-to-end message flows.
|
|
87
|
-
|
|
88
|
-
Ready to build one? Follow the [building](/docs/contributing/building) guide.
|
|
89
|
-
|
|
90
|
-
## How adapters work
|
|
91
|
-
|
|
92
|
-
Each adapter implements a standard interface that the `Chat` class uses to route events and send messages. When a webhook arrives:
|
|
93
|
-
|
|
94
|
-
1. The adapter verifies the request signature
|
|
95
|
-
2. Parses the platform-specific payload into a normalized `Message`
|
|
96
|
-
3. Routes to your handlers via the `Chat` class
|
|
97
|
-
4. Converts outgoing messages from markdown/AST/cards to the platform's native format
|
|
98
|
-
|
|
99
|
-
## Using multiple adapters
|
|
100
|
-
|
|
101
|
-
Register multiple adapters and your event handlers work across all of them:
|
|
102
|
-
|
|
103
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
104
|
-
import { Chat } from "chat";
|
|
105
|
-
import { createSlackAdapter } from "@chat-adapter/slack";
|
|
106
|
-
import { createTeamsAdapter } from "@chat-adapter/teams";
|
|
107
|
-
import { createGoogleChatAdapter } from "@chat-adapter/gchat";
|
|
108
|
-
import { createRedisState } from "@chat-adapter/state-redis";
|
|
109
|
-
|
|
110
|
-
const bot = new Chat({
|
|
111
|
-
userName: "mybot",
|
|
112
|
-
adapters: {
|
|
113
|
-
slack: createSlackAdapter(),
|
|
114
|
-
teams: createTeamsAdapter(),
|
|
115
|
-
gchat: createGoogleChatAdapter(),
|
|
116
|
-
},
|
|
117
|
-
state: createRedisState(),
|
|
118
|
-
});
|
|
119
|
-
|
|
120
|
-
// This handler fires for mentions on any platform
|
|
121
|
-
bot.onNewMention(async (thread) => {
|
|
122
|
-
await thread.subscribe();
|
|
123
|
-
await thread.post("Hello!");
|
|
124
|
-
});
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
Each adapter auto-detects credentials from environment variables, so you only need to pass config when overriding defaults.
|
|
128
|
-
|
|
129
|
-
Each adapter creates a webhook handler accessible via `bot.webhooks.slack`, `bot.webhooks.teams`, etc.
|