在一个收件箱中
连接所有渠道。

§ 00您需要准备的

每个渠道需要 5–20 分钟来接入。您将在两个地方进行操作:渠道自己的开发者控制台(Telegram 的 BotFather、Meta 的 Developer Dashboard)以及您 EasyLiveChat 工作区内的 Channels 页面 app.livechattools.com/channels.

在 EasyLiveChat 中,四个渠道共享同一架构 —— 每个联系人一个归一化的 Conversation、一个收件箱、一个回复框。差异在于每个 provider 所需的凭证以及其 webhook 签名方案。

§ 01Telegram

最简单的渠道。Telegram 不需要开发者应用或商业账号 —— 只需要一个 bot。Bot tokens 永久有效,整个 integration 大约需要 5 分钟。

1. 用 BotFather 创建 bot

打开 Telegram 并与下面对话 @BotFather. 发送 /newbot,选择一个显示名称和一个以下面结尾的用户名 bot. BotFather 回复一个形如下面的 token 1234567890:ABCdefGHI…. 复制它。

2. 在 EasyLiveChat 中接入

在工作区中进入 Channels → Telegram Bot → Connect。粘贴 bot token。选择任意显示名称 —— 只在收件箱内显示。提交。

在新建的行上打开 Integration settings,以显示 Webhook secret 和该 integration 的 callback URL。

3. 让 Telegram 指向我们的 webhook

Telegram Bot API 没有 webhook 的 UI;通过下面设置 setWebhook. 把下面的占位符替换为您的 bot token、integration ID 和 webhook secret,然后运行一次:

curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.livechattools.com/api/channels/webhook/telegram/${INTEGRATION_ID}",
    "secret_token": "${WEBHOOK_SECRET}",
    "allowed_updates": ["message", "edited_message"]
  }'

Telegram 返回 {"ok":true,"description":"Webhook was set"}. 。用下面验证 getWebhookInfo — —— pending_update_count 应当下降到 0。

4. 测试

在 Telegram 中打开 t.me/yourbot_username,点击 Start,发送任意消息。应当在不到一秒内出现在您的 EasyLiveChat 收件箱中,带有发送者的名称和语言代码。从面板回复 —— 不久后会到达访客的 Telegram。

§ 02WhatsApp Cloud

Meta Cloud API 对几乎所有人来说都是正确的选择 —— 完全托管、每月最多 1,000 次 service conversation 免费,且是唯一不需要您一侧任何基础设施的 WhatsApp 通道。设置比 Telegram 复杂,因为 Meta 要求 production 流量必须有开发者应用和已验证的 business portfolio。

1. 创建 Meta 开发者应用

前往 developers.facebook.com/apps → Create App。选择名称、邮箱,然后在下一屏选择使用场景 “Connect with customers through WhatsApp”。关联一个 Business Portfolio —— 已有的或 Meta 内置的 Test Business 用于评估。

应用创建后,打开 Use Cases → Connect on WhatsApp → API Setup。您会看到一个 Phone Number ID(Meta 免费提供的测试号码,或您添加后自己的)以及 Generate access token 按钮。点击它,授权,并复制得到的 token。同时复制 Phone Number ID。

2. 获取 App Secret

在同一 Meta 面板中,打开 App settings → Basic。App Secret 隐藏在 Show 按钮后面 —— 显示并复制。这是 Meta 用来对每个 webhook POST 进行签名的 HMAC 密钥。没有它,您的入站消息将被拒绝为 BAD_SIGNATURE.

3. 在 EasyLiveChat 中接入 WhatsApp

Channels → WhatsApp Cloud → Connect。填写显示名称(自由)、Phone Number ID、Access Token 和 App Secret。提交。打开 integration 设置以复制自动生成的 webhook secret 和 integration ID。

4. 配置 Meta 的 webhook

回到 Meta 面板,前往 Use Cases → Connect on WhatsApp → Configuration。粘贴:

Callback URL : https://api.livechattools.com/api/channels/webhook/whatsapp/${INTEGRATION_ID}
Verify token : ${WEBHOOK_SECRET}

点击 Verify and save。Meta 发送 GET 握手 —— 如果 verify token 匹配我们会回显其 challenge。在同一页面找到 Webhook fields 列表,把 messages 切换为 Subscribed。没有这个切换,Meta 接受 webhook URL 但永远不会向其投递任何内容。

5. 添加测试收件人(仅 sandbox)

如果您使用 Meta 的免费测试号码,在发送之前必须把每个收件人列入白名单。在 API Setup → To 中添加您要发送的电话号码 —— Meta 会发送 6 位 OTP 短信进行验证。最多可列入五位测试收件人。真实的 business 号码没有这个限制。

