feat(wechat): add wechat integration

integrations/wechat-entree/definitions/channels.ts

@@ -0,0 +1,36 @@
+import { messages } from '@botpress/sdk'
+
+const _textMessageDefinition = {
+  ...messages.defaults.text,
+  schema: messages.defaults.text.schema.extend({
+    text: messages.defaults.text.schema.shape.text
+      .max(4096)
+      .describe('The text content of the WeChat message (Limit 4096 characters)'),
+  }),
+}
+
+// ============== FOR FUTURE USE ==============
+// const _imageMessageDefinition = {
+//   ...messages.defaults.image,
+//   schema: messages.defaults.image.schema.extend({
+//     caption: z.string().optional().describe('The caption/description of the image'),
+//   }),
+// }
+
+// const _audioMessageDefinition = {
+//   ...messages.defaults.audio,
+//   schema: messages.defaults.audio.schema.extend({
+//     caption: z.string().optional().describe('The caption/transcription of the audio message'),
+//   }),
+// }
+// =============================================
+
+const _imageMessageDefinition = {
+  ...messages.defaults.image,
+}
+
+export const wechatMessageChannels = {
+  text: _textMessageDefinition,
+  image: _imageMessageDefinition,
+  video: messages.defaults.video,
+}

integrations/wechat-entree/hub.md

