Conversational Components

对话组件（开场白与快捷命令）

对话组件（Conversational Components）用于增强 WhatsApp 用户与商企号码的交互体验，当前支持两类能力：

• 开场白（Prompts）：首次与用户聊天时展示的可点击预设文本
• 快捷命令（Commands）：用户在对话中输入 / 时可见的命令及说明

##呈现形式

• 这项体验在不同设备上的显示效果可能有所不同

应用场景

开场白（prompts）

• 开场白是您首次与某个用户聊天时出现在消息对话中的可定制、可轻触的文本字符串。例如：“计划旅行”或“制定健身计划”。
• 开场白非常适合展开服务互动，如客户支持或账户服务。例如，您可以在自己的应用或网站上嵌入一个 WhatsApp 按钮。
• 用户轻触该按钮后，将跳转到 WhatsApp 界面，在那里用户可以从一系列可定制的提示中进行选择，了解如何与您的服务互动。
• 当用户轻触开场白时，会触发标准的已收到消息 Webhook。开场白字符串会分配到 Payload 中的 body 属性。

快捷命令（commands）

• 命令由命令本身和提示组成，该提示会告知用户在使用该命令时会发生的事情。
• 例如，您可以定义以下命令： /imagine - Create images using a text prompt
• 当 WhatsApp 用户输入 /imagine cars racing on Mars 时，会触发消息接收 Webhook，其中包含该完整的文本字符串（分配到 body 属性）。
• 然后，您便可生成并返回一张在火星上赛车的图片。

能力限制

开场白（prompts）

• 单个业务电话号码最多可配置 4 条开场白
• 每条开场白最长 80 个字符
• 不支持表情符号
• 如果 WhatsApp 用户轻触了带有预填文本的通用链接（即 wa.me 链接 或 api.whatsapp.com 链接），开场白的用户界面将自动关闭。

快捷命令（commands）

• 单个业务电话号码最多可配置 30 个快捷命令
• command_name 最长 32 个字符
• command_description 最长 256 个字符
• 不支持表情符号

功能

此 API 包含 2 个接口：

// 设置对话组件-开场白和快捷命令
/api/wa/updateConversationalAutomation

// 获取对话组件-开场白和快捷命令
/api/wa/getConversationalAutomation

鉴权机制

鉴权规则请参考地址：API接口调用约定

请求参数

header参数

参数名	类型	必选	示例值	说明
accessKey	String	是	fme2na3kdi3ki	用户身份标识
ts	String	是	1655710885431	当前请求的时间戳（毫秒），服务端允许客户端请求最大时间误差为 60 秒
bizType	String	是	2	WhatsApp 业务类型，固定值 2
action	String	是	mt	WhatsApp 业务操作，固定值 mt
sign	String	是	6e9506557d1f289501d333ee2c365826	API 入参参数签名，见鉴权文档

---

设置对话组件-开场白和快捷命令

用于为指定商户 WhatsApp 号码配置开场白（prompts）和快捷命令（commands）。

接口

• URL：https://api2.nxcloud.com/api/wa/updateConversationalAutomation
• Method：POST
• Content-Type：application/json
• 需要鉴权：是

body参数

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	应用 appkey
business_phone	String	是	xxx	商户 WhatsApp 号码（需带国码）
messaging_product	String	是	whatsapp	固定值 whatsapp
prompts	String[]	否	["Book a flight","plan a vacation"]	开场白列表，最多 4 条，每条最长 80 个字符
commands	Object[]	否	见请求示例	快捷命令列表，最多 30 条
commands[].command_name	String	是	tickets	命令名称，最长 32 个字符
commands[].command_description	String	是	Book flight tickets	命令描述，最长 256 个字符

说明：

• prompts 和 commands 可按需配置其一或同时配置
• 相关文本不支持表情符号

请求示例

设置开场白和快捷命令

{
  "appkey": "xxx",
  "messaging_product": "whatsapp",
  "business_phone": "xxx",
  "prompts": [
    "Book a flight",
    "plan a vacation"
  ],
  "commands": [
    {
      "command_name": "tickets",
      "command_description": "Book flight tickets"
    },
    {
      "command_name": "hotel",
      "command_description": "Book hotel"
    }
  ]
}

