Files

T

rogee 0dabb8cfa5 docs: 整理文档目录结构 — 清理过时文档、归集功能子目录、统一命名规范

清理:
- 删除 34 份过时文档（gap reports/QA临时报告/验收报告/阶段性文档）
- 删除 docs/.hermes/skills 第三方 skills 副本（16 文件）
- 删除 skills-lock.json

目录归集:
- 根目录仅保留 README.md 索引
- product/ — 产品与架构设计（PRD + ARCHITECTURE + P2设计文档 + AI/企业路线图）
- tracking/ — Chatwoot parity 开发跟踪
- requirements/ — M01-M12 模块需求
- plans/ — 历史实现计划
- parity/ — 路由 parity 与前端契约
- qa/ — QA 报告与测试计划
- ops/ — 运维部署

命名规范:
- 全小写 kebab-case，禁止全大写文件名
- product/tracking/ops 用 NN- 序号前缀
- requirements 用 MNN- 两位零填充模块号
- plans/qa 用 YYYY-MM-DD- 日期前缀
- requirements M1-M9 零填充为 M01-M09（修复字典序）

同步更新:
- backend/cmd/route_parity/main.go 路径默认值
- backend/scripts/parity_frontend_smoke.sh 报告路径
- 所有 docs 内部交叉引用
- .gitignore 排除编译产物 (backend/gochat, backend/route_parity)
- 新增迁移 000052/000053
- 前端 WS 相关修改

2026-07-09 14:53:27 +08:00

38 KiB

Raw Blame History

M2 Inbox与渠道管理功能梳理文档

参照仓库：chatwoot-reference
产出日期：2026-05-22
版本基准：Chatwoot v3.x

Inbox CRUD + 设置 + 品牌
InboxMember绑定
Channelable多渠道模式
WebWidget渠道
Telegram渠道
Facebook / Instagram渠道
WhatsApp渠道
Email渠道
Twilio SMS / WhatsApp渠道
其他渠道（SMS、Line、Twitter、TikTok、API）
Webhook回调（外部事件推送）
OAuth刷新 / Reauthorizable
企业版InboxCapacity

1. Inbox CRUD + 设置 + 品牌

功能描述

Inbox（收件箱）是 Chatwoot 的核心聚合单元，代表一个对外沟通渠道的入口。每个 Inbox 绑定一个多态 Channel 对象（channel_type + channel_id），并拥有独立的设置：自动分配、工作时间、CSAT 调查、欢迎语、离线消息、品牌名等。

用户操作流程

创建 Inbox：管理员进入 Settings → Inboxes → 点击 "Add Inbox"，选择渠道类型（WebWidget/Telegram/WhatsApp等），填写渠道配置，系统自动创建 Channel + Inbox
查看 Inbox 列表：按账户加载所有 Inbox（含 channel、portal、working_hours、avatar）
更新 Inbox 设置：修改名称、欢迎语、工作时间、CSAT、自动分配、品牌名、时区等；同时可更新底层 Channel 的属性
删除 Inbox：级联删除 Channel、InboxMember、Conversation、ContactInbox、Campaign 等
查看可分配 Agent：获取 Inbox 的 assignable_agents（成员 + 管理员）
设置/移除 Agent Bot：为 Inbox 关联一个 AgentBot（AI/自动回复机器人）
上传/移除 Avatar：Inbox 支持头像（ActiveStorage attachment）

涉及的API端点

方法	路径	说明
GET	`/api/v1/accounts/{account_id}/inboxes`	列出所有 Inbox
POST	`/api/v1/accounts/{account_id}/inboxes`	创建 Inbox（含 channel 参数）
GET	`/api/v1/accounts/{account_id}/inboxes/{id}`	查看单个 Inbox
PATCH/PUT	`/api/v1/accounts/{account_id}/inboxes/{id}`	更新 Inbox 设置 + Channel 属性
DELETE	`/api/v1/accounts/{account_id}/inboxes/{id}`	删除 Inbox
GET	`/api/v1/accounts/{account_id}/inboxes/{id}/assignable_agents`	(已废弃) 可分配 Agent
GET	`/api/v1/accounts/{account_id}/inboxes/{id}/campaigns`	Inbox 下的 Campaign
POST	`/api/v1/accounts/{account_id}/inboxes/{id}/avatar`	移除头像
POST	`/api/v1/accounts/{account_id}/inboxes/{id}/set_agent_bot`	设置 Agent Bot

涉及的数据模型 + 关键字段

Inbox (inboxes 表)
- id, name (必填), account_id (必填), channel_type (多态类型), channel_id (多态ID)
- enable_auto_assignment (默认 true), enable_email_collect (默认 true)
- greeting_enabled, greeting_message, out_of_office_message
- working_hours_enabled (默认 false), timezone (默认 "UTC")
- csat_survey_enabled (默认 false), csat_config (jsonb: display_type/message/button_text/language/survey_rules)
- allow_messages_after_resolved (默认 true)
- lock_to_single_conversation (默认 false)
- sender_name_type (enum: friendly=0 / professional=1)
- business_name, email_address, auto_assignment_config (jsonb)
- portal_id (关联帮助中心 Portal)
- 关联: has_many :inbox_members, has_many :contact_inboxes, has_many :conversations, has_many :campaigns, has_one :agent_bot_inbox, has_one :inbox_assignment_policy, has_many :webhooks, has_many :working_hours, belongs_to :channel (多态, dependent: :destroy)
WorkingHour (working_hours 表)
- inbox_id, day_of_week, open_hour, open_minutes, close_hour, close_minutes
- closed_all_day, open_all_day
AgentBotInbox (agent_bot_inboxes 表)
- inbox_id, agent_bot_id, account_id, status (active/inactive)

