# 消息连接回调协议

该入口将平台回调绑定到指定消息连接。已保存的连接、通道实例、凭据及平台账户必须一致，路径中的连接ID不是独立授权凭据。

## 路径与配置

```http
GET https://api.moi.matrixorigin.cn/v5/ingress-callbacks/{provider}/{workspace_id}/{connection_id}
POST /ingress-callbacks/{provider}/{workspace_id}/{connection_id}
```

使用消息连接详情给出的callback_path，在同环境组成完整公网地址；不要从凭据回调URL直接替换一个ID。handler没有普通产品身份包装，实际准入仍验证连接Provider、receive_mode=callback、enabled和desired_state、非空channel_instance_id，以及当前通道事实active/inbound及账户身份。

连接校验、供应商Webhook登记和平台实际投递是不同动作。测试接口返回或挑战成功不表示消息任务已完成。当前GET仅允许企业微信，不推导GitHub或所有其他平台均有GET校验。

## 解码与接收

通过绑定检查后，从通道事实解析CredentialRef和版本，再按平台签名/加密及身份解码。Slack/飞书/Telegram/企业微信各有消息分支，企业微信智能机器人另有回调流处理；不是把凭据回调规则入口当成任意消息连接的别名。

挑战直接返回平台响应。可处理消息会形成带当前连接配置版本、通道实例、账户、接收模式及响应凭据版本的入站信封，执行重放检查和正式接收；空消息、非目标事件等可确认而不触发新任务。

平台确认不等于智能体终态或外部回送完成；后续任务及消息结果按连接自身读取协议核对。回调拉取还使用冻结路由，不因一次后续查询而重新准入所有事件。

## 限制与环境

handler使用2 MiB MaxBytesReader；超限可返回413/code2。共享错误适配器返回数值code/message/details，但签名、账户、连接停用、分发失败等各自有不同原因，不能只按HTTP判断业务完成。

此组没有向外部平台发送消息、登记Webhook或发起实际回调。