设置开场白

{
  "appkey": "xxx",
  "messaging_product": "whatsapp",
  "business_phone": "xxx",
  "prompts": [
    "Book a flight",
    "plan a vacation"
  ]
}

清空开场白和快捷命令

{
  "appkey": "xxx",
  "messaging_product": "whatsapp",
  "business_phone": "xxx",
  "prompts": [
  ],
  "commands": [
  ]
}

响应结果

参数	描述
code	状态码，0表示成功
message	响应消息
data 对象	返回数据

data 对象

参数	描述
success	布尔值。设置成功时返回 true
error	错误对象。下游校验失败时返回，常见字段有 code、message、type、fbtrace_id

响应示例

成功：

{
  "code": 0,
  "data": {
    "success": true
  },
  "message": "success"
}

失败：

{
  "code": 0,
  "data": {
    "error": {
      "code": 100.0,
      "message": "(#100) Param prompts[1] must be at most 80 characters long.",
      "type": "OAuthException",
      "fbtrace_id": "Ar7-8qcpU3GzpuNgrb5TfJW"
    }
  },
  "message": "success"
}

---

获取对话组件-开场白和快捷命令

用于查询指定商户 WhatsApp 号码当前已配置的开场白和快捷命令。

接口

• URL：https://api2.nxcloud.com/api/wa/getConversationalAutomation
• Method：POST
• Content-Type：application/json
• 需要鉴权：是

body参数

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	应用 appkey
business_phone	String	是	xxx	商户 WhatsApp 号码（需带国码）
messaging_product	String	是	whatsapp	固定值 whatsapp

请求示例

{
  "appkey": "xxx",
  "messaging_product": "whatsapp",
  "business_phone": "xxx"
}

响应参数

参数名	类型	说明
code	Integer	结果编码
data	Object	请求结果（可能包含下游 error 对象）
message	String	请求结果说明

data Object

参数名	类型	说明
id	Integer	业务电话号码对应的下游 ID
conversational_automation	Object	当前配置的对话组件对象

conversational_automation Object

参数名	类型	说明
enable_welcome_message	Boolean	是否启用欢迎消息
id	Integer	对话组件配置 ID
prompts	Array[String]	当前配置的开场白列表
commands	Array[command Object]	当前配置的快捷命令列表

command Object

参数名	类型	说明
command_name	String	命令名称
command_description	String	命令描述

响应示例

配置过对话组件

{
  "code": 0,
  "data": {
    "conversational_automation": {
      "enable_welcome_message": false,
      "id": "1707588057223674",
      "prompts": [
        "Book a flight",
        "plan a vacation"
      ],
      "commands": [
        {
          "command_name": "tickets",
          "command_description": "Book flight tickets"
        },
        {
          "command_name": "hotel",
          "command_description": "Book hotel"
        }
      ]
    },
    "id": "661162737077678"
  },
  "message": "success"
}

未配置对话组件

{
    "code": 0,
    "data": {
        "id": "107327795550855"
    },
    "message": "success"
}

对接注意事项

1. messaging_product 固定传 whatsapp。
2. prompts 用于配置开场白，最多 4 条，每条最长 80 个字符。
3. commands 用于配置快捷命令，最多 30 条；其中 command_name 最长 32 个字符，command_description 最长 256 个字符。
4. 开场白和快捷命令文本均不支持表情符号。
5. code == 0 仅表示开放平台接口调用成功；如果返回体中存在 data.error，仍需按下游错误处理。
6. 用户点击开场白或输入快捷命令后，会以普通文本消息形式回调到消息 Webhook 中。

测试验证

对话组件配置完成之后，如要测试这些组件，请打开 WhatsApp 客户端，然后向您业务电话号码发起聊天。 对于开场白，如果您当前与该业务电话号码之间已存在聊天对话，则必须先删除该聊天对话：

1. 在 WhatsApp 客户端中打开该对话。
2. 轻触业务电话号码的主页。
3. 轻触清空聊天 > 清除所有消息。
4. 删除聊天。
5. 与商企发起新的聊天对话。 然后，您可以向该业务电话号码发送消息，以测试开场白。