涉及的业务逻辑（service层）

InboxesController#create → 事务中先创建 Channel 再创建 Inbox
InboxesController#update → 更新 Inbox 参数 + update_inbox_working_hours + update_channel（如果 channel 参数存在）
InboxesHelper#validate_email_channel → 验证 IMAP/SMTP 连接
OutOfOffisable concern → out_of_office? / working_now? / create_default_working_hours / update_working_hours
InboxAgentAvailability concern → available_agents（基于 OnlineStatusTracker 筛选在线成员）

涉及的自动化/规则/事件

after_create_commit :dispatch_create_event → 发布 INBOX_CREATED 事件
after_update_commit :dispatch_update_event → 发布 INBOX_UPDATED 事件
after_destroy :delete_round_robin_agents → 清除 Redis Round Robin 队列
validate_limit → 创建前检查账户 Inbox 数量上限（企业版有更细粒度限制）

Chatwoot原实现关键代码文件路径

app/models/inbox.rb
app/models/concerns/out_of_offisable.rb
app/models/concerns/inbox_agent_availability.rb
app/models/working_hour.rb
app/models/agent_bot_inbox.rb
app/controllers/api/v1/accounts/inboxes_controller.rb
app/helpers/api/v1/inboxes_helper.rb
app/views/api/v1/accounts/inboxes/*.json.jbuilder

版本标注：社区版 / 企业版

社区版：Inbox CRUD、工作时间、CSAT、AgentBot、Avatar、基本数量限制
企业版：Inbox数量精确限制（PlanUsageAndLimits）、InboxCapacityLimits、Captain Assistant绑定、CSAT模板

2. InboxMember绑定

功能描述

InboxMember 将 User（客服/Agent）绑定到 Inbox，形成「哪些Agent可以处理该收件箱的对话」的关系。创建/删除 InboxMember 会自动维护 Round Robin 队列。

用户操作流程

查看 Inbox 成员：进入 Inbox Settings → 查看已绑定的 Agent 列表
添加成员：选择 Agent 添加到 Inbox，触发 Round Robin 入队
批量更新成员：传入完整 user_ids 列表，自动计算增量（新增/移除）
移除成员：从 Inbox 中移除 Agent，触发 Round Robin 出队
Widget端查看成员：前端 Widget 可查询 Inbox 的在线成员列表

涉及的API端点

方法	路径	说明
GET	`/api/v1/accounts/{account_id}/inbox_members/{inbox_id}`	查看成员列表
POST	`/api/v1/accounts/{account_id}/inbox_members/{inbox_id}`	添加成员
PATCH/PUT	`/api/v1/accounts/{account_id}/inbox_members/{inbox_id}`	批量更新成员
DELETE	`/api/v1/accounts/{account_id}/inbox_members/{inbox_id}`	移除成员
GET	`/api/v1/widget/inbox_members`	Widget端查看成员（公开）

涉及的数据模型 + 关键字段

InboxMember (inbox_members 表)
- id, inbox_id (必填), user_id (必填)
- 联合唯一索引: (inbox_id, user_id)
- belongs_to :inbox, belongs_to :user

涉及的业务逻辑（service层）

InboxMembersController → 调用 @inbox.add_members(user_ids) / @inbox.remove_members(user_ids)
Inbox#add_members → 批量创建 inbox_members + update_account_cache
Inbox#remove_members → 批量删除 + update_account_cache

涉及的自动化/规则/事件

InboxMember after_create :add_agent_to_round_robin → 调用 AutoAssignment::InboxRoundRobinService#add_agent_to_queue
InboxMember after_destroy :remove_agent_from_round_robin → 调用 AutoAssignment::InboxRoundRobinService#remove_agent_from_queue
Audit::InboxMember mod → 审计日志记录

Chatwoot原实现关键代码文件路径

app/models/inbox_member.rb
app/models/inbox.rb (add_members/remove_members)
app/controllers/api/v1/accounts/inbox_members_controller.rb
app/controllers/api/v1/widget/inbox_members_controller.rb
app/services/auto_assignment/inbox_round_robin_service.rb

版本标注：社区版

3. Channelable多渠道模式

功能描述

Chatwoot 采用多态 + Concern 的设计模式实现多渠道。每个渠道类型（WebWidget/Telegram/Facebook/WhatsApp/Email 等）都是独立的 Channel 模型，通过 Channelable concern 统一接入 Inbox。Inbox 通过 belongs_to :channel, polymorphic: true, dependent: :destroy 关联，channel_type 字段存储类名（如 'Channel::WebWidget'），channel_id 存储对应表的 PK。

用户操作流程

创建 Inbox 时选择渠道类型 → Controller 根据类型动态创建对应 Channel 模型
更新 Inbox 时可选更新 Channel 属性 → 每个 Channel 模型定义 EDITABLE_ATTRS 常量控制可修改字段
删除 Inbox → 级联删除 Channel 记录（dependent: :destroy_async）

涉及的数据模型 + 关键字段

Channelable concern 核心逻辑：
- validates :account_id, presence: true
- belongs_to :account
- has_one :inbox, as: :channel, dependent: :destroy_async, touch: true
- after_update :create_audit_log_entry
Inbox 多态关联：
- belongs_to :channel, polymorphic: true, dependent: :destroy
- channel_type 存储类名如 'Channel::WebWidget'
- channel_id 存储对应表的 PK

涉及的业务逻辑（service层）

InboxesController#channel_type_from_params → 映射参数类型名到 Channel 类：

{ 'web_widget' => Channel::WebWidget, 'api' => Channel::Api,
  'email' => Channel::Email, 'line' => Channel::Line,
  'telegram' => Channel::Telegram, 'whatsapp' => Channel::Whatsapp,
  'sms' => Channel::Sms }

InboxesController#create_channel → 根据 EDITABLE_ATTRS 创建 Channel 实例
InboxesController#update_channel → 读取 EDITABLE_ATTRS，验证/更新 Channel 属性
InboxesController#allowed_channel_types → 仅允许 web_widget/api/email/line/telegram/whatsapp/sms 七种通过此 Controller 创建（Facebook/Twilio/Instagram/TikTok/Twitter 有独立的创建流程）

Chatwoot原实现关键代码文件路径

app/models/concerns/channelable.rb
app/models/inbox.rb (多态 belongs_to)
app/controllers/api/v1/accounts/inboxes_controller.rb (create_channel / update_channel)
app/models/channel/web_widget.rb, telegram.rb, whatsapp.rb, email.rb, api.rb, sms.rb, line.rb, facebook_page.rb, instagram.rb, twilio_sms.rb, twitter_profile.rb, tiktok.rb

版本标注：社区版（所有渠道模型均在社区版）

4. WebWidget渠道

功能描述

WebWidget 是 Chatwoot 的核心内置渠道，为网站提供嵌入式聊天窗口。支持自定义外观（颜色/欢迎语/回复时间）、预聊天表单、HMAC验证、域名白名单、邮件回访等。

用户操作流程

创建 WebWidget Inbox：选择 "Website" 渠道 → 输入网站URL、Widget颜色、欢迎标题/标语 → 生成 website_token
配置 Widget：设置预聊天表单（字段类型/必填/占位符）、HMAC强制验证、允许域名列表、邮件回访
嵌入网站：将生成的 JS SDK + website_token 嵌入目标网站
Portal 关联：WebWidget 可关联到 Portal（帮助中心），portals.channel_web_widget_id

涉及的API端点

创建/更新通过 InboxesController（channel.type = 'web_widget'）
Widget 前端通过 website_token 发起对话（/api/v1/widget/conversations）

涉及的数据模型 + 关键字段

Channel::WebWidget (channel_web_widgets 表)
- id, account_id
- website_url (网站URL), website_token (唯一，用于前端SDK标识)
- widget_color (默认 "#1f93ff"), welcome_title, welcome_tagline
- reply_time (enum: in_a_few_minutes / in_a_few_hours / in_a_day)
- pre_chat_form_enabled (默认 false), pre_chat_form_options (jsonb)
- hmac_mandatory (默认 false), hmac_token (唯一，用于身份验证)
- allowed_domains (域名白名单)
- continuity_via_email (默认 true，关闭对话后邮件通知)
- feature_flags (FlagShihTzu 位标志，控制 Widget 功能)

涉及的业务逻辑（service层）

Widget SDK 加载 → 通过 website_token 定位 Channel → 创建 ContactInbox + Conversation
HMAC 验证 → hmac_mandatory 强制前端传递 HMAC 签名
预聊天表单 → pre_chat_form_options 定义表单字段

涉及的自动化/规则/事件

创建时自动生成 website_token + hmac_token（has_secure_token）
Portal 关联 → portals.channel_web_widget_id 外键

Chatwoot原实现关键代码文件路径

app/models/channel/web_widget.rb
app/javascript/widget/ (前端SDK)
app/controllers/api/v1/widget/ (Widget API)
db/migrate/20240415210313_add_channel_web_widget_to_portals.rb

版本标注：社区版

5. Telegram渠道

功能描述

通过 Telegram Bot API 接入，将 Telegram Bot 的消息同步到 Chatwoot Inbox。支持文本、附件发送，支持获取用户头像。

用户操作流程

创建 Telegram Inbox：输入 Bot Token → 系统验证 Token 有效性 → 自动注册 Webhook
收发消息：用户在 Telegram 发消息 → Webhook 推送到 Chatwoot → 创建 Conversation → Agent 回复通过 Bot API 发回 Telegram
更新：可修改 Bot Token（重新验证 + 重设 Webhook）

涉及的API端点

创建/更新通过 InboxesController（channel.type = 'telegram'）
Telegram Webhook: /webhooks/telegram/{bot_token} → Webhooks::TelegramController#process_payload

涉及的数据模型 + 关键字段

Channel::Telegram (channel_telegram 表)
- id, account_id
- bot_token (必填, 唯一, 可加密), bot_name
- EDITABLE_ATTRS = [:bot_token]

涉及的业务逻辑（service层）

Telegram::IncomingMessageService → 解析 Telegram Webhook payload → 创建/更新 Conversation + Message
Telegram::SendOnTelegramService → Agent 回复通过 Bot API 发送
Telegram::SendAttachmentsService → 处理附件发送
Telegram::UpdateMessageService → 更新已发送消息

涉及的自动化/规则/事件

before_validation :ensure_valid_bot_token → 创建时验证 Bot Token 有效（调用 getMe API）
before_save :setup_telegram_webhook → 自动注册 Telegram Webhook URL

Chatwoot原实现关键代码文件路径

app/models/channel/telegram.rb
app/controllers/webhooks/telegram_controller.rb
app/services/telegram/incoming_message_service.rb
app/services/telegram/send_on_telegram_service.rb
app/services/telegram/send_attachments_service.rb
app/jobs/webhooks/telegram_events_job.rb

版本标注：社区版

6. Facebook / Instagram渠道

功能描述

通过 Facebook Graph API 接入 Facebook Page 消息（Messenger）和 Instagram DM。需要 OAuth 授权获取 Page Access Token，支持 Webhook 接收消息，支持 Reauthorization 机制。

用户操作流程

Facebook 创建：通过 OAuth 流程 → 选择 Page → 获取 Page Access Token → 自动订阅 Webhook
Instagram 创建：类似 Facebook OAuth → 获取 Instagram Business Account ID + Access Token
收发消息：Facebook/Instagram Webhook 推送 → 创建 Conversation → Agent 回复通过 Graph API 发回
Reauthorization：Token 失效后提示重新授权（Reauthorizable concern）

涉及的API端点

Facebook OAuth: /api/v1/accounts/{id}/facebook/authorize
Instagram OAuth: /api/v1/accounts/{id}/instagram/authorizations
Facebook Webhook: /webhooks/facebook (全局)
Instagram Webhook: /webhooks/instagram/{instagram_id} → Webhooks::InstagramController
InboxesController 创建 Facebook/Instagram Inbox（通过 OAuth 回调后）

涉及的数据模型 + 关键字段

Channel::FacebookPage (channel_facebook_pages 表)
- id, account_id, page_id (必填, scope唯一), page_access_token (加密), user_access_token (加密)
- instagram_id (可选，关联 Instagram Business Account)
- include Reauthorizable
Channel::Instagram (channel_instagram 表)
- id, account_id, instagram_id (必填, 唯一), access_token (加密), expires_at
- include Reauthorizable, AUTHORIZATION_ERROR_THRESHOLD = 1

涉及的业务逻辑（service层）

Facebook::SendOnFacebookService → 通过 Graph API 发送 Messenger 消息
Instagram::SendOnInstagramService / Instagram::Messenger::SendOnInstagramService → 发送 Instagram DM
Instagram::RefreshOauthTokenService → 刷新 Instagram Access Token
Channel::FacebookPage#subscribe / unsubscribe → 注册/注销 Facebook Webhook
Channel::Instagram#subscribe / unsubscribe → 注册/注销 Instagram Webhook

涉及的自动化/规则/事件

after_create_commit :subscribe → 自动订阅 Facebook/Instagram Webhook
before_destroy :unsubscribe → 删除时注销 Webhook
Reauthorizable → Token 失效计数 + 邮件通知 + UI 提示重新授权

Chatwoot原实现关键代码文件路径

app/models/channel/facebook_page.rb
app/models/channel/instagram.rb
app/models/concerns/reauthorizable.rb
app/controllers/webhooks/instagram_controller.rb
app/controllers/api/v1/accounts/instagram/authorizations_controller.rb
app/services/facebook/send_on_facebook_service.rb
app/services/instagram/send_on_instagram_service.rb
app/services/instagram/refresh_oauth_token_service.rb

版本标注：社区版

7. WhatsApp渠道

功能描述

支持两种 WhatsApp 提供商：360dialog（默认）和 WhatsApp Cloud API（Meta官方）。创建时需要手机号 + provider配置，自动同步消息模板，自动设置 Webhook。

用户操作流程

创建 WhatsApp Inbox：选择 Provider → 输入手机号 → 配置 API Key / Webhook Verify Token
Embedded Signup（企业版）：通过 Meta Embedded Signup 流程一键创建
模板管理：自动同步 WhatsApp 消息模板 → 用于 Campaign 发送
收发消息：WhatsApp Webhook 推送 → 创建 Conversation → Agent 回复通过 Provider API 发回

涟及的API端点

创建/更新通过 InboxesController（channel.type = 'whatsapp'）
WhatsApp Webhook: /webhooks/whatsapp/{phone_number} → Webhooks::WhatsappController
WhatsApp Health: /api/v1/accounts/{id}/inboxes/{id}/whatsapp_health (企业版 WhatsappHealthManagement)

涉及的数据模型 + 关键字段

Channel::Whatsapp (channel_whatsapp 表)
- id, account_id, phone_number (必填, 唯一)
- provider (enum: default / whatsapp_cloud)
- provider_config (jsonb: webhook_verify_token, api_key, source 等)
- message_templates (jsonb), message_templates_last_updated
- include Reauthorizable

涉及的业务逻辑（service层）

Whatsapp::IncomingMessageWhatsappCloudService / Whatsapp::IncomingMessageBaseService → 处理 WhatsApp Webhook payload
Whatsapp::SendOnWhatsappService → 通过 Provider API 发送消息
Whatsapp::ChannelCreationService → 创建 WhatsApp Channel
Whatsapp::WebhookSetupService / Whatsapp::WebhookTeardownService → 设置/注销 Webhook
Whatsapp::TokenExchangeService / Whatsapp::TokenValidationService → Token 管理
Whatsapp::TemplateProcessorService / Whatsapp::SyncTemplatesJob → 模板同步
Whatsapp::EmbeddedSignupService → Meta Embedded Signup 流程
Whatsapp::ReauthorizationService → 360dialog Token 重新授权
Whatsapp::PhoneNumberNormalizationService → 手机号规范化

涉及的自动化/规则/事件

after_create :sync_templates → 创建时同步消息模板
after_commit :setup_webhooks, on: :create → 自动设置 Webhook（条件: should_auto_setup_webhooks?）
before_destroy :teardown_webhooks → 删除时注销 Webhook
Webhook 签名验证 → MetaTokenVerifyConcern (WhatsApp Cloud)
Reauthorizable → Token 失效处理

Chatwoot原实现关键代码文件路径

app/models/channel/whatsapp.rb
app/controllers/webhooks/whatsapp_controller.rb
app/services/whatsapp/incoming_message_whatsapp_cloud_service.rb
app/services/whatsapp/incoming_message_base_service.rb
app/services/whatsapp/send_on_whatsapp_service.rb
app/services/whatsapp/webhook_setup_service.rb
app/services/whatsapp/channel_creation_service.rb
app/services/whatsapp/embedded_signup_service.rb
app/services/whatsapp/reauthorization_service.rb
app/controllers/api/v1/accounts/concerns/whatsapp_health_management.rb

版本标注：社区版（核心功能）/ 企业版（Embedded Signup、WhatsApp Health Dashboard）

8. Email渠道

功能描述

通过 IMAP + SMTP 接入邮件，将客户邮件同步到 Chatwoot Inbox。支持 IMAP 收件（拉取邮件）和 SMTP 发件（Agent回复通过邮件发出），也支持邮件转发（forward_to_email）。

用户操作流程

创建 Email Inbox：输入邮箱地址 → 系统生成 forward_to_email → 可选配置 IMAP/SMTP
配置 IMAP：设置 IMAP 地址/端口/SSL/认证/登录凭据 → 验证连接 → 启用 IMAP 收件
配置 SMTP：设置 SMTP 地址/端口/SSL/认证/域名/登录凭据 → 验证连接 → 启用 SMTP 发件
收发邮件：IMAP 拉取 → 创建 Conversation → Agent 回复通过 SMTP 发出

涉及的API端点

创建/更新通过 InboxesController（channel.type = 'email'）
更新时额外验证 IMAP/SMTP 连接（InboxesHelper#validate_email_channel）

涉及的数据模型 + 关键字段

Channel::Email (channel_email 表)
- id, account_id, email (唯一), forward_to_email (唯一)
- IMAP: imap_enabled, imap_address, imap_port, imap_login, imap_password, imap_enable_ssl, imap_authentication
- SMTP: smtp_enabled, smtp_address, smtp_port, smtp_login, smtp_password, smtp_domain, smtp_enable_ssl_tls, smtp_enable_starttls_auto, smtp_authentication, smtp_openssl_verify_mode
- provider, provider_config (jsonb)
- verified_for_sending (默认 false)
- EDITABLE_ATTRS 包含所有 IMAP/SMTP 字段

涉及的业务逻辑（service层）

Email::SendOnEmailService → Agent 回复通过 SMTP 发送邮件
Imap::FetchService → 定期通过 IMAP 拉取新邮件 → 创建 Conversation/Message
InboxesHelper#validate_email_channel → 创建/更新时验证 IMAP/SMTP 连接

涉及的自动化/规则/事件

IMAP 拉取 → 定时任务（Scheduler）定期调用 Imap::FetchService
SMTP 发件 → Agent 回复触发 Email::SendOnEmailService
验证 → 创建/更新 Email Inbox 时必须验证 IMAP/SMTP 连接

Chatwoot原实现关键代码文件路径

app/models/channel/email.rb
app/services/email/send_on_email_service.rb
app/services/imap/fetch_service.rb
app/helpers/api/v1/inboxes_helper.rb
app/services/imap/ (IMAP 相关)

版本标注：社区版 / 企业版（Email Channel Migration - Platform API）

9. Twilio SMS / WhatsApp渠道

功能描述

通过 Twilio API 接入 SMS 和 WhatsApp 消息。Twilio 渠道有独立的创建流程（不通过 InboxesController），支持 API Key 认证、Messaging Service、语音通话（企业版）。

用户操作流程

创建 Twilio Inbox：输入 Account SID + Auth Token / API Key → 选择 medium (sms/whatsapp) → 输入手机号或 Messaging Service SID → 系统验证 Twilio 凭据 → 自动设置 Webhook
收发消息：Twilio Webhook 推送 → 创建 Conversation → Agent 回复通过 Twilio API 发回
模板同步：WhatsApp 模板可通过 Twilio Content API 同步

涉及的API端点

方法	路径	说明
POST	`/api/v1/accounts/{id}/channels/twilio_channel`	创建 Twilio Inbox（独立 Controller）
POST	`/webhooks/twilio/callback`	Twilio 回调 Webhook

涉及的数据模型 + 关键字段

Channel::TwilioSms (channel_twilio_sms 表)
- id, account_id, account_sid (必填), auth_token (必填, 加密), api_key_sid, api_key_secret
- phone_number, messaging_service_sid
- medium (enum: sms=0 / whatsapp=1)
- voice_enabled (默认 false, 企业版语音通话)
- content_templates (jsonb), content_templates_last_updated
- twiml_app_sid

涉及的业务逻辑（service层）

Twilio::IncomingMessageService → 处理 Twilio Webhook payload
Twilio::SendOnTwilioService → 通过 Twilio API 发送消息
Twilio::WebhookSetupService → 设置 Twilio Webhook URL
Twilio::DeliveryStatusService → 处理消息送达状态回调
Twilio::TemplateSyncService → 同步 WhatsApp Content Templates
Twilio::OneoffSmsCampaignService → SMS 短信营销

涉及的自动化/规则/事件

创建时验证 Twilio 凭据（authenticate_twilio → client.messages.list(limit: 1)）
创建 SMS 时自动设置 Webhook（setup_webhooks → Twilio::WebhookSetupService）

Chatwoot原实现关键代码文件路径

app/models/channel/twilio_sms.rb
app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb
app/controllers/webhooks/twilio_controller.rb
app/services/twilio/incoming_message_service.rb
app/services/twilio/send_on_twilio_service.rb
app/services/twilio/webhook_setup_service.rb
app/services/twilio/template_sync_service.rb

版本标注：社区版（SMS/WhatsApp）/ 企业版（Voice 通话、Twilio CSAT 模板）

10. 其他渠道（SMS、Line、Twitter、TikTok、API）

SMS（Bandwidth）

Channel::Sms (channel_sms 表)
- phone_number (唯一), provider (default), provider_config (jsonb: application_id 等)
- 通过 Bandwidth API 发送 SMS
- Webhook: /webhooks/sms/{phone_number} → Webhooks::SmsController
关键文件: app/models/channel/sms.rb, app/services/sms/

Line

Channel::Line (channel_line 表)
- line_channel_id (唯一), line_channel_secret, line_channel_token (加密)
- 使用 line-bot-api gem
- Webhook: /webhooks/line/{line_channel_id} → Webhooks::LineController
关键文件: app/models/channel/line.rb, app/services/line/incoming_message_service.rb, app/services/line/send_on_line_service.rb

Twitter

Channel::TwitterProfile (channel_twitter_profiles 表)
- profile_id (scope唯一), twitter_access_token (加密), twitter_access_token_secret (加密)
- tweets_enabled (默认 true)
- before_destroy :unsubscribe
- 注：Twitter API v1.1 已停用，此渠道功能受限
关键文件: app/models/channel/twitter_profile.rb

TikTok

Channel::Tiktok (channel_tiktok 表)
- business_id (唯一), access_token (加密), refresh_token (加密)
- expires_at, refresh_token_expires_at
- include Reauthorizable
- OAuth 授权: /api/v1/accounts/{id}/tiktok/authorizations
关键文件: app/models/channel/tiktok.rb, app/services/tiktok/, app/controllers/webhooks/tiktok_controller.rb

API Channel

Channel::Api (channel_api 表)
- identifier (唯一, auto token), hmac_token (唯一, auto token), webhook_url
- hmac_mandatory, additional_attributes (jsonb: agent_reply_time_window 等)
- secret (auto token, WebhookSecretable)
- 适合第三方系统通过 API + Webhook 集成
关键文件: app/models/channel/api.rb, app/controllers/api/v1/accounts/inboxes_controller.rb

版本标注

SMS/Line/Twitter/API: 社区版
TikTok: 社区版（OAuth + Webhook）

11. Webhook回调（外部事件推送）

功能描述

Chatwoot 支持两类 Webhook：

渠道 Webhook：外部平台（Telegram/WhatsApp/Facebook等）向 Chatwoot 推送消息事件的回调入口
用户自定义 Webhook：Chatwoot 向外部系统推送内部事件（对话创建/更新/消息等）的出站 Webhook

用户操作流程

渠道 Webhook：创建渠道时自动注册 → 外部平台推送消息 → WebhookController 接收 → 异步 Job 处理
自定义 Webhook：管理员创建 Webhook → 选择订阅事件 → 事件触发时 Chatwoot POST 到指定 URL

涉及的API端点

渠道 Webhook（入站）：

路径	说明
`/webhooks/telegram/{bot_token}`	Telegram 消息回调
`/webhooks/whatsapp/{phone_number}`	WhatsApp 消息回调
`/webhooks/line/{line_channel_id}`	Line 消息回调
`/webhooks/sms/{phone_number}`	SMS 消息回调
`/webhooks/instagram/{instagram_id}`	Instagram 消息回调
`/webhooks/tiktok`	TikTok 消息回调
`/webhooks/facebook`	Facebook 消息回调
`/twilio/callback`	Twilio 回调

自定义 Webhook（出站）：

方法	路径	说明
GET	`/api/v1/accounts/{id}/webhooks`	列出 Webhook
POST	`/api/v1/accounts/{id}/webhooks`	创建 Webhook
PATCH	`/api/v1/accounts/{id}/webhooks/{wid}`	更新 Webhook
DELETE	`/api/v1/accounts/{id}/webhooks/{wid}`	删除 Webhook

涉及的数据模型 + 关键字段

Webhook (webhooks 表)
- id, account_id, inbox_id (可选), url, name, secret (WebhookSecretable)
- subscriptions (jsonb: 允许的事件列表)
- webhook_type (enum: account_type=0 / inbox_type=1)
- 联合唯一索引: (account_id, url)

允许的订阅事件

ALLOWED_WEBHOOK_EVENTS = %w[
  conversation_status_changed conversation_updated conversation_created
  contact_created contact_updated
  message_created message_updated
  webwidget_triggered
  inbox_created inbox_updated
  conversation_typing_on conversation_typing_off
]

涉及的业务逻辑（service层）

各渠道 WebhookController → 接收 payload → 异步 Job 处理（如 Webhooks::TelegramEventsJob, Webhooks::WhatsappEventsJob）
自定义 Webhook → 事件触发时 WebhookJob POST 到用户指定 URL（带 HMAC 签名）
WebhookSecretable → 生成/验证 Webhook Secret

涉及的自动化/规则/事件

渠道创建时自动注册 Webhook（Telegram/WhatsApp/Facebook/Instagram/Twilio）
渠道删除时自动注销 Webhook
WhatsApp Webhook 签名验证 → MetaTokenVerifyConcern

Chatwoot原实现关键代码文件路径

app/controllers/webhooks/ (各渠道 Webhook Controller)
app/models/webhook.rb
app/controllers/api/v1/accounts/webhooks_controller.rb
app/models/concerns/webhook_secretable.rb
app/jobs/webhooks/ (各渠道异步 Job)

版本标注：社区版

12. OAuth刷新 / Reauthorizable

功能描述

部分渠道（Facebook、Instagram、WhatsApp、TikTok）依赖外部 OAuth Token，Token 可能过期或失效。Reauthorizable concern 提供统一机制：计数授权错误 → 达到阈值后标记需要重新授权 → 发邮件通知 → UI 提示重新授权流程。

用户操作流程

正常使用：Token 有效，消息正常收发
Token 失效：外部 API 返回授权错误 → authorization_error! 计数 +1
达到阈值：标记 reauthorization_required? → 发邮件通知管理员 → UI 显示"需要重新授权"提示
重新授权：管理员点击重新授权 → 通过 OAuth 流程获取新 Token → reauthorized! 清除标记
自动刷新：Instagram/Google/Microsoft 有 RefreshOauthTokenService 自动刷新 Token

涉及的数据模型 + 关键字段

Reauthorizable concern：
- reauthorization_required? → Redis 键检查
- authorization_error_count → Redis 计数
- authorization_error! → 计数递增 + 阈值判断
- prompt_reauthorization! → 设置 Redis 标记 + 发邮件
- reauthorized! → 清除 Redis 标记 + 计数
使用此 concern 的模型：
- Channel::FacebookPage (阈值=2)
- Channel::Instagram (阈值=1)
- Channel::Whatsapp (阈值=2)
- Channel::Tiktok (阈值=1)

涉及的业务逻辑（service层）

Instagram::RefreshOauthTokenService → 自动刷新 Instagram Token
Google::RefreshOauthTokenService → 自动刷新 Google Token
Microsoft::RefreshOauthTokenService → 自动刷新 Microsoft Token
Whatsapp::ReauthorizationService → 360dialog Token 重新授权
Tiktok::TokenService → TikTok Token 管理

涉及的自动化/规则/事件

Inbox#dispatch_reauthorization_event → 发布 INBOX_UPDATED 事件（包含 reauthorization_required 变化）
邮件通知 → Reauthorizable 阈值触发时发送邮件给管理员
after_update :create_audit_log_entry (Channelable) → Channel 更新时创建审计日志

Chatwoot原实现关键代码文件路径

app/models/concerns/reauthorizable.rb
app/models/inbox.rb (dispatch_reauthorization_event)
app/services/instagram/refresh_oauth_token_service.rb
app/services/google/refresh_oauth_token_service.rb
app/services/microsoft/refresh_oauth_token_service.rb
app/services/whatsapp/reauthorization_service.rb
app/services/tiktok/token_service.rb

版本标注：社区版

13. 企业版InboxCapacity

功能描述

企业版的 Agent Capacity Policy 机制允许为每个 Inbox + Agent 组合设定对话数量上限（conversation_limit）。当 Agent 在某 Inbox 的活跃对话数达到上限时，自动分配系统不再将新对话分配给该 Agent。

用户操作流程

创建 Agent Capacity Policy：定义全局分配容量策略
设置 Inbox 容量限制：为 Policy 下的每个 Inbox 设定 conversation_limit
分配生效：自动分配时检查 Agent 在该 Inbox 的容量是否已满

涉及的API端点

方法	路径	说明
POST	`/api/v1/accounts/{id}/agent_capacity_policies/{policy_id}/inbox_limits`	创建 Inbox 容量限制
PATCH	`/api/v1/accounts/{id}/agent_capacity_policies/{policy_id}/inbox_limits/{limit_id}`	更新限制
DELETE	`/api/v1/accounts/{id}/agent_capacity_policies/{policy_id}/inbox_limits/{limit_id}`	删除限制

涉及的数据模型 + 关键字段

InboxCapacityLimit (inbox_capacity_limits 表)
- id, agent_capacity_policy_id (必填), inbox_id (必填)
- conversation_limit (必填, >=0)
- 联合唯一索引: (agent_capacity_policy_id, inbox_id)
Enterprise::Concerns::Inbox → has_many :inbox_capacity_limits
AgentCapacityPolicy → has_many :inbox_capacity_limits
Inbox#member_ids_with_assignment_capacity → 企业版覆写，返回有剩余容量的成员 ID

涉及的业务逻辑（service层）

Api::V1::Accounts::AgentCapacityPolicies::InboxLimitsController → CRUD InboxCapacityLimit
Inbox#member_ids_with_assignment_capacity → 社区版返回所有 member_ids，企业版根据容量筛选
Enterprise::Account::PlanUsageAndLimits → usage_limits 包含 inboxes 数量限制

涉及的自动化/规则/事件

创建 InboxCapacityLimit 时验证无重复（同一 Policy + Inbox 只能有一条）
自动分配时 member_ids_with_assignment_capacity 筛选有容量的 Agent
validate_limit → 创建 Inbox 时检查账户 Inbox 数量上限

Chatwoot原实现关键代码文件路径

enterprise/app/models/inbox_capacity_limit.rb
enterprise/app/models/enterprise/concerns/inbox.rb
enterprise/app/models/enterprise/account/plan_usage_and_limits.rb
enterprise/app/controllers/api/v1/accounts/agent_capacity_policies/inbox_limits_controller.rb
app/models/concerns/inbox_agent_availability.rb (社区版 member_ids_with_assignment_capacity)

版本标注：企业版

附录：渠道模型对照表

渠道	模型类	表名	关键标识字段	创建方式	Reauthorizable	加密字段
WebWidget	Channel::WebWidget	channel_web_widgets	website_token	InboxesController	❌	❌
Telegram	Channel::Telegram	channel_telegram	bot_token	InboxesController	❌	bot_token
Facebook	Channel::FacebookPage	channel_facebook_pages	page_id	OAuth回调	✅ (阈值2)	page_access_token, user_access_token
Instagram	Channel::Instagram	channel_instagram	instagram_id	OAuth回调	✅ (阈值1)	access_token
WhatsApp	Channel::Whatsapp	channel_whatsapp	phone_number	InboxesController	✅ (阈值2)	❌ (provider_config含API key)
Email	Channel::Email	channel_email	email	InboxesController	❌	imap_password, smtp_password
Twilio	Channel::TwilioSms	channel_twilio_sms	account_sid+phone_number	TwilioChannelsController	❌	auth_token
SMS	Channel::Sms	channel_sms	phone_number	InboxesController	❌	❌
Line	Channel::Line	channel_line	line_channel_id	InboxesController	❌	line_channel_secret, line_channel_token
Twitter	Channel::TwitterProfile	channel_twitter_profiles	account_id+profile_id	OAuth	❌	twitter_access_token, twitter_access_token_secret
TikTok	Channel::Tiktok	channel_tiktok	business_id	OAuth回调	✅ (阈值1)	access_token, refresh_token
API	Channel::Api	channel_api	identifier	InboxesController	❌	❌

附录：Inbox多态类型判断方法

# Inbox 模型中的渠道类型判断方法
inbox.web_widget?   # Channel::WebWidget
inbox.telegram?     # Channel::Telegram
inbox.facebook?     # Channel::FacebookPage
inbox.instagram?    # Facebook? + channel.instagram_id.present? || Channel::Instagram
inbox.whatsapp?     # Channel::Whatsapp
inbox.email?        # Channel::Email
inbox.twilio?       # Channel::TwilioSms
inbox.twilio_whatsapp? # Channel::TwilioSms && medium == 'whatsapp'
inbox.sms?          # Channel::Sms
inbox.twitter?      # Channel::TwitterProfile
inbox.tiktok?       # Channel::Tiktok
inbox.api?          # Channel::Api

# Inbox 通用类型名
inbox.inbox_type    # channel.name (如 'WebWidget', 'Telegram', 'Whatsapp' 等)

附录：Inbox回调Webhook URL生成

# Inbox#callback_webhook_url 根据渠道类型生成
Channel::TwilioSms   → "#{FRONTEND_URL}/twilio/callback"
Channel::Sms         → "#{FRONTEND_URL}/webhooks/sms/#{phone_number}"
Channel::Line        → "#{FRONTEND_URL}/webhooks/line/#{line_channel_id}"
Channel::Whatsapp    → "#{FRONTEND_URL}/webhooks/whatsapp/#{phone_number}"

38 KiB Raw Blame History Unescape Escape

M2 Inbox与渠道管理 功能梳理文档

目录

1. Inbox CRUD + 设置 + 品牌

功能描述

用户操作流程

涉及的API端点

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

涉及的自动化/规则/事件

Chatwoot原实现关键代码文件路径

版本标注：社区版 / 企业版

2. InboxMember绑定

功能描述

用户操作流程

涉及的API端点

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

涉及的自动化/规则/事件

Chatwoot原实现关键代码文件路径

版本标注：社区版

3. Channelable多渠道模式

功能描述

用户操作流程

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

Chatwoot原实现关键代码文件路径

版本标注：社区版（所有渠道模型均在社区版）

4. WebWidget渠道

功能描述

用户操作流程

涉及的API端点

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

涉及的自动化/规则/事件

Chatwoot原实现关键代码文件路径

版本标注：社区版

5. Telegram渠道

功能描述

用户操作流程

涉及的API端点

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

涉及的自动化/规则/事件

Chatwoot原实现关键代码文件路径

版本标注：社区版

6. Facebook / Instagram渠道

功能描述

用户操作流程

涉及的API端点

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

涉及的自动化/规则/事件

Chatwoot原实现关键代码文件路径

版本标注：社区版

7. WhatsApp渠道

功能描述

用户操作流程

涟及的API端点

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

涉及的自动化/规则/事件

Chatwoot原实现关键代码文件路径

版本标注：社区版（核心功能）/ 企业版（Embedded Signup、WhatsApp Health Dashboard）

8. Email渠道

功能描述

用户操作流程

涉及的API端点

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

涉及的自动化/规则/事件

Chatwoot原实现关键代码文件路径

版本标注：社区版 / 企业版（Email Channel Migration - Platform API）

9. Twilio SMS / WhatsApp渠道

功能描述

用户操作流程

涉及的API端点

涉及的数据模型 + 关键字段

涉及的业务逻辑（service层）

涉及的自动化/规则/事件

38 KiB

Raw Blame History

M2 Inbox与渠道管理功能梳理文档