@crvouga/mockingbird-service-intercom (中文(简体) )

本地模拟器。 真正的API合同. 部分 嘲笑鸟。 。 。 .

国家模拟器 Intercom REST API (第 2. 11 版) 测试套房。 服务于电话 我们的后端:

• 联系人 : a. 搜索、创建(复制409个,Intercom的方式)、更新和获取;
• 对话 : 创建( 可选) Idempotency-Key,更新,作为成员或作为 管理员(JSON或多部分附件),关闭/打开/snooze/指派,与 ?display_as=plaintext,并用光标涂上搜索;
• 身份 : /admins 财务报告和审定财务报表 /me。 。 。 .

行政答复和关闭/开放(对于订阅这些答复的接收者,还包括成员信息和 答复)发送Intercom的 notification_event 与 webhoks 签约 X-Hub-Signature: sha1=<hex HMAC-SHA1>,给两个接收器:后端的 POST /messaging/webhook 以及欧洲公路运输公司 POST /v1/webhooks/intercom。 。 。 .

• 行动范围: 支助
• 合同openapi.yaml由Intercom发表的2.11 引用 消费者使用.

安装

npm install -D @crvouga/mockingbird-service-intercom

仅限无害环境管理。 节点 22或 Bun 1.2. 无土生属地. 给它服务 npx mockingbird-intercom serve, (中文(简体) ), createServer 从 ./server (节点),或 createRuntime 与 任何获取服务器.

使用量

npx mockingbird-intercom serve --port 8807 \
  --webhook-url http://127.0.0.1:3000/messaging/webhook \
  --emr-webhook-url http://127.0.0.1:4000/v1/webhooks/intercom \
  --webhook-secret "$INTERCOM_WEBHOOK_SECRET"

添加 --webhook-events conversation.user.created,conversation.user.replied,conversation.admin.replied,conversation.admin.closed,conversation.admin.opened 订阅 --webhook-url 成员专题; --emr-webhook-url 只保留管理员 默认.

import { IntercomClient } from "intercom-client"
import { createServer } from "@crvouga/mockingbird-service-intercom/server"

const emulator = await createServer({
  webhooks: {
    urls: ["http://127.0.0.1:3000/messaging/webhook", "http://127.0.0.1:4000/v1/webhooks/intercom"],
    secret: "whsec-test",
  },
})

// The application's Intercom client. Only baseUrl changes.
const intercom = new IntercomClient({ token: "any-token", baseUrl: emulator.url })
const contact = await intercom.contacts.create({ role: "user", external_id: "1652", email: "[email protected]" })
// The member opens a conversation through the app.
const message = await intercom.conversations.create({
  from: { type: "user", id: contact.id ?? "" },
  body: "Are my results in?",
})

// Test control. Support answers: appends an admin comment and fires the signed conversation.admin.replied.
await fetch(`${emulator.url}/__admin/conversations/${message.conversation_id}/admin-reply`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ adminId: "1000001", body: "Your results are in" }),
})

await emulator.close()

路线

每条路线都需要 Authorization: Bearer <token>除非 tokens 已经设定. Intercom-Version 默认值为2.11,一个错误的值回答400 intercom_version_invalid。每次错误都使用 Intercom 的信封 : {type: "error.list", request_id, errors: [{code, message}]}。 。 。 .

对话状态如下Intercom :

• 管理评论集 read: false,意思是未读成员.
• 成员答复 read: true设置 waiting_since,然后重新打开一个已关闭或已打呼的 谈话.
• PUT {read: true} 标记谈话内容.
• 笔记改变不了成员所看到的任何东西.
• 尸体作为 HTML 存储. 纯文本被包入 <p>,每行一段,以及 display_as=plaintext 变回正文.

附件仅保留其元数据:名称、内容类型、大小和a downloads.intercomcdn.com 未服务的 URL 。 上传的字节从未被存储 .

搜索

查询是过滤器 {field, operator, value} 或化合物 {operator: "AND" | "OR", value: [query, …]},巢至两层.

