将Stella API应用于聊天机器人

Stella API允许外部应用程序在Stella中触发以下类型的机器人动作。

  • 发送响应。向聊天机器人用户发送一个特定响应类型的信息。
  • 重定向成员到节点。重定向到一个特定的节点，并为一个聊天机器人用户执行该节点。

常见的用例是，当你想激活Stella，根据你的外部应用程序的动作向用户发送消息。例如，你想在一个WhatsApp用户在你的网上商店完成购买并提供了WhatsApp号码后，向该用户发送一条购买确认信息。

开始实践

这个过程将教你如何在Postman上测试Stella API（即POST）。

发送回复

  1. 在Postman上创建一个新的请求，并在请求的URL上添加https://bot.stellabot.com/sendResponses。

Create a new Postman request

  1. 将请求类型改为 "POST"。

    1. 生成一个具有bot:sendResponses权限的访问令牌，并把它放到 "Params"下的 "VALUE"。在 "KEY"下标记accessToken。

Input Postman request Params
  1. 前往 "Body"，选择 "raw"和 "JSON"。

Select Postman Request Body Type
  1. 粘贴 "发送响应 "的主体代码。下面的代码只是一个例子，你应该根据你的需要来编辑响应。你可以在响应生成器的高级标签中找出响应对象的JSON。你还可以在Stella上生成不同类型的响应。
{
  "channelId": "5ece50e72efaabd58ef55027",
  "fbUserRef": null,
  "memberId": "5ece50f3bf385b25c4e08db5",
  "recipientId": null,
  "messagingType": "MESSAGE_TAG",
  "messagingTag": "CONFIRMED_EVENT_UPDATE",
  "response": [
    {
      "type": "TEXT",
      "text": "Hello World"
    },
    {
      "type": "IMAGE",
      "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
    }
  ]
}
  1. 你应该能从你的频道中找到频道ID，从会员页中找到收件人ID/会员ID/fbUserRef。

Input Postman Request Body
  1. 点击 "发送"。它应该返回以下200响应。

成功:

