在消息传送人工智能专员（旧版）中使用“进行 API 调用”步骤

What's my plan?

Suite

Any plan

本文所述功能仅限于以下客户使用：在 2025 年 2 月 2 日前已获取人工智能专员（未正式或已正式发布版本）。有关人工智能专员（高级）等效功能的信息，请参阅将其他平台与人工智能专员（高级）整合。

进行 API 调用步骤可以配置对另一个系统（例如内部 CRM 或 ERP）的 API 调用，或将对话详情推送到外部端点，例如 Amazon Event Bridge 或 Google Analytics（分析）。

在本文中，我们将带您了解在消息传送人工智能专员中添加和配置步骤所涉及的程序。

有关进行 API 调用步骤及其配置规则的概述，请参阅了解人工智能专员步骤类型：进行 API 调用。

本文章包括以下部分：

• 将“进行 API 调用”步骤添加到人工智能专员
• 添加 API 详情
• 保存来自 API 响应的变量
• 关于步骤分支

将“进行 API 调用”步骤添加到人工智能专员

将进行 API 调用步骤添加到人工智能专员涉及到各种任务。

以下程序假定您已经创建消息传送人工智能专员，并要在该人工智能专员中添加此步骤。

注意：如果被呼叫的系统在 10 秒钟内未响应，呼叫将超时。

添加“进行 API 调用”步骤

1. 在管理中心，单击侧栏中的人工智能 ()，然后选择人工智能专员 > 人工智能专员。
2. 单击管理消息传送人工智能专员。
3. 单击您要编辑的人工智能专员的名称。
4. 单击“答案”标签，然后创建一个新答案或打开一个现有答案。
5. 在智能机器人生成器中要插入该步骤的位置（分支末尾或两个现有步骤之间），单击添加步骤图标。
6. 在配置面板中，单击进行 API 调用。
7. 输入该步骤的描述信息。
   • 名称：便于团队识别的调用名称。
   • 描述（选填）：对调用所采取操作的简短描述。

   此信息对客户不可见。

8. 继续执行添加 API 详情中所述的步骤。

添加 API 详情

使用“API 详情”部分配置要进行的 HTTP 调用，包括 HTTP 请求方法、外部资源的位置，以及根据需要添加标头。以下步骤是上一部分程序的延续。

添加 API 详情

1. 在配置面板中，单击 API 详情。
2. 选择一个请求方法：
   • GET 可从 API 服务检索外部资源。这是最常用的方法。
   • POST 可发送数据以在外部系统中创建资源。如果资源已存在，则发送的数据将修改资源。
   • PUT 可发送数据以更新资源。
   • PATCH - 可发送数据以更新外部网站的资源，用于将部分修改应用于资源。
   • DELETE - 可移除外部资源。
3. 输入端点 URL。

   该端点 URL 是要连接的外部资源的位置，端点 URL 支持 https:// 协议。URL 的路径或查询字符串值中可以包含变量。有关更多信息，请参阅在 API 调用中传递变量。

4. （可选）选择一个连接以对 API 调用进行身份验证。
   注意：您必须先创建连接，才能在进行 API 调用步骤中使用。
5. 如果需要，请输入可选标头的键值和值。
   重要提示：请勿使用标头进行身份验证，而应改用 API 连接。

   包含身份验证相关标头（例如 authorization 或 x-api-key）的进行 API 调用步骤会自动失败。如果进行 API 调用步骤失败，对话将遵循该步骤的 API 调用失败分支。

6. 单击进行 API 调用以测试 API 调用。

   将变量添加到步骤的 URL 或标头可以在外部服务中包含可选的测试数据，以检查 API 调用是否如预期工作。请注意，这将向已配置的端点 URL 发出 HTTP 请求。

在 API 调用中传递变量

为 API 调用输入端点 URL，即可在 URL 的路径或查询字符串值中包含变量。这样可以将数据从对话传递到外部系统。

例如，消息传送人工智能专员可以使用询问详情步骤提示客户提供订单号。然后，人工智能专员可以使用进行 API 调用步骤从您的在线商店获取订单的送货状态。

端点 URL 的域名或子域名不能使用变量。下表列举了有效和无效端点 URL 值的示例。

有效端点 URL	无效端点 URL
https://myshopify.com/admin/api/orders/order_number.json 指定 Shopify 的订单 ID 以检索订单。	https://domain.com/api/search?input=value 变量不能添加到域名/子域名
https://maps.googleapis.com/maps/api/place?input=city_name 从 Google 的场所 API 按关键字搜索检索位置。	https://example.com/api/search?key=value 变量不能添加到查询字符串键值

如果变量无效或为空，人工智能专员将在对话期间跳过该变量。

注意：变量值不会自动翻译。在消息传送对话中使用自动翻译时，请务必记住这点。

保存来自 API 响应的变量

配置详情并测试 API 调用后，可以将 API 调用的 JSON 响应的值保存为变量。在进行 API 调用步骤中，最多可以保存 12 个变量。只保存变量值的前 280 个字符。

