Typing Indicator

接入“正在输入”提示（Typing Indicator）

通过 API 触发 WhatsApp “正在输入”提示能力。 收到消息 Webhook表示已收到上行消息回执时，您可以使用 message.id 值将消息标记为已读并显示“正在输入”提示，以便 WhatsApp 用户知道您正准备回复。如果您需要几秒钟才能回复，这将是一种很好的做法。

在您回复后或 25 秒后（以先发生者为准），“正在输入”提示将关闭。为了避免糟糕的用户体验，仅在您要做出回复时，才显示“正在输入”提示。

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

鉴权机制

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

请求参数

Header 参数

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

Body 参数

参数名	类型	必选	示例值	说明
appkey	String	是	xxx	应用 appkey
messaging_product	String	是	whatsapp	消息通道，固定值 whatsapp
business_phone	String	是	xxx	商户手机号码（需带国码）
status	String	是	read	固定值 read
message_id	String	是	wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjkzRjVGODY0OTJCQzM5QzQ1MgA=	入站消息 ID（incoming message id）
typing_indicator	Object	是	{"type":"text"}	输入提示对象
typing_indicator.type	String	是	text	固定值 text

请求示例

{
  "appkey": "xxx",
  "messaging_product": "whatsapp",
  "business_phone": "xxx",
  "status": "read",
  "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjkzRjVGODY0OTJCQzM5QzQ1MgA=",
  "typing_indicator": {
    "type": "text"
  }
}

响应参数

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

响应示例

成功示例

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

错误案例 1：message_id 无效

{
  "code": 0,
  "data": {
    "error": {
      "code": 100.0,
      "message": "(#100) Invalid parameter",
      "type": "OAuthException",
      "fbtrace_id": "APoPA639oqWRwvF3dFSQsUz",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Please check the message ID you have provided."
      }
    }
  },
  "message": "success"
}

错误案例 2：message_id 为出站消息（非入站）

{
  "code": 0,
  "data": {
    "error": {
      "code": 100.0,
      "message": "(#100) Invalid parameter",
      "type": "OAuthException",
      "fbtrace_id": "A9PTrNfMQxS6EZ8uUlxAAey",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Message supplied to mark message as read API with message ID: wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjkzRjVGODY0OTJCQzM5QzQ1MgA= is outgoing. Please use an incoming message ID."
      }
    }
  },
  "message": "success"
}

失败示例：参数错误

{
  "code": 9000,
  "data": null,
  "message": "Invalid parameter (typing_indicator.type must be 'text')"
}

失败示例：系统失败

{
  "code": -1,
  "message": "failure",
  "data": null
}

响应码说明

code	message	解决办法
0	success	请求成功。若 data.error 非空，请按下游错误处理
-1	failure	系统异常，请联系技术人员排查
1000~100X	鉴权问题	详情查看 API 鉴权部分
9000	参数异常	参数遗漏或格式错误，请检查必填参数和固定值
9001	系统业务错误	请联系技术人员排除问题
9002	商户手机号错误	请确认商户号码是否属于 WhatsApp 号码
10003	该 WhatsApp 号码未绑定应用	请联系业务人员处理应用和手机号绑定操作

对接注意事项

1. status 必须传 read。
2. typing_indicator 必须传，且 typing_indicator.type 必须为 text。
3. message_id 必须是入站消息 ID，出站消息 ID 会触发下游 Invalid parameter。
4. 建议业务成功判定条件为：
   • code == 0
   • 且 data.error 不存在。