{
  "ok": 1,
  "member": "5ece50f3bf385b25c4e08db5",
  "sendResults": [
    {
      "result": [
        {
          "result": {
            "recipient_id": "10152368852405295",
            "message_id": "m_U0EmmN476hlyPr-0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          },
          "messageEvent": {
            "from": "124830722411862",
            "to": "10152368852405295",
            "data": {
              "text": "Hello World"
            },
            "type": "TEXT",
            "timestamp": 1583292367324,
            "messageId": "  -0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          }
        },
        {
          "result": {
            "recipient_id": "10152368852405295",
            "message_id": "m_U0EmmN476hlyPr-0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          },
          "messageEvent": {
            "from": "124830722411862",
            "to": "10152368852405295",
            "data": {
              "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
            },
            "type": "IMAGE",
            "timestamp": 1583292367324,
            "messageId": "  -0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          }
        }
      ]
    }
  ]
}
  • 失败:
{
  "ok": 0,
  "err_code": 108,
  "err": "Either memberId or recipientId or fbUserRef is required.\""
}

你也可以查看[错误代码列表]（https://doc.stella.sanuker.com/botapi/#section/Error-codes）。

重定向成员到节点

  1. 在一个树中创建一个树节点，并将这个树添加到你将用于这个POST请求的通道中。

  2. 在Postman上创建一个新的请求，并在请求的URL中添加https://bot.stellabot.com/redirectMemberToNode。

Create a new Postman request

  1. 将请求类型改为 "POST"。

    1. 生成一个具有bot:redirectMemberToNode权限的访问令牌，并把它放到 "Params"下的 "VALUE"。在 "KEY"下标记accessToken。

Input Postman request Params
  1. 前往 "Body"，选择 "raw"和 "JSON"。

Select Postman Request Body Type
  1. 粘贴 "重定向成员到节点"的主体代码。下面的代码只是一个例子，你应该把你在步骤1中创建的树形节点中的tree和nodeCompositeId改为the ones。
{
  "channelId": "5ece50e72efaabd58ef55027",
  "fbUserRef": null,
  "memberId": "5ece50f3bf385b25c4e08db5",
  "recipientId": null,
  "redirect": {
    "tree": "5ecf6cfba3b6643c33a64079",
    "nodeCompositeId": "j4Bivxm0GWhnNV1m",
    "runPreAction": true,
    "sendResponse": null,
    "runPostAction": false
  },
  "meta": {
    "name": "Sanuker",
    "orderId": "5ecf6be76fcfda6b139d802c"
  }
}
  1. 你应该能从你的频道中找到频道ID，从会员页中找到收件人ID/会员ID/fbUserRef。

Input Postman Request Body
  1. 点击 "发送"。它应该返回以下200响应。

成功。

{
  "ok": 1,
  "member": "5ece50f3bf385b25c4e08db5",
  "sendResults": [
    {
      "result": [
        {
          "result": {
            "recipient_id": "10152368852405295",
            "message_id": "m_U0EmmN476hlyPr-0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          },
          "messageEvent": {
            "from": "124830722411862",
            "to": "10152368852405295",
            "data": {
              "text": "Hello World"
            },
            "type": "TEXT",
            "timestamp": 1583292367324,
            "messageId": "  -0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          }
        },
        {
          "result": {
            "recipient_id": "10152368852405295",
            "message_id": "m_U0EmmN476hlyPr-0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          },
          "messageEvent": {
            "from": "124830722411862",
            "to": "10152368852405295",
            "data": {
              "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
            },
            "type": "IMAGE",
            "timestamp": 1583292367324,
            "messageId": "  -0iH2cXMcrTLJ5HeVUQjzqok8vkkF8wnJpPkagYbXU5hr0bXWHM5PPYjgd9RWG10K0oujeHQ"
          }
        }
      ]
    }
  ]
}
  • 失败:
{
  "ok": 0,
  "err_code": 108,
  "err": "Either memberId or recipientId or fbUserRef is required.\""
}

你也可以查看[错误代码列表]（https://doc.stella.sanuker.com/botapi/#section/Error-codes）。

进阶

如上一节所述，重定向成员到节点允许你将一个成员重定向到树中的特定节点，并执行该节点的全部或部分组件。这对于在成员上执行复杂的操作是非常有用的，并将所有的机器人逻辑保留在树中，而不是硬编码在一个api中。

在某些情况下，你可能想向客户发送定制的信息，而不是标准化的信息。因此，这个高级指南将演示你如何使用 "重定向成员到节点 "来发送带有变量的消息。

简介

在这个例子中，我们想使用重定向成员到节点向WhatsApp上的客户发送订单确认。该消息将包括一些变量，如购买的物品和订单号。

要做到这一点，你将需要利用meta对象，使用API将变量传递给节点。这些变量将被保存到成员的TempData中。之后，这些变量可以被提取并应用到你要发送的响应中。

Meta 物件

当应用重定向成员到节点时，你也可以使用API来传递元对象到目标节点。在这个例子中，Meta对象包含两个信息：orderID和item，我们希望以后把它们作为变量应用到响应中。

关于如何构建请求的更多细节，请参考[BotAPI]（https://doc.stella.sanuker.com/botapi/#operation/redirectMemberToNode）。

{
 "channelId": "611492017e746925434536d",
 "recipientId": "65874121234",
 "redirect": {
  "tree": "60ff7a60fe96167111244s",
  "nodeCompositeId": "gQEytkyMjZdwR69N"
 },
 "meta": {
  "orderID": "FP123456789",
  "item": "Graphic T-shirt"
 },
 "accessToken": "ACCESS_TOKEN",
 "headers": {
  "Content-Type": "application/json",
  "Origin": "https://bot.stellabot.com"
 }
}

模板信息提交

在我们开始建立节点之前，我们需要首先提交一个模板信息给WhatsApp进行审批。

  1. 按照这个指南来起草和提交您的模板信息到WhatsApp。

  1. 在创建模板时，你可以使用参数占位符，格式为{{1}}。

Example:

Your order {{1}} is ready! It will be deilvered within 3 days.

Item: {{2}}

Please contact our hotline if you have any questions.

创建一个节点

  1. 在Stella中，选择Bot Builder，首先创建一个新的树。

  1. 创建一个树形节点，这个树形节点将被用于 "重定向成员到节点"。最终用户将被重定向到这个节点，这个节点的组件将被执行。

创建一个预先行动--保存Meta物件

  1. 创建一个新的pre-action。

  1. 在预行动中插入以下代码。它是用来保存成员tempData中的Meta物件的。
return new Promise((resolve) => {
  this.member.botMeta.tempData.orderID = this.agendaMeta.orderID
  this.member.botMeta.tempData.item = this.agendaMeta.item
  resolve({ member: this.member })
})

在会员中，你可以查看会员资料中的临时数据。

将变量应用于响应

  1. 创建一个新的响应。

  1. 选择WhatsApp信息模板作为响应类型，并选择您刚刚创建的模板。

  1. 下面的代码可以让你访问保存在tempData中的变量。
{{botMeta.tempData.orderID}}
  1. 在填写模板信息的变量时，你可以在相应的字段中插入上述代码，并从tempData中获得相关信息。

  1. 现在，你可以通过向一个测试者发送 "重定向成员到节点 "的API请求进行测试，看看它是否能显示预期的订单确认信息。
← 将Agenda应用于聊天机器人将Web Event应用到Webchat的聊天机器人 →