💻 开放平台接口文档

Open API 开放平台接口文档

1. 概述

本文档描述了 Open API 开放平台的接口规范，供开发者接入使用。
所有接口均基于 HTTP/HTTPS 协议，响应数据格式为 JSON。

1.1 环境配置

接口地址: https://openapi.a2c.chat/api/openapi

2. 认证鉴权

开放平台使用 Bearer Token 进行鉴权。在调用业务接口前，需先通过认证接口获取 accessToken，并在后续请求头中携带该 Token。

请求头示例：

Authorization: Bearer <your_access_token>

3. 接口列表

3.1 认证管理

3.1.1 获取访问令牌

获取用于后续接口调用的访问令牌。

接口地址: /open/auth/token
请求方式: POST
Content-Type: application/json

请求参数 (Body):

参数名	类型	必填	说明
appId	String	是	应用ID
appSecret	String	是	应用密钥

响应参数:

参数名	类型	说明
code	Integer	状态码 (200表示成功)
msg	String	提示信息
data	Object	响应数据
└─ accessToken	String	访问令牌
└─ expireIn	Long	过期时间（秒）

3.2 模板管理

3.2.1 获取模板列表

分页查询模板列表。

接口地址: /v1/templates
请求方式: GET

请求参数 (Query):

参数名	类型	必填	说明
wabaId	String	否	WABA ID
pageNum	Integer	否	页码 (默认1)
pageSize	Integer	否	每页条数 (默认10)

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
total	Long	总记录数
rows	Array	模板列表数据
└─ id	Long	模板ID
└─ name	String	模板名称
└─ wabaId	String	WABA ID
└─ language	String	语言
└─ category	Integer	类别
└─ status	Integer	状态
└─ body	String	模板内容
└─ templateType	Integer	模板类型
└─ qualityRating	Integer	质量评级
└─ headerVariable	Map	头部变量示例
└─ bodyVariable	Map	正文变量示例

3.2.2 获取可发送的模板

查询状态为 APPROVED (已批准) 的模板列表。

接口地址: /v1/templates/sendable
请求方式: GET

请求参数 (Query):

参数名	类型	必填	说明
wabaId	String	否	WABA ID

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Array	模板列表 (字段同上)

3.2.3 获取模板详情 (根据名称和语言)

接口地址: /v1/templates/{name}
请求方式: GET

请求参数:

参数名	类型	位置	必填	说明
name	String	Path	是	模板名称
language	String	Query	是	语言代码

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Object	模板详情 (字段同上)

3.2.4 获取模板详情 (根据ID)

接口地址: /v1/templates/detail/{id}
请求方式: GET

请求参数:

参数名	类型	位置	必填	说明
id	String	Path	是	模板ID

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Object	模板详情 (字段同上)

3.3 账号管理

3.3.1 查询 API 账号列表

接口地址: /v1/accounts
请求方式: GET

请求参数 (Query):

参数名	类型	必填	说明
wabaId	String	否	WABA ID
apiAccount	String	否	API 账号 (发送号码)
status	Integer	否	状态
numberStatus	Integer	否	号码状态

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Array	账号列表
└─ apiPhone	String	API 发送号码
└─ wabaId	String	WABA ID
└─ status	Integer	状态
└─ numberStatus	Integer	号码状态
└─ qualityRating	Integer	质量评级
└─ messagingLimit	Integer	消息限制
└─ verifiedName	String	已验证名称

3.3.2 获取指定客户手机号的 API 账号

根据客户手机号智能选择合适的 API 发送账号。

接口地址: /v1/accounts/{customerPhone}/account
请求方式: GET

请求参数:

参数名	类型	位置	必填	说明
customerPhone	String	Path	是	客户手机号

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Object	账号信息
└─ apiPhone	String	API 账号 (发送号码)
└─ type	Integer	状态类型 (1:有效会话, 2:会话已过期, 3:无会话记录, 5:号码无效, 6:号码不存在, 7:号码未启用)
└─ wabaId	String	WABA ID
└─ expirationTime	Date	会话过期时间
└─ numberStatus	String	号码状态

3.3.3 获取账号分组列表

接口地址: /v1/accounts/groups
请求方式: GET

请求参数 (Query):

参数名	类型	必填	说明
groupType	Integer	否	分组类型
accountGroupType	Integer	否	账号分组子类型

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Array	分组列表
└─ id	Long	分组ID
└─ groupName	String	分组名称
└─ groupType	Integer	分组类型

3.3.4 生成设备码

用于生成扫码登录所需的设备码。

接口地址: /v1/accounts/device-code
请求方式: POST
Content-Type: application/json

请求参数 (Body):

参数名	类型	必填	说明
groupId	Long	是	分组ID
groupType	Integer	是	分组类型 (1:普通组, 2:养号组)
accountType	Integer	是	账号类型 (1:web个人版, 2:web商业版)
ipMode	Integer	是	IP模式 (1:系统自动分配, 2:个人)
scanType	Integer	是	扫码类型 (1:web扫码, 2:安卓扫码, 3:设备码)
ip	Integer	否	IP ID (用户自定义IP时传入)
ipType	Integer	否	IP类别 (系统自动分配时传入: 1:动态ip, 2:养号IP, 3:业务IP)
ipCountryCode	String	否	IP国家代码
phone	String	否	手机号 (设备码登录必填)
country	String	否	国家

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Object	响应数据
└─ key	String	二维码Key

