Session Link

开发者 API

从您自己的系统获取指向客户会话的直达链接；如果客户或会话尚不存在，会自动创建。

WhatsApp
Instagram
REST API

从 MonoStore 安装在 monochat.ai 上查看

概览

一次 API 调用，传入渠道以及客户的电话号码或邮箱，即可返回在 MonoChat 中打开该客户会话的链接。如果客户或会话尚不存在，会自动创建。

把链接放进您的 CRM、客服系统或订单页面，团队就能从那里直接跳转到聊天。

亮点

打开或创建。 适用于指定 WhatsApp、Instagram 或其他渠道上的客户，可按电话号码或邮箱查找。
随调用即时分配。 在同一次调用中，按 ID 或邮箱把会话分配给某位客服，或分配给某个工作组。
同一客户，同一会话。 对同一客户和渠道再次调用，会返回已有的会话。

安装与设置

在 设置 › MonoStore › 应用 中安装 Session Link，或打开安装链接 app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA。如果您还没有 MonoChat 账号，通过该链接可以先注册，并自动为您安装应用。
在 个人资料 › API 令牌 下创建 API 令牌。令牌只会显示一次，请立即复制。请参阅 API 令牌。
打开 设置 › Session Link API。那里的文档会显示您工作区的准确接口地址和可直接复制的示例请求。请用您的某个渠道试用该示例。
在您的 CRM、客服系统或订单页面中添加一个“在 WhatsApp 上聊天”按钮，调用该 API 并打开返回的 url。

备注

该链接会为已登录且有权查看该会话的人打开 MonoChat。
该调用只会打开会话，不会向客户发送消息。如需主动联系，请使用 WhatsApp Template API。

功能

会话链接

返回结果包含在 MonoChat 中打开该会话的链接和会话 ID。

必要时创建客户

会用您发送的名和姓创建新客户；返回结果会告诉您该客户是否已存在。

分配

按 ID 或邮箱分配给某位客服，或分配给某个工作组。

文档页面

API 参考文档，包含您工作区的准确接口地址和可直接复制的示例请求。

API 参考

该调用是带有 JSON 请求体的 POST，使用 API 令牌进行身份验证。

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

<slug> 是您工作区的租户 slug，即您的 MonoChat 地址中 /tenants/ 之后的部分。
<app-folder> 是应用安装所在的文件夹。设置 › Session Link API 页面会显示填好这两项的完整地址。
请在 个人资料 › API 令牌 下创建令牌。请参阅 API 令牌。

请求字段

字段	是否必填	说明
`connectorBrand`	是	渠道类型，例如 `whatsapp` 或 `instagram`。
`channelUsername`	是	您的渠道在 MonoChat 中的用户名，例如不带 `+` 的 WhatsApp 号码。
`customer.identityType`	是	`phoneNumber` 或 `email`。
`customer.identity`	是	客户的电话号码（含国家区号，不带 `+`）或邮箱地址。
`customer.firstname`, `customer.lastname`	否	当客户在 MonoChat 中是新客户时使用。默认为 `-`。
`assignment.type`	否	`agent`（客服用户 ID）、`agentIdentity`（客服邮箱）或 `workgroup`（工作组 ID）。
`assignment.value`	使用 `assignment.type` 时必填	用于分配会话的 ID 或邮箱。

示例请求

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

响应

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

字段	说明
`url`	在 MonoChat 中打开该会话。
`sessionId`	会话 ID。同一渠道上的同一客户始终对应同一个会话。
`isOldUser`	当客户由本次调用创建时为 `false`。

错误

失败的调用会返回错误状态和一条消息：

消息	原因
`connectorBrand, channelUsername and customer fields are required`	缺少必填的顶层字段。
`customer.identityType must be one of: phoneNumber, email`	缺少 `identityType`，或其值不正确。
`customer.identity field is required`	缺少客户的电话号码或邮箱。
`Channel not found`	您的工作区中没有该类型且用户名相符的渠道。
`Customer Channel not found`	无法将该客户匹配到某个渠道身份。
`Agent user not found`	没有与 `assignment.value` 中的邮箱对应的客服。
`401`	缺少 `Authorization` 请求头，或令牌无效。