§ 03Facebook Messenger

Messenger 使用与 WhatsApp 相同的 Meta App、App Secret 和 webhook 管道 —— 但它面向的是 Facebook Page 而非电话号码,access token 是 Page Access Token,而不是 WhatsApp Business token。

1. 将 Messenger 添加到您的 Meta app

在您用于 WhatsApp 的同一应用(或新建一个)中,打开 Use cases → Add use cases → Business messaging 过滤 → Engage with customers on Messenger from Meta。保存。该应用现在并排有两个产品。

2. 连接 Facebook Page

打开 Messenger from Meta → Messenger API Settings。在 Generate access tokens 下,点击 No FB pages yet 旁的 Connect。Meta 询问要授权哪些 Page —— 选择您希望接收消息的页面,接受权限,保存。

页面现在以一键 Page Access Token 和 Page ID 显示。两者都复制。Page ID 也是您在 EasyLiveChat 中粘贴为 pageId 的值。

3. 在 EasyLiveChat 中接入 Messenger

Channels → Messenger → Connect。填写 Page ID、Page Access Token,以及您用于 WhatsApp 的同一个 App Secret。提交并复制新 integration 的 webhook secret + ID。

4. 双层 webhook 订阅

Messenger 有一个 WhatsApp 没有的怪癖:需要两个订阅才能投递任何内容。先做应用级订阅 —— 在 Messenger API Settings → Configure webhooks 中粘贴:

Callback URL : https://api.livechattools.com/api/channels/webhook/messenger/${INTEGRATION_ID}
Verify token : ${WEBHOOK_SECRET}

点击 Verify and save,然后展开 Webhook fields 并启用 messages。然后是 Page 级订阅,UI 无法完成 —— 运行此 curl:

curl -X POST "https://graph.facebook.com/v20.0/${PAGE_ID}/subscribed_apps" \
  -d "subscribed_fields=messages,messaging_postbacks,message_deliveries,message_reads" \
  -d "access_token=${PAGE_ACCESS_TOKEN}"

没有 Page 级订阅,Meta 在应用订阅上返回 {"success":true} 但实际上永远不会触发 webhook。可以通过查询确认一切已连通:

curl "https://graph.facebook.com/v20.0/${APP_ID}/subscriptions?access_token=${APP_ID}|${APP_SECRET}"

响应应当列出一个类型为 page 的对象,其 fields 数组非空,包含 messages.

§ 04Instagram DM

Instagram 消息走的是与 Messenger Platform 相同的管道,但增加了两个要求:Instagram 账号必须是 Business 账号(不是个人或 Creator),并且必须连接到同一 Business Portfolio 中的一个 Facebook Page。两者都满足时,您的 Page Access Token 也就是您的 Instagram access token。

1. 将 IG 账号转换为 Business

在 Instagram 移动 app:Settings → Account → Switch to professional account → Business。选择任意类别。该转换可逆。

2. 将 IG 账号添加到 Business Portfolio

在 Meta Business Suite Settings → Accounts → Instagram accounts → Add → 用 IG 凭据登录。Meta 确认后显示 IG 账号的 Instagram Business Account ID —— 一个以下面开头的 17 位数字 1784…. 复制它;这是您 EasyLiveChat integration 的 pageId 。

3. 把 IG 链接到 Facebook Page

这是最常被遗漏的一步。在 Meta Business Suite 中打开 Facebook Page 的 Inbox —— business.facebook.com/latest/inbox?asset_id={page_id}. 顶部横幅写着 “Connect to Instagram” 并附 Connect 按钮。点击它,登录 Instagram,授予所请求的权限,确认。此后,Meta 的 Graph API 将开始回答关于 IG 账号的查询,作用域为 Page 的 access token。

4. 在 EasyLiveChat 中接入 Instagram

Channels → Instagram DM → Connect。把步骤 2 中的 IG Business Account ID 用作 pageId,您用于 Messenger 的同一个 Page Access Token 用作 pageAccessToken,以及与之前相同的 App Secret。

5. 在两层都订阅

Instagram 在应用级 webhook 中使用 object=instagram (Messenger 使用 object=page. )。在您已有的 Messenger 订阅之上加上这个 curl:

curl -X POST "https://graph.facebook.com/v20.0/${APP_ID}/subscriptions" \
  -d "object=instagram" \
  -d "callback_url=https://api.livechattools.com/api/channels/webhook/instagram/${INTEGRATION_ID}" \
  -d "verify_token=${WEBHOOK_SECRET}" \
  -d "fields=messages,messaging_postbacks,message_reactions" \
  -d "access_token=${APP_ID}|${APP_SECRET}"

§ 05故障排查