• 运算符 : =, (中文(简体) ), !=, (中文(简体) ), IN, (中文(简体) ), NIN (这两个取一阵子), <, (中文(简体) ), >, (中文(简体) ), ~ (夹子), !~, (中文(简体) ), ^ (从开始)和 $ (结束). 字符串比较对大小写不敏感.
• 联系字段 : id, (中文(简体) ), external_id, (中文(简体) ), email, (中文(简体) ), name, (中文(简体) ), phone, (中文(简体) ), role时间戳, 财务报告和审定财务报表 custom_attributes.<name>。 。 。 .
• 对话字段 : id, (中文(简体) ), contact_ids, (中文(简体) ), teammate_ids, (中文(简体) ), admin_assignee_id, (中文(简体) ), team_assignee_id, (中文(简体) ), state, (中文(简体) ), open, (中文(简体) ), read, (中文(简体) ), priority, (中文(简体) ), title,时间戳,和 source.{id,type,delivered_as,subject,body,author.id,author.type,author.name,author.email}。 。 。 .
• 未知字段或运算符 答复 400 parameter_invalid。 。 。 .
• 排序 : updated_at 默认下降, id作为断线器.
• 光标 : 不透明基数64,默认每页有20个.

网络呼号

模拟器为这些事件发送了网络呼号:

端点接收上面四个管理主题, 除非它列出自己的主题 events成员 议题, conversation.admin.snoozed 财务报告和审定财务报表 .assigned 已发布,但选择进入:用 --webhook-events, (中文(简体) ), webhooks.urls: [{url, events}] 或者说 PUT /__admin/webhook-endpoints。 EMR 处理每个 notification_event 它作为管理事件收到,所以它的订阅不能 包括成员专题。 笔记什么也没有发出.

每一次送货都有一个JSON机体 X-Hub-Signature: sha1=<hex HMAC-SHA1(secret, rawBody)>数字 :

{ "type": "notification_event", "app_id": "mockapp", "topic": "conversation.admin.replied",
  "id": "notif_…", "created_at": 1760000000, "delivery_status": "pending", "delivery_attempts": 1,
  "data": { "type": "notification_event_data", "item": { "type": "conversation", "id": "…",
    "source": { "delivered_as": "customer_initiated", "author": { "email": "…" }, "body": "…" },
    "contacts": { "contacts": [{ "id": "…", "external_id": "1652" }] },
    "conversation_parts": { "conversation_parts": [ { "id": "…", "part_type": "comment", "body": "<p>…</p>", "created_at": 1760000000 } ] } } } }

• 只有新的部分. item.conversation_parts 仅保留导致事件的部分, 就像Intercom自己的有效载荷一样.
• 长相相出相出相. 该部分的时间戳和信封 created_at 使用真实 时间,绝不是模拟时钟,因为EMR将超过5分钟的部件拒绝用于其 拥有时钟.
• 稳定编号. 通知 id 复试和复试时保持不变 webhook_duplicate这样 后门的 delivery_id ?? id dedupe和EMR的处理-标记器 dedupe都持有.
• 复问. 非-2xx的回答在5 s, 5 min, 30 min和 2 h 之后重审.
• 行政飞机. GET /__admin/webhooks, (中文(简体) ), …/events, (中文(简体) ), …/flush, (中文(简体) ), …/:id/replay 财务报告和审定财务报表 PUT /__admin/webhook-endpoints 是标准的 webhook 管理员路径.

管理员(超过标准合同)

错误预设( E)POST /__admin/faults {"preset": "<name>", "count"?: n}:

命名空间

• 页:1 x-mockingbird-namespace 页眉;
• (单位:千美元) /__admin/ns/<name> 前缀在 INTERCOM_API_BASE_URL· ;
• 访问符号 : PUT /__admin/credentials {"credentials": {"<INTERCOM_ACCESS_TOKEN>": "<namespace>"}}。 。 。 .

请求日记记录了操作的ID,状态和联系,谈话和部分ID. 这个 从不记录信件机构或联系方式.

故意不模拟

• 成员- 应用程序 信使 SDK 和 Web 部件 (@intercom/intercom-react-native, (中文(简体) ), @intercom/messenger-js-sdk) (中文(简体) ). 他们通过自己的协议与Intercom自己的主机交谈. 这个 web 部件没有测试阶段的门, 因此 QA 应该屏蔽它 .
• 附件下载: URL已录入但未服务.
• 标记、笔记、公司、片段、门票、文章、数据属性管理、团队和 解放军. 这些只是有效载荷所在的空清单.
• 正常响应的速率限制头. 仅 rate_limited 派他们来.
• Intercom对同位素冲突的确切措辞,未经验证:仿真器答案 409个 conflict。 。 。 .

API 密码

部分 嘲笑鸟。 。 。 .