3.3.5 查询设备码状态

查询设备码的扫码状态和登录结果。

接口地址: /v1/accounts/device-code/query
请求方式: POST
Content-Type: application/json

请求参数 (Body):

参数名	类型	必填	说明
key	String	是	二维码Key

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Object	响应数据
└─ qrCode	String	二维码内容
└─ qrCodeStatus	Integer	二维码状态 (1:已生成, 2:已扫码, 3:已过期, 4:异常, 5:可用云设备数不足, 6:账号存在于回收站, 7:账号存在于账号列表)

3.4 WABA 管理

3.4.1 获取 WABA 账号列表

接口地址: /v1/wabas
请求方式: GET

请求参数 (Query):

参数名	类型	必填	说明
name	String	否	WABA名称 (模糊查询)

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Array	WABA列表
└─ wabaId	String	WABA账户ID
└─ name	String	姓名
└─ status	Integer	状态 (1:PENDING, 2:APPROVED, 3:REJECTED)
└─ apiConfigType	Integer	API配置类型 (1:ycloud, 2:chatApp, 3:cloudapi)

3.5 消息发送

3.5.1 发送普通消息

支持发送文本、图片、视频、音频、文档等类型的消息。

接口地址: /v1/messages
请求方式: POST
Content-Type: application/json

请求参数 (Body):

参数名	类型	必填	说明
to	String	是	接收方手机号
senderPhoneNumber	String	是	发送人手机号
type	Integer	是	消息类型 (1:文本, 2:图片, 3:视频, 4:音频, 5:文档)
content	String	条件必填	文本内容 (当 type=1 时必填)
url	String	条件必填	媒体文件链接 (当 type=2/3/4/5 时必填)
caption	String	否	媒体附言
fileName	String	否	文件名

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	String	消息ID

3.5.2 发送模板消息

发送模板消息，支持在没有会话记录的情况下自动创建客户和会话。

接口地址: /v1/messages/template
请求方式: POST
Content-Type: application/json

请求参数 (Body):

参数名	类型	必填	说明
senderPhoneNumber	String	是	发送人手机号
to	String	是	接收方手机号
templateId	Long	是	模板ID
headerVariables	Map	否	头部变量 (Key:变量名, Value:变量值)
bodyVariables	Map	否	内容变量 (Key:变量名, Value:变量值)
buttonVariables	List	否	按钮变量 (按顺序排列)

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	String	消息ID

3.6 IP资源管理

3.6.1 查询个人可用IP列表

接口地址: /v1/ipPool/listAvailable
请求方式: GET

请求参数 (Query):

参数名	类型	必填	说明
host	String	否	IP地址
groupId	Long	否	分组ID
pageNum	Integer	否	页码 (默认1)
pageSize	Integer	否	每页条数 (默认10)

响应参数:

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
total	Long	总记录数
rows	Array	IP列表数据
└─ id	Integer	主键ID
└─ host	String	IP地址
└─ port	Integer	端口
└─ userId	String	用户名
└─ password	String	密码

4. Webhook 通知

4.1 概述

开放平台支持通过 Webhook 将关键事件（如客户消息）实时推送到开发者配置的服务器地址。
开发者需要在应用后台配置 Webhook URL。当事件触发时，开放平台会向该 URL 发送 HTTP POST 请求。

请求方式: POST
Content-Type: application/json

4.2 消息格式

4.2.1 外层消息结构

所有 Webhook 推送消息均遵循统一的外层结构：

参数名	类型	说明
id	String	消息唯一ID (UUID)
timestamp	Long	推送时间戳 (毫秒)
type	String	消息类型 (CUSTOMER_MESSAGE)
data	Object	业务数据对象

4.2.2 客户消息数据 (type=CUSTOMER_MESSAGE)

当 type 为 CUSTOMER_MESSAGE 时，data 字段包含具体的客户消息内容：

参数名	类型	说明
messageId	String	消息ID
content	String	消息内容 (文本消息时非空)
from	String	发送方手机号
to	String	接收方手机号
msgType	String	消息类型 (text, image, video, audio, document)
timestamp	Long	消息发送时间戳
nickname	String	发送方昵称
headImg	String	发送方头像URL
fileName	String	文件名 (媒体消息)
url	String	媒体文件链接
caption	String	媒体附言
duration	Integer	语音/视频时长(秒)
thumbnail	String	缩略图/封面图链接

4.3 响应与重试

响应: 开发者服务器在接收到 Webhook 请求后，应返回 HTTP 200 状态码表示接收成功。
重试: 如果请求失败（非 200 响应或超时），开放平台将自动重试 3 次。

4.4 示例

请求示例 (文本消息):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1710654000000,
  "type": "CUSTOMER_MESSAGE",
  "data": {
    "messageId": "wamid.HBgNN...",
    "content": "Hello World",
    "from": "1234567890",
    "to": "0987654321",
    "msgType": "text",
    "timestamp": 1710654000,
    "nickname": "John Doe",
    "headImg": "https://example.com/avatar.jpg"
  }
}