username

业务账号（Username）管理

业务账号（Username）可用于展示业务身份。商企可以采用业务账号，但采用业务账号不会隐藏 WhatsApp 或 WhatsApp Business 客户端中的业务电话号码。

在整个 WhatsApp 体系内：

• 一个业务账号对应单一业务电话号码。
• 一个电话号码在任何时候只能有一个账号。
• 两个 WhatsApp 电话号码（包括消费者或商企号码）不能使用相同账号。

聊天窗口显示优先级

在应用聊天窗口中展示业务主页信息时，优先级从高到低如下（业务电话号码始终会显示）：

1. 已保存的联系人姓名
2. 已认证的商企名称或官方商业账户名称
3. 账号（Username）
4. 电话号码

业务账号格式规则

业务账号必须遵循以下规则：

• 只能包含英文字母（a-z）、数字（0-9）、句点（.）和下划线（_）字符
• 不支持非英文字符（如 ñ、é、ü）
• 长度须介于 3 至 35 个字符之间
• 须包含至少一个英文字母（a-z、A-Z）
• 不得以句点开头或结尾，亦不得包含连续 2 个句点
• 不得以 www 开头
• 不得以网域结尾（如 .com、.org、.net、.int、.edu、.gov、.mil、.us、.in、.html 等）
• 账号比较时忽略大小写，但不忽略句点和下划线
  • myID 和 myid 视为同一账号
  • myid、my.id、my_id 视为不同账号

功能

此 API 包含 4 个接口：

// 采用或更改业务账号
/api/wa/setUsername

// 获取当前账号
/api/wa/getUsername

// 获取预留账号
/api/wa/suggestionsUsername

// 删除账号
/api/wa/deleteUsername

鉴权机制

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

请求参数

header参数

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

---

采用或更改业务账号

接口

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

body参数

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

请求示例

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

响应结果

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

data 对象

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

响应示例

成功：

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

失败：

{
  "code": 0,
  "data": {
    "error": {
      "code": 3.0,
      "message": "Authorization Error",
      "type": "OAuthException",
      "fbtrace_id": "AKCCGckqmBZdcdqdgCi71WI"
    }
  },
  "message": "success"
}

---

获取当前账号

获取业务电话号码关联的业务账号状态或账号信息。

接口

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

body参数

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

请求示例

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

响应结果

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

data 对象

参数	描述
username	当前生效的业务账号
status	账号状态（例如 ACTIVE）

响应示例

已设置账号：

{
  "code": 0,
  "data": {
    "username": "nxcxxx",
    "status": "ACTIVE"
  },
  "message": "success"
}

未设置账号：

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

---

获取预留账号

获取已为当前业务资产组合预留的账号列表。

接口

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

body参数

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

请求示例

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

响应结果

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

data 对象

参数	描述
username_suggestions	预留账号候选列表（数组）
error	错误对象。失败场景返回

响应示例

{
  "code": 0,
  "data": {
    "username_suggestions": [
      "nxcxxx",
      "nxclxxxt",
      "nxxx",
      "nxclxxxxd"
    ]
  },
  "message": "success"
}

---

删除账号

删除业务电话号码关联的业务账号。

接口

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

body参数

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

请求示例

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

响应结果

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

data 对象

参数	描述
success	布尔值。删除成功时返回 true
error	错误对象。失败场景返回，常见字段有 code、message、type、fbtrace_id、is_transient

响应示例

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

响应码说明

code	message	说明
0	success	请求已受理；若 data.error 非空，按失败处理
-1	failure	系统异常
1000~100X	鉴权问题	详见鉴权文档
9000	参数异常	参数缺失或格式错误
9001	系统业务错误	业务处理异常
9002	商户手机号错误	请确认 business_phone 是否有效
10003	该 WhatsApp 号码未绑定应用	请先完成应用与号码绑定

对接注意事项

1. 入参核心是 business_phone，其余参数采用 map body 方式透传。
2. 采用或更改账号时，username 为必填。
3. 建议成功判定条件：
   • code == 0
   • 且 data.error 不存在。
4. code == 0 仅表示网关/服务请求成功，不代表下游业务一定成功，需检查 data.error。

附录 webhook

应用webhook监听事件 business_username_updates

当业务账号状态更改时，会触发此 Webhook。

• username — 状态发生变更的账号。如果 status 设置为 deleted，则省略。
• status — 值可以是：

1. approved — 表示账号已通过审核并对 WhatsApp 用户可见。当账号的状态从 reserved 更改为 approved，或账号通过 WhatsApp Business 应用进行更改时触发。
2. deleted — 表示账号已通过 WhatsApp Business 应用被删除。
3. reserved — 表示账号是为业务电话号码预留的，但对 WhatsApp 用户不可见。账号功能对所有人开放后，该账号就会变为可见。

{
    "field": "business_username_updates",
    "value": {
        "business_phone": "xxx",
        "display_phone_number": "xxx",
        "status": "approved",
        "time": 1780275371,
        "username": "xxx",
        "wabaId": "xxx"
    }
}