自定义收件箱集成

网络钩子

验证

所有 webhook 事件都将在标头中带有签名（“X-Stella-Signature”）以进行验证。 可以使用以下方法验证每个 webhook 事件。

  1. 使用 HMAC-SHA256 算法，以通道密钥作为密钥，计算请求正文的摘要。
  2. 确认 Base64 编码的摘要与 X-Stella-Signature 请求头中的签名匹配。

入站消息

Stella 会以 2 种形式将它接收到的所有事件中继到您指定的 webhook。

原始入站消息

通过订阅此 webhook，您将收到我们正在接收的原始事件 请注意，在 Messenger 上，事件结构将略有修改。

Sample from WhatsApp

文本

{
  "contacts": [
    {
      "profile": {
        "name": "Roy"
      },
      "wa_id": "85260903521"
    }
  ],
  "messages": [
    {
      "from": "85260903521",
      "id": "ABGGhSYJA1IfAgo6qRe8bWPLEpxD",
      "text": {
        "body": "Hello"
      },
      "timestamp": "1599536864",
      "type": "text"
    }
  ]
}

视频

{
  "contacts": [
    {
      "profile": {
        "name": "Roy"
      },
      "wa_id": "85260903521"
    }
  ],
  "messages": [
    {
      "from": "85260903521",
      "id": "ABGGhSYJA1IfAgo6koySp3Sro3ro",
      "timestamp": "1599537042",
      "type": "video",
      "video": {
        "id": "e8a85916-2386-49dc-8f05-1cd0527bfb68",
        "mime_type": "video/mp4",
        "sha256": "586cc370c535661c16e662f9cd2987215a878efd929073230de7cf5ec0c867ff"
      }
    }
  ]
}

标准化入站消息

通过订阅此 webhook，您将收到 Stella 为所有支持平台预处理的规范化事件。

来自 WhatsApp 的示例

文本

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "TEXT",
  "data": {
    "text": "Hello"
  }
}

视频

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "MISC",
  "data": {
    "attachments": [{
      "type": "VIDEO",
      "waMediaId": "e8a85916-2386-49dc-8f05-1cd0527bfb68",
    }],
  }
}

出站消息

机器人回复的消息

当成员（最终用户）liveChat 属性为false 时，Stella 会将聊天机器人发送的消息发送到您指定的 webhook。

手动消息

通过 Stella sendResponse API 发送的所有消息也将作为类型“MANUAL”发送到您指定的 webhook。

中继消息

当成员（最终用户）liveChat 属性为true 时，Stella 会将消息转发到相应的配对频道，并且这些消息将作为类型 ``RELAY发送到您指定的 webhook.

body

PropertyTypeDescription
typeStringCan be either BOT, MANUAL or RELAY. Indicating whether the outbound message is from the chatbot or from API
messageEventObjectmessageEvent object container the normalised message
appStringID of the app
channelStringID of the chanel
messageEvent
PropertyTypeDescription
fromStringID of the sender
toStringID of the receipient
timestampNumberUnix timestamp
typeStringMessage type*
dataObjectMessage data for the corresponding message type*
messageIdStringMessage ID from the external platform (this property might not exists)

*Please refer to the official documentation for all the message types and the structure of the corresponding message data here

Sample event
{
  type: "BOT",
  app: "app-id",
  channel: "channel-id",
  messageEvent: {
    from: "1332323131312",
    to: "443232332323",
    timestamp: 1599093015000,
    type: "TEXT",
    data: {
      text: "Hello World"
    },
    messageId: "gBGHYoUiNWZwfwIJbtM1ryHfqTdp"
  }
}

###取消授权

当用户从他的 Stella 应用程序中删除收件箱解决方案集成时，一个事件将发送到指定的 webhook URL。

示例事件
{
  "account": "account-id",
  "timestamp": 1599527673000
}

API

授权

所有 API 的授权都需要查询参数“access_token”。 访问令牌可以在 Stella 平台上生成。 对于微调授权，可以生成具有特定“范围”的“access_token”。

集成 API

创建集成

scope: admin:app、api:admin、integration:admin、integration:write

API 端点

PUT /integration?access_token=some-access-token

请求正文

预期的主体是 JSON 类型，所有字段都可以自定义，除了字段 id 保留供内部使用。 集成对象应存储第三方集成所需的所有凭据，这些凭据稍后可用于机器人流程。

