diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 8546721a..a8300316 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -258,6 +258,7 @@ export default defineConfig({ { text: 'Telegram', link: '/channels/telegram' }, { text: 'Lark / Feishu', link: '/channels/lark' }, { text: 'WhatsApp', link: '/channels/whatsapp' }, + { text: 'WhatsApp Business', link: '/channels/whatsapp-business' }, { text: 'WeCom', link: '/getting-started/channel-deployment#option-c-wecom-企业微信-deployment' }, { text: 'DingTalk', link: '/getting-started/channel-deployment#option-d-dingtalk-钉钉-deployment' }, { text: 'Slack', link: '/getting-started/channel-deployment#slack' }, @@ -442,6 +443,7 @@ export default defineConfig({ { text: 'Telegram', link: '/zh/channels/telegram' }, { text: 'Lark / 飞书', link: '/zh/channels/lark' }, { text: 'WhatsApp', link: '/zh/channels/whatsapp' }, + { text: 'WhatsApp Business', link: '/zh/channels/whatsapp-business' }, { text: '企业微信', link: '/zh/getting-started/channel-deployment#option-c-wecom-企业微信-deployment' }, { text: '钉钉', link: '/zh/getting-started/channel-deployment#option-d-dingtalk-钉钉-deployment' }, { text: 'Slack', link: '/zh/getting-started/channel-deployment#slack' }, diff --git a/docs/channels/index.md b/docs/channels/index.md index d4da18d5..8f85e9e5 100644 --- a/docs/channels/index.md +++ b/docs/channels/index.md @@ -9,6 +9,7 @@ Learn how to get the most out of each communication channel with your COCO AI em | [Telegram](./telegram) | International users, personal & team use | ✅ Available | | [Lark / Feishu](./lark) | Enterprise teams, document collaboration | ✅ Available | | [WhatsApp](./whatsapp) | International business, customer-facing | ✅ Available | +| [WhatsApp Business (Official API)](./whatsapp-business) | International business, official API, customer-facing at scale | ✅ Available | | [WeCom](../getting-started/channel-deployment#option-c-wecom-企业微信-deployment) | China enterprise teams | ✅ Available | | [DingTalk](../getting-started/channel-deployment#option-d-dingtalk-钉钉-deployment) | China enterprise teams | ✅ Available | | [Slack](../getting-started/channel-deployment#slack) | International teams, developer workflows | ✅ Available | diff --git a/docs/channels/whatsapp-business.md b/docs/channels/whatsapp-business.md new file mode 100644 index 00000000..88e44fb7 --- /dev/null +++ b/docs/channels/whatsapp-business.md @@ -0,0 +1,48 @@ +# WhatsApp Business (Official API) — Usage Tips + +Use your COCO AI employee on the official WhatsApp Business Platform (Cloud API) — a verified business number your customers can message from their everyday WhatsApp app. Built for customer-facing business messaging at scale. + +> New here? See the [WhatsApp Business Deployment guide](../getting-started/channel-deployment#whatsapp-business) to connect your business number first. + +> **WhatsApp Business vs. WhatsApp:** This channel uses Meta's **official Cloud API** — you verify a business phone number by OTP, with no phone or QR linking. The [WhatsApp](./whatsapp) channel links a regular WhatsApp account via QR code instead. Choose this one for official, customer-facing business use. + +## Basic Usage + +### Direct Messages +Customers send a message to your business number from their normal WhatsApp app — no special command needed. The first person to DM the number becomes the **Owner** with full access. + +### Group Chats +Not supported — the official WhatsApp Business Cloud API is **1:1 (DM) only**. If you need group chat support, use the [WhatsApp](./whatsapp) channel instead. + +## Best Use Cases + +### Customer-Facing Support +The official API is built for business-to-customer messaging: +- Answer FAQs and product questions instantly, around the clock +- Triage and route incoming requests +- Serve customers on the app they already use — no install needed + +### Official Business Presence +- Your business display name is shown to customers, backed by Meta's official platform +- No linked phone to keep online — the connection is server-to-server and stays up on its own +- Delivery and read status is tracked for outbound messages + +## Pro Tips + +**24-hour window**: WhatsApp allows freeform replies within 24 hours of the customer's last message. Outside that window, only pre-approved **template messages** can be sent — the AI employee handles this automatically. + +**Media in, media out**: Customers can send images, documents, audio, and video — the AI employee receives them and can reply with text, images, and documents. + +**Owner**: The first person to DM the business number becomes the Owner, who always has full access regardless of access settings. + +**Access control**: By default only the Owner can DM the number. Adjust the DM policy (owner / allowlist / open) to open it up to customers or a team. + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Bot not responding | Confirm the WhatsApp Business card shows **Connected** in the employee detail page, then send another message | +| Replies not arriving after a long pause | The 24-hour customer-service window has likely closed — send a new message from the customer side to reopen it | +| Can't add the bot to a group | Group chats are not supported by the official Cloud API — this channel is 1:1 only | +| Others can't message the bot | By default only the Owner can chat. Enable Allowlist or Open mode to grant access | +| Want to disconnect | Click the **Disconnect** button on the WhatsApp Business card in the employee detail page | diff --git a/docs/getting-started/channel-deployment.md b/docs/getting-started/channel-deployment.md index 0aa91337..03e0fb8f 100644 --- a/docs/getting-started/channel-deployment.md +++ b/docs/getting-started/channel-deployment.md @@ -15,6 +15,7 @@ Detailed guide for connecting your AI employee to Telegram or Lark. | WeCom (企业微信) | Available | Domestic enterprise users | | DingTalk (钉钉) | Available | Domestic teams, no public callback needed | | [WhatsApp](#whatsapp) | Available | International business users | +| [WhatsApp Business (Official API)](#whatsapp-business) | Available | International business, official Cloud API | | [Discord](#discord) | Available | Developer/community scenarios | | [Slack](#slack) | Available | European/US enterprise users | | [Microsoft Teams](#ms-teams) | Available | Enterprise teams, Microsoft 365 organizations | @@ -815,6 +816,8 @@ Your AI employee will automatically configure the Slack channel connection. > **Note:** WhatsApp connects via **QR code scanning** (linked device), similar to using WhatsApp Web. No API keys, developer accounts, or app configuration are needed — just a phone with WhatsApp installed. +> **Looking for the official WhatsApp Business API?** This option links a regular WhatsApp account by QR code. For a verified business number on Meta's official Cloud API (no QR or phone linking), see [WhatsApp Business (Official API)](#whatsapp-business). + ::: warning Use a Dedicated WhatsApp Account Please use a **newly registered, dedicated WhatsApp account** for the bot — do **not** use your personal WhatsApp account. The connected account will serve exclusively as the bot's number. ::: @@ -1457,3 +1460,61 @@ No credentials are required. Authentication is done entirely via QR code: | Want to disconnect | Click the **Disconnect** button on the Zalo Personal (Unofficial) card in the employee detail page | --> + +## Option L: WhatsApp Business (Official API) Deployment {#whatsapp-business} + +**Estimated time: ~5 minutes** + +> **Note:** This channel uses Meta's **official WhatsApp Business Platform (Cloud API)**. You bring a phone number, verify it with a one-time code right in the Dashboard, and COCO handles everything on the Meta side — no Meta developer account, API keys, or QR/phone linking needed. Prefer linking a regular WhatsApp account by QR code instead? See [WhatsApp](#whatsapp). + +No credentials are required. You only need: + +| Item | Description | +|------|-------------| +| COCO AI Employee | An existing instance in COCO Dashboard | +| Phone Number | A number that can receive an SMS or voice call, and is **not** currently registered on WhatsApp or another WhatsApp Business account | +| ~5 minutes | Time to complete deployment | + +### Step 1: Click Connect on the WhatsApp Business Card + +1. Log into [COCO Dashboard](https://icoco.ai/dashboard) and open the employee instance detail page +2. Find the **WhatsApp Business** card and click **Connect** + +### Step 2: Enter Your Phone Number and Display Name + +1. Enter the phone number you want to use, in international format (e.g. `+1 555 123 4567`) +2. Enter a **display name** — this is the business name your customers will see in WhatsApp +3. Check the preview carefully before continuing + +> **Important:** The display name is reviewed against Meta's display name policy and is **hard to change later** — choose it carefully. + +### Step 3: Verify with the One-Time Code + +1. Meta sends a **6-digit verification code** to your number via SMS (a voice call option is available if SMS doesn't arrive) +2. Enter the code in the wizard + +> **Mainland China numbers:** SMS delivery to +86 numbers can be unreliable — if the code doesn't arrive, use the **voice call** option. + +### Step 4: Deploy + +1. After the code is verified, the system registers your number and deploys the channel automatically — a progress indicator shows each step +2. When finished, the WhatsApp Business card shows **Connected** + +### Step 5: Start Chatting + +1. From any phone with WhatsApp, send a message to your business number +2. Your AI employee responds immediately — deployment complete! + +> **First message:** The first user to DM the business number becomes the **Owner** (administrator), who always has full access regardless of policy settings. + +### WhatsApp Business FAQ + +| Issue | Solution | +|-------|----------| +| Verification code never arrives | Wait a moment and retry, or choose the **voice call** option. SMS to mainland China (+86) numbers is often unreliable | +| "Number already in use" or verification fails | The number must not be registered on the WhatsApp consumer app or another WhatsApp Business account — remove it there first (WhatsApp → Settings → Account → Delete account), then retry | +| Closed the wizard before finishing | Your progress is saved — click **Connect** on the WhatsApp Business card again to resume where you left off | +| Can't use the bot in group chats | The official Cloud API is **1:1 (DM) only**. If you need group chats, use the [WhatsApp](#whatsapp) channel | +| No reply after a long silence | WhatsApp's **24-hour customer-service window** has closed — send a new message from the customer side to reopen it; outside the window only pre-approved template messages can be sent | +| Others can't message the bot | By default only the Owner can chat. Enable Allowlist or Open mode to grant access | +| Want to disconnect | Click the **Disconnect** button on the WhatsApp Business card in the employee detail page | diff --git a/docs/zh/channels/index.md b/docs/zh/channels/index.md index 745163f2..08d6986b 100644 --- a/docs/zh/channels/index.md +++ b/docs/zh/channels/index.md @@ -9,6 +9,7 @@ | [Telegram](./telegram) | 国际用户、个人及团队使用 | ✅ 可用 | | [Lark / 飞书](./lark) | 企业团队、文档协作 | ✅ 可用 | | [WhatsApp](./whatsapp) | 国际业务、面向客户的场景 | ✅ 可用 | +| [WhatsApp Business(官方 API)](./whatsapp-business) | 国际业务、官方 API、规模化客户服务 | ✅ 可用 | | [企业微信](../getting-started/channel-deployment#option-c-wecom-企业微信-deployment) | 国内企业团队 | ✅ 可用 | | [钉钉](../getting-started/channel-deployment#option-d-dingtalk-钉钉-deployment) | 国内企业团队 | ✅ 可用 | | [Slack](../getting-started/channel-deployment#slack) | 国际团队、开发者工作流 | ✅ 可用 | diff --git a/docs/zh/channels/whatsapp-business.md b/docs/zh/channels/whatsapp-business.md new file mode 100644 index 00000000..e50f7aba --- /dev/null +++ b/docs/zh/channels/whatsapp-business.md @@ -0,0 +1,48 @@ +# WhatsApp Business(官方 API)— 使用技巧 + +在官方 WhatsApp Business Platform(Cloud API)上使用 COCO AI 员工——一个经过验证的企业号码,客户直接用日常使用的 WhatsApp 应用就能联系你。专为规模化的企业客户消息场景打造。 + +> 第一次使用?请先查看 [WhatsApp Business 部署指南](../getting-started/channel-deployment#whatsapp-business) 连接你的企业号码。 + +> **WhatsApp Business 与 WhatsApp 的区别:** 本渠道使用 Meta 的**官方 Cloud API**——通过 OTP 验证码验证一个企业电话号码,无需手机扫码或设备关联。而 [WhatsApp](./whatsapp) 渠道是通过二维码关联一个普通 WhatsApp 账号。面向客户的正式商务场景请选择本渠道。 + +## 基本使用 + +### 私信 +客户用普通 WhatsApp 应用给你的企业号码发送消息即可——无需特殊命令。第一个给该号码发私信的用户会成为 **Owner(管理员)**,拥有完整访问权限。 + +### 群聊 +不支持——官方 WhatsApp Business Cloud API 仅支持 **1:1 私信**。如需群聊支持,请改用 [WhatsApp](./whatsapp) 渠道。 + +## 适用场景 + +### 面向客户的支持 +官方 API 专为企业对客户(B2C)消息场景设计: +- 全天候即时回答常见问题和产品咨询 +- 对收到的请求进行分流和路由 +- 在客户已经在用的应用上提供服务——无需安装任何东西 + +### 官方商务形象 +- 客户会看到你的企业显示名称,背靠 Meta 官方平台 +- 无需保持任何手机在线——连接是服务器对服务器的,自行保持稳定 +- 出站消息的送达和已读状态会被跟踪 + +## 进阶技巧 + +**24 小时窗口**:WhatsApp 允许在客户最后一条消息后的 24 小时内自由回复。超出该窗口后,只能发送预先审核通过的**模板消息**——AI 员工会自动处理这一逻辑。 + +**媒体收发**:客户可以发送图片、文档、音频和视频——AI 员工能接收它们,并可回复文字、图片和文档。 + +**Owner(管理员)**:第一个给企业号码发私信的用户将成为 Owner,始终拥有完整访问权限,不受访问设置限制。 + +**访问控制**:默认只有 Owner 能私信该号码。可调整私信策略(owner / allowlist / open),向客户或团队开放。 + +## 故障排除 + +| 问题 | 解决方案 | +|------|---------| +| 机器人无响应 | 确认员工详情页的 WhatsApp Business 卡片显示为**已连接**,然后再发送一条消息 | +| 长时间未联系后收不到回复 | 24 小时客服窗口可能已关闭——由客户一侧发送一条新消息即可重新打开窗口 | +| 无法把机器人拉进群 | 官方 Cloud API 不支持群聊——本渠道仅支持 1:1 私信 | +| 其他人无法和机器人聊天 | 默认只有 Owner 可以聊天。启用 Allowlist 或 Open 模式以开放访问权限 | +| 想要断开连接 | 在员工详情页的 WhatsApp Business 卡片上点击**断开连接**按钮 | diff --git a/docs/zh/getting-started/channel-deployment.md b/docs/zh/getting-started/channel-deployment.md index f2bdc1d3..0af3ea6f 100644 --- a/docs/zh/getting-started/channel-deployment.md +++ b/docs/zh/getting-started/channel-deployment.md @@ -17,6 +17,7 @@ import { withBase } from 'vitepress' | [企业微信](#wecom) | 已支持 | 国内企业用户首选 | | [钉钉](#dingtalk) | 已支持 | 国内团队协作,无需公网回调 | | [WhatsApp](#whatsapp) | 已支持 | 海外商务用户 | +| [WhatsApp Business(官方 API)](#whatsapp-business) | 已支持 | 国际业务、官方 Cloud API | | [Discord](#discord) | 已支持 | 开发者/社区场景 | | [Slack](#slack) | 已支持 | 欧美企业用户 | | [Microsoft Teams](#ms-teams) | 已支持 | 企业团队、Microsoft 365 组织 | @@ -947,6 +948,8 @@ AI 员工会自动完成 Slack 渠道的连接配置。 > **说明:** WhatsApp 通过**扫码关联设备**方式接入,无需 API 密钥、开发者账号或应用配置。 +> **在找官方 WhatsApp Business API?** 本选项通过二维码关联一个普通 WhatsApp 账号。如需在 Meta 官方 Cloud API 上使用经过验证的企业号码(无需扫码或关联手机),请查看 [WhatsApp Business(官方 API)](#whatsapp-business)。 + ::: danger 重要提醒:必须使用新的专属号码 为了让这个 AI 员工像独立 Bot 一样正常使用,请务必绑定一个**新的、专属的 WhatsApp 号码**。 @@ -1561,3 +1564,61 @@ LINE 通过两个凭证连接——**Channel Access Token**(通道访问令牌 | 想要断开连接 | 在员工详情页的 Zalo 个人版(非官方) 卡片上点击 **断开连接** 按钮 | --> + +## 选项M:WhatsApp Business(官方 API)部署 {#whatsapp-business} + +**预计用时:约5分钟** + +> **说明:** 本渠道使用 Meta **官方 WhatsApp Business Platform(Cloud API)**。你只需提供一个电话号码,在 Dashboard 中用一次性验证码完成验证,Meta 侧的所有配置由 COCO 代为处理——无需 Meta 开发者账号、API 密钥,也无需扫码或关联手机。想通过二维码关联普通 WhatsApp 账号?请查看 [WhatsApp](#whatsapp)。 + +无需填写凭证,只需准备: + +| 所需项目 | 说明 | +|----------|------| +| COCO AI 员工 | COCO Dashboard 中已创建的实例 | +| 电话号码 | 一个能接收短信或语音电话的号码,且**未**注册过 WhatsApp 或其他 WhatsApp Business 账号 | +| 约5分钟 | 完成部署所需时间 | + +### 第1步:点击 WhatsApp Business 卡片的「连接」 + +1. 登录 [COCO Dashboard](https://icoco.ai/dashboard),进入员工实例详情页 +2. 找到 **WhatsApp Business** 卡片,点击 **连接** + +### 第2步:输入电话号码和显示名称 + +1. 按国际格式输入你要使用的电话号码(例如 `+86 130 xxxx xxxx`) +2. 输入**显示名称**——这是客户在 WhatsApp 中看到的企业名称 +3. 继续之前请仔细核对预览效果 + +> **重要:** 显示名称需符合 Meta 的显示名称政策,且**之后很难更改**——请谨慎选择。 + +### 第3步:输入一次性验证码 + +1. Meta 会通过短信向你的号码发送一个 **6 位验证码**(如果短信收不到,可选择语音电话方式) +2. 在向导中输入验证码 + +> **中国大陆号码:** 发往 +86 号码的短信可能不稳定——如果收不到验证码,请使用**语音电话**方式。 + +### 第4步:部署 + +1. 验证码通过后,系统会自动注册你的号码并部署渠道——进度指示器会展示每一步 +2. 完成后,WhatsApp Business 卡片显示为**已连接** + +### 第5步:开始聊天 + +1. 用任意一台装有 WhatsApp 的手机,给你的企业号码发送一条消息 +2. AI 员工会立即响应——部署完成! + +> **首条消息:** 第一个给企业号码发私信的用户将成为 **Owner(管理员)**,无论权限设置如何始终拥有完整访问权限。 + +### WhatsApp Business 常见问题 + +| 问题 | 解决方案 | +|------|---------| +| 收不到验证码 | 稍等后重试,或选择**语音电话**方式。发往中国大陆(+86)号码的短信经常不稳定 | +| 提示「号码已被使用」或验证失败 | 该号码不能已注册在 WhatsApp 消费者应用或其他 WhatsApp Business 账号上——请先在原处注销(WhatsApp → 设置 → 账号 → 删除账号),然后重试 | +| 向导中途关闭了 | 进度已保存——再次点击 WhatsApp Business 卡片上的**连接**即可从中断处继续 | +| 无法在群聊中使用 | 官方 Cloud API 仅支持 **1:1 私信**。如需群聊,请使用 [WhatsApp](#whatsapp) 渠道 | +| 长时间未联系后收不到回复 | WhatsApp 的 **24 小时客服窗口**已关闭——由客户一侧发送一条新消息即可重新打开;窗口外只能发送预先审核通过的模板消息 | +| 其他人无法和机器人聊天 | 默认只有 Owner 可以聊天。启用 Allowlist 或 Open 模式以开放访问权限 | +| 想要断开连接 | 在员工详情页的 WhatsApp Business 卡片上点击**断开连接**按钮 |