根据响应数据创建变量

1. 在配置面板中，单击进行 API 调用。
2. 展开折叠面板，并确定要转为变量的外部系统数据。
   提示：切换到响应正文标签可查看从外部系统返回的原始响应。
3. 单击保存。
4. 为新变量命名。

   变量名称只能包含小写字母、数字和下划线。

在 API 调用中传递数组变量

您可以使用进行 API 调用并向外部系统提供 URL 来传递数组变量。外部系统必须有 API 端点。API 端点是 API 接收请求并发送响应的 URL，允许两个系统进行交互。响应以 JavaScript 对象表示法 (JSON) 格式显示，示例如下。

{               
    "info": {   
        "count": 50,
        "pages": 2,
        "next": "https://mycompany.com/api/orders?page=2",
        "prev": null
    },      
    "results": [
        {   
            "id": 1052,
            "name": "Alexander Cummings",
            “address”: “123 MyStreet”,
            "Item": "belt",
            "price": "15.00",
            "image": "https://mycompany.com/api/orders/avatar/1.jpeg",
	…
    

管理中心仅显示数组变量中的前几个项目，以便可视化返回的数据。例如，在上述 JSON 输出中，id、name、address、item、price 和 image 都会显示出来。此数据通常被传递到轮播，但轮播最多只能显示 10 个项目。

注意：响应中仅显示属性值的前 280 个字符。

嵌套的 JSON 数组也可以保存为数组变量。例如，在以下 JSON 输出中，lastname 和 firstname 可以单独另存为数组变量。

"name": 
   {
      "lastname": "Cummings”,
      "firstname": “Alexander"
   },
    

在管理中心的轮播配置中无法编辑数组或数组值。如需更改任何数据，必须在管理中心删除该数组并创建一个新数组。

如果返回的变量为 null，则该项目不会显示在轮播中。例如，在以下场景中，假设变量 {{customer.order}} 的值为空。其中，卡片 1 将显示为“订单号”的部分标题，卡片 2 则因生成的标题为空而不会显示。

Card 1
Title: Order number {{customer.order}}
Description: Here's your order {{product.description}}

Card 2
Title: {{customer.order}}
Description: Here's your order {{product.description}}
    

示例

本例中，我们使用一个可返回订单数组的 API 端点创建了一个数组变量。orders 数组由以下 API 响应代码段中的“results”属性指定。

     {
  "info": {
   "count": 5,
   "pages": 1
  },
  "results": [
   {
    "createdAt": "July 10, 2023",
    "name": "Connie Stokes",
    "Shippingaddress": "123 Street, City, State",
    "order": {
      "Status": "Ordered",
      "Image": "https://images.pexels.com/photos/1484808/pexels-photo-1484808.jpeg"
    },
    "Quantity": 1,
    "Price": 45,
    "Item": "Shirt",
    "id": "1"
   },
…   

本例使用进行 API 调用创建了数组变量，然后使用动态轮播向终端用户显示结果。

创建数组

1. 在配置面板中，单击进行 API 调用。
2. 输入 orders 作为名称。
3. 在配置面板中，单击 API 详情。
4. 单击请求方法下拉菜单，然后选择 GET。
5. 输入 URL 作为端点 URL。
6. 对于身份验证，选择您的身份验证方法。

   有关更多信息，请参阅创建连接以与外部服务整合。

7. 单击进行 API 调用。
8. 单击结果旁边的保存。

   

9. 从值下拉菜单中选择 Order，然后选择 Image。

   使用默认变量名称 (image)。

10. 单击添加项目，然后重复上述步骤，为 Order Status 和 Item 创建项目。

    最多可添加 12 个项目（或键值对）。

    

11. 单击保存。

创建动态轮播

1. 在智能机器人生成器中，单击 API 调用成功下的添加步骤，然后选择添加轮播。
2. 在配置面板中，单击转换为动态消息。
3. 在数组下拉菜单中，单击结果。随即显示上面创建的数组。
4. 对于标题，单击加号，选择 results.item。

   对于标题和描述，您最多可以输入 128 个字符。

5. 对于按钮链接，单击加号，选择 results.image。
6. 对于按钮文本，单击加号，选择 results.status。
7. 对于图像链接，单击加号，选择 results.image。
8. 单击完成。

   

以下是一个动态轮播的例子。

关于步骤分支

进行 API 调用步骤是分支步骤。添加此步骤可根据 API 请求是否成功执行来拆分人工智能专员响应。

在以下情况下，人工智能专员将沿失败分支下移：

• API 返回 400 或 500 响应代码。
• API 返回 200 响应代码（如果保存的变量之一缺失或有 null 值）。

在所有其他情况下，人工智能专员将沿成功分支下移。

使用进行 API 调用步骤即表示您确认所连接的外部系统是 Non-Zendesk Service（定义见主要服务协议）。Zendesk 不运营或控制通过工作流程生成器扩展功能启用的 Non-Zendesk Service，并对您或 Non-Zendesk Service 的法律或合规义务概不负责。