@@ -0,0 +1,132 @@
+# WeChat Official Account Integration
+
+Connect your Botpress chatbot to WeChat Official Accounts and engage with your Chinese audience in real-time.
+
+## Prerequisites
+
+Before you begin, you need:
+
+1. **WeChat Official Account** (Service Account or Subscription Account)
+   - Create one at: https://mp.weixin.qq.com/
+2. **App ID and App Secret** from your WeChat Official Account settings
+3. **Server Configuration** enabled in WeChat Admin Panel
+
+## Configuration
+
+### 1. Get Your WeChat Credentials
+
+In your WeChat Official Account admin panel:
+
+1. Go to **Settings & Development** > **Basic Configuration**
+2. Copy your **AppID** and **AppSecret**
+3. Generate a **Token** (any random string, you'll use this in both WeChat and Botpress)
+
+### 2. Install the Integration in Botpress
+
+1. Install this integration in your Botpress workspace
+2. Configure with your credentials:
+   - **WeChat Token**: The token you generated (used for signature verification)
+   - **App ID**: Your WeChat Official Account AppID
+   - **App Secret**: Your WeChat Official Account AppSecret
+
+### 3. Configure WeChat Webhook
+
+In your WeChat Official Account admin panel:
+
+1. Go to **Settings & Development** > **Basic Configuration**
+2. Click **Enable** Server Configuration
+3. Set the **URL** to your Botpress webhook URL (provided after integration installation)
+4. Set the **Token** to the same token you used in Botpress configuration
+5. Select **Message Encryption Method**: Plain Text (recommended for testing)
+6. Click **Submit** - WeChat will verify your server
+
+## Supported Features
+
+### Receiving Messages
+
+Your bot can receive the following message types from WeChat users:
+
+- **Text messages** - Plain text messages
+- **Image messages** - Photos sent by users (PicUrl provided)
+- **Voice messages** - Audio messages with optional speech recognition
+- **Video messages** - Video content
+- **Location messages** - User location with latitude, longitude, and label
+- **Link messages** - Shared links with title, description, and URL
+
+### Sending Messages
+
+Your bot can send the following message types to WeChat users:
+
+- **Text messages** - Up to 4,096 characters
+- **Image messages** - Images (automatically uploaded to WeChat)
+- **Audio/Voice messages** - Audio files (automatically uploaded to WeChat)
+- **Video messages** - Video files (automatically uploaded to WeChat)
+- **Card messages** - Rich cards with title, image, and link (sent as WeChat News)
+- **Carousel messages** - Multiple cards (up to 8 articles)
+- **Choice/Dropdown messages** - Formatted as text with numbered options
+
+## How It Works
+
+1. **User sends message** → WeChat forwards it to your Botpress webhook
+2. **Botpress processes** → Your bot logic analyzes and generates response
+3. **Bot sends reply** → Via WeChat Customer Service API (asynchronous)
+
+This integration uses WeChat's **Customer Service API** which allows:
+
+- ✅ Sending messages anytime (not limited to 5-second window)
+- ✅ Multiple messages per user interaction
+- ✅ Asynchronous bot processing (perfect for AI/LLM responses)
+
+## Limitations
+
+### WeChat Platform Limitations
+
+- **Official Account Required**: Personal WeChat accounts cannot be used
+- **Customer Service API Window**: Can only send messages to users who have messaged you within the last 48 hours
+- **Message Frequency**: Rate limits apply (typically 100 messages/second)
+- **Media Upload**: Images/videos/audio must be uploaded to WeChat servers first (handled automatically)
+- **Message Length**: Text messages limited to 4,096 characters
+- **Carousel Limit**: Maximum 8 articles per carousel message
+
+### Integration Limitations
+
+- **No Proactive Messaging**: Cannot initiate conversations; users must message first
+- **Interactive Elements**: WeChat doesn't support buttons/quick replies natively (rendered as text with numbers)
+- **File Messages**: Generic file sending not fully supported by WeChat Customer Service API
+
+## Troubleshooting
+
+### Webhook Verification Fails
+
+- Ensure your **Token** matches exactly in both Botpress and WeChat
+- Check that your webhook URL is publicly accessible
+- Verify the URL ends with your integration webhook path
+
+### Messages Not Appearing in Botpress
+
+- Check your WeChat Admin Panel logs for delivery errors
+- Verify your **App ID** and **App Secret** are correct
+- Ensure Server Configuration is enabled in WeChat
+
+### Bot Not Responding
+
+- Check Botpress logs for errors
+- Verify the user messaged you within the last 48 hours
+- Ensure your bot flow is properly configured
+
+## Changelog
+
+### v1.0.2 (Current)
+
+- ✅ Full message type support (text, image, audio, video, location, link)
+- ✅ WeChat Customer Service API integration for sending messages
+- ✅ Automatic media upload to WeChat servers
+- ✅ Signature verification for secure webhook handling
+- ✅ Rich message support (cards, carousels)
+- ✅ Comprehensive error handling and logging
+
+## Additional Resources
+
+- [WeChat Official Account Platform Docs](https://developers.weixin.qq.com/doc/offiaccount/en/Getting_Started/Overview.html)
+- [WeChat API Reference](https://developers.weixin.qq.com/doc/offiaccount/en/Message_Management/Receiving_standard_messages.html)
+- [Botpress Documentation](https://botpress.com/docs)

integrations/wechat-entree/integration.definition.ts

@@ -0,0 +1,49 @@
+import { z, IntegrationDefinition } from '@botpress/sdk'
+import { wechatMessageChannels } from './definitions/channels'
+export default new IntegrationDefinition({
+  name: 'plus/WeChat',
+  version: '1.0.2',
+  title: 'WeChat',
+  description: 'Engage with your WeChat audience in real-time.',
+  icon: 'icon.svg',
+  readme: 'hub.md',
+  configuration: {
+    schema: z.object({
+      wechatToken: z
+        .string()
+        .trim()
+        .min(1)
+        .describe('Token used for WeChat signature verification')
+        .title('WeChat Token'),
+      appId: z.string().trim().min(1).describe('WeChat Official Account App ID').title('App ID'),
+      appSecret: z.string().trim().min(1).describe('WeChat Official Account App Secret').title('App Secret'),
+    }),
+  },
+  channels: {
+    channel: {
+      title: 'Channel',
+      description: 'WeChat Channel',
+      messages: wechatMessageChannels,
+      message: {
+        tags: {
+          id: { title: 'ID', description: 'The message ID' },
+          chatId: { title: 'Chat ID', description: 'The message chat ID' },
+        },
+      },
+      conversation: {
+        tags: {
+          id: { title: 'ID', description: 'The conversation ID' },
+          fromUserId: { title: 'WeChat User ID', description: 'The conversation WeChat user ID' },
+          chatId: { title: 'Chat ID', description: 'The conversation chat ID' },
+        },
+      },
+    },
+  },
+  actions: {},
+  events: {},
+  user: {
+    tags: {
+      id: { title: 'ID', description: 'The ID of the user' },
+    },
+  },
+})

integrations/wechat-entree/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@bp-templates/empty-integration",
+  "integrationName": "plus/WeChat",
+  "scripts": {
+    "check:type": "tsc --noEmit"
+  },
+  "private": true,
+  "dependencies": {
+    "@botpress/client": "1.27.1",
+    "@botpress/sdk": "4.21.0",
+    "prettier": "^3.6.2"
+  },
+  "devDependencies": {
+    "@botpress/cli": "4.27.4",
+    "@botpress/sdk": "4.21.0",
+    "@types/node": "^22.16.4",
+    "typescript": "^5.6.3"
+  }
+}