申请 Instagram API 并把账号接入 ChatHub

本文解决什么问题#

ChatHub 的 Instagram 渠道让您在共享收件箱里接收并回复 Instagram 商家账号的私信。Instagram 没有自己的令牌：所有调用都通过所关联 Facebook 主页的令牌进行，因此该渠道与 Facebook 渠道共用同一个 Meta 应用、应用密钥和管理员令牌 — 您只需额外申请权限并多注册一个 webhook。

因此第一个前提是已完成「Facebook 主页」一文：Meta 应用已创建，App ID、应用密钥和管理员令牌已保存在 ChatHub。本文从那里继续。

还没有 Meta 应用？请先完成 Facebook 主页指南 ↗

1. 准备正确类型的 Instagram 账号#

Meta 只向已关联 Facebook 主页的专业版 Instagram 账号（商家或创作者）开放消息 API。个人账号无论申请什么权限都无法调用。

1. 1

   在手机的 Instagram 应用中，打开设置 → 账户类型和工具 → 切换为专业账户，选择「商家」。

2. 2

   把账号关联到 Facebook 主页：在 Facebook 打开主页，进入设置 → 已关联的账户，选择 Instagram 并登录要连接的账号。

3. 3

   仍在 Instagram 应用中，打开设置 → 隐私 → 消息，在「已连接的工具」下允许访问消息 — 缺少这个开关，webhook 会静默地什么都不发。

2. 向应用添加 Instagram 用例#

1. 1

   打开 developers.facebook.com，进入 Facebook 渠道正在使用的那个应用。

2. 2

   在控制面板右上角点击「添加用例」。

3. 3

   在弹窗中按「商家消息」分组筛选，勾选「管理 Instagram 上的消息和内容」，然后点击保存。

3. 添加消息权限并签发新的管理员令牌#

ChatHub 通过「使用 Facebook 登录」这条路径收发 Instagram 消息，所以要加的权限位于刚添加用例的「使用 Facebook 登录信息设置 API」页面。

1. 1

   打开「用例」，在 Instagram 行点击「自定义」，然后进入「使用 Facebook 登录信息设置 API」页面（简介段落里也有直达链接）。

2. 2

   在「在 Instagram 上发送消息」下点击 Add required messaging permissions。Meta 提示权限已添加，按钮变为 Go to permissions and features。

3. 3

   打开工具 → Graph API 探索工具，在「Meta 应用」框中选中正确的应用。

4. 4

   在原有三个 pages 权限旁边加上 instagram_basic 和 instagram_manage_messages。

5. 5

   点击 Generate Access Token 并确认授权 — 授权窗口会同时询问主页及其 Instagram 账号 — 然后复制新令牌。

4. 更新令牌并复制 Instagram 回调地址#

1. 1

   在 ChatHub 打开设置，选择「渠道」分组，找到「Facebook 应用」卡片。

2. 2

   把刚签发的管理员令牌粘贴到「管理员令牌」框并保存。App ID 和应用密钥保持不变。

3. 3

   滚动到「向 Meta 注册 webhook」：Callback URL (Instagram) 一行是专供 Instagram 产品的地址。分别点击该行和 Verify Token 行的复制按钮 — 这对值用于下一步。

5. 在 Instagram 设置中连接主页并注册 webhook#

Instagram 的 webhook 在 Messenger 用例内的「Instagram 设置」页面注册 — Meta 把走主页令牌的 Instagram 消息功能归在了这里。

1. 1

   打开「用例」，在 Messenger 行点击「自定义」，然后在左栏选择「Instagram 设置」。

2. 2

   在「访问令牌」部分点击「添加或移除主页」，选择已关联 Instagram 的 Facebook 主页；授权窗口会连同主页的 Instagram 账号一起询问。

3. 3

   在「Webhooks」部分点击「添加回调网址」。

4. 4

   把 Callback URL (Instagram) 粘贴到回调网址框，把 Verify Token 粘贴到验证码框，然后点击「验证并保存」。

5. 5

   在保存后出现的 webhook 字段表中，为 messages 和 messaging_postbacks 两个字段打开「订阅」。

6. 在 ChatHub 中添加 Instagram 渠道#

1. 1

   在 ChatHub 打开「渠道」页面，点击「添加账号」，选择 Instagram 类型。

2. 2

   列表会显示管理员令牌能触达的、已关联 Instagram 的主页；选中要连接的账号并点击「创建账号」。

3. 3

   在新渠道上点击「连接」。ChatHub 会自行把应用订阅到所关联的主页 — Meta 那边无需再注册任何东西。

4. 4

   用另一个在应用中拥有角色的 Instagram 账号发一条测试私信，确认它到达收件箱。

其余渠道类型请参阅渠道接入指南 ↗

需要提前了解的限制#

Instagram 与 Messenger 遵循同样的 24 小时窗口：只能在客户最后一条消息后的 24 小时内自由回复，超时后 Meta 会拒绝，直到客户再次来信。ChatHub 会在输入框上方倒计时，内部备注则不受窗口限制。

关于发出的内容：Instagram 只接受图片、视频和音频文件 — PDF 等文档无法发送；表情贴纸只能收不能发；工作流按钮以快捷回复形式发出，链接按钮则连同网址写进正文，因为 Instagram 没有可挂链接按钮的位置。

同时运行两个 Meta 渠道时的一个易踩坑：webhook 订阅属于主页而不属于单个渠道，因此在 Instagram 渠道上点「断开连接」也会停掉同一主页上 Facebook 渠道的 Messenger webhook，反之亦然。另一渠道会在下次检查时显示已断开 — 点「连接」即可重新订阅，不会丢失任何数据。