响应体
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
integrationIdStringID of the integration in Stella
errorObjectError object contains message field for a detailed description of the error
样品申请
PUT '/integration?access_token=some-access-token' \
--header 'Content-Type: application/json' \
--data '{
  "accessToken": "some-token",
  "clinetId": "33233323332113",
  "clientKey": "1dasd#%5rsDD"
}'
样品申请
{
  ok: 1,
  integrationId: "ad2T3wdsd2Gff"
}

删除集成

Scopes: admin:app, api:admin, integration:admin, integration:delete

API 端点
DELETE /integration/:integrationId?access_token=some-access-token
请求参数
PropertyTypeDescription
integrationIdStringid of the integration (required)
响应体
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
errorObjectError object contains message field for a detailed description of the error
样品申请
DELETE /integration/ad2T3wdsd2Gff?access_token=some-access-token
样品申请
{
  ok: 1
}

列出集成

scope: admin:app, api:admin, integration:admin, integration:read

API 端点
GET /integrations?access_token=some-access-token
请求参数
PropertyTypeDescription
integrationIdStringid of the integration (required)
请求体
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
integrations[Object]List of integration objects under the calling OAuth client
errorObjectError object contains message field for a detailed description of the error
样品申请
DELETE /integration/ad2T3wdsd2Gff?access_token=some-access-token
样品申请
{
  ok: 1
}

###文件API

从 WhatsApp 媒体 ID 获取文件

scope: admin:app, api:admin, file:admin, file:waGet

API 端点
GET /file/whatsapp/:mediaId?channel=wa-channel-id&access_token=some-access-token
请求参数
PropertyTypeDescription
mediaIdStringid of the file received from WhatsApp webhook when receiving inbound voice, image, video, file messages (required)
channelStringid of the WhatsApp channel on Stella (required)
响应体
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
urlStringPublic URL of the requested media
errorObjectError object contains message field for a detailed description of the error

发送 API

发送回复

scope: admin:app, api:admin, bot:admin, bot:sendResponses

请参阅 此处 以获取详细文档。

会员API

获取会员

scope: admin:app, api:admin, member:admin, member:read

API 端点
GET /member?member_id=member-id&external_id=extenal-id&access_token=some-access-token
请求参数
PropertyTypeDescription
external_idStringPlatform-specific ID of the member i.e. PSID for Messenger, phone number (WAID) for WhatsApp, etc. (Either external_id or member_id is required)
member_idStringID of the member in Stella (Either external_id or member_id is required)
响应体
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
memberObjectmember object in Stella. Please see the documentation on Member for more details
errorObjectError object contains message field for a detailed description of the error
示例请求
GET /member?external_id=external-id&access_token=some-access-token
示例响应
{
  ok: 1,
  member: {
    "_id" : "5efaeba88bb86af1c4dad0b5",
    "externalId" : "85260903521",
    "app" : "app-id",
    "channel" : "channel-id",
    "platform" : "whatsapp",
    "profile" : {
        "name" : "Roy"
    },
    "tags" : [],
    "meta" : {},
    "botMeta" : {
        "subscribe" : true,
        "liveChat" : false,
        "tempData" : {}
    },
    "botId" : "",
    "admin" : null,
    "group" : null,
    "fbId" : null,
    "firstName" : "Roy",
    "lastName" : null,
    "name" : null,
    "profilePic" : null,
    "gender" : null,
    "locale" : null,
    "email" : null,
    "profilePicString" : null,
    "createdAt" : 1593502632638.0,
    "etag" : "d-ofrj2T5gf2N6yqpvr/eQdNgcqUs",
    "_version" : 2
  }
}

切换实时聊天

Scopes: admin:app, api:admin, member:admin, member:write

API 端点
PATCH /member/live_chat?access_token=some-access-token
请求正文
PropertyTypeDescription
externalIdStringPlatform-specific ID of the member i.e. PSID for Messenger, phone number (WAID) for WhatsApp, etc. (Either externalId or memberId is required)
memberIdStringID of the member in Stella (Either externalId or memberId is required)
liveChatBooleanUpdate member's liveChat property to true or false
响应体
PropertyTypeDescription
okNumber1 means successful and 0 means unsuccessful
memberIdStringID of the member in Stella
errorObjectError object contains message field for a detailed description of the error
样品申请
PATCH '/member/live_chat?access_token=some-access-token' \
--header 'Content-Type: application/json' \
--data '{
  "appId": "app-id",
  "externalId": "33233323332113",
  "liveChat": true
}'
样本响应
{
  ok: 1,
  memberId: "some_member_id"
}
← LUIS数据库 →