pandamobo – 第 2 页 – JoinMC WhatsApp API 接口文档

请求验证码

请求方式

POST /whatsapp/phoneNumbers/requestCode HTTP/1.1
Host: https://{your-domain}/api/open/v1

请求头

字段	类型	注释
X-API-Key	string	必填，API 密钥

请求参数

{
  “phone_number_id”: “1906385232743451”,
  “code_method”: “SMS”,
  “language”: “en_US”
}

字段	类型	注释
phone_number_id	string	是，电话号码 ID
code_method	string	否，验证码方式，默认 SMS，可选 SMS 或 VOICE
language	string	否，语言，默认 en_US

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {}
}

字段	类型	注释
code	int	状态码
msg	string	提示信息
data	object	返回数据

注册验证电话号码

请求方式

POST /whatsapp/phoneNumbers/registerPin HTTP/1.1
Host: https://{your-domain}/api/open/v1

请求头

字段	类型	注释
X-API-Key	string	必填，API 密钥

请求参数

{
“phone_number_id”: “1906385232743451”,
“pin”: “123456”
}

字段	类型	注释
phone_number_id	string	是，电话号码 ID
pin	string	是，6位 PIN 码

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {}
}

字段	类型	注释
code	int	状态码
msg	string	提示信息
data	object	返回数据

创建电话号码

请求方式

POST /whatsapp/phoneNumbers/register HTTP/1.1
Host: https://{your-domain}/api/open/v1

请求头

字段	类型	注释
X-API-Key	string	必填，API 密钥

请求参数

{
  “waba_id”: “918802267845274”,
  “phone_number”: “+15551234567”,
  “verified_name”: “My Business”,
  “cc”: “US”,
  “migrate_phone_number”: false
}

字段	类型	注释
waba_id	string	是，WABA 账户 ID
phone_number	string	是，电话号码
verified_name	string	是，已验证名称
cc	string	是，国家代码
migrate_phone_number	bool	否，是否迁移电话号码，默认 false

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {}
}

字段	类型	注释
code	int	状态码
msg	string	提示信息
data	object	返回数据

获取手机号列表

请求方式

GET /whatsapp/phoneNumbers HTTP/1.1
Host: https://{your-domain}/api/open/v1

请求头

字段	类型	注释
X-API-Key	string	必填，API 密钥

请求参数

字段	类型	注释
waba_id	string	是，WABA 账户 ID
page	int	否，页码，默认 1
limit	int	否，每页条数，默认 10
fields	string	否，指定返回字段

可用 fields 字段：id, display_phone_number, verified_name, status, quality_rating, country_code, country_dial_code, code_verification_status, account_mode, host_platform, messaging_limit_tier, is_official_business_account

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {
    “data”: {
      “0”: {
        “id”: “1906385232743451”,
        “display_phone_number”: “+1 631-555-5555”,
        “verified_name”: “Jasper’s Market”,
        “status”: “CONNECTED”,
        “quality_rating”: “GREEN”,
        “country_code”: “US”,
        “country_dial_code”: “1”,
        “code_verification_status”: “VERIFIED”,
        “account_mode”: “LIVE”,
        “host_platform”: “CLOUD_API”,
        “messaging_limit_tier”: “TIER_1K”,
        “is_official_business_account”: true
      }
    },
    “total”: 1,
    “per_page”: 10,
    “current_page”: 1
  }
}

字段	类型	注释
id	string	电话号码 ID
display_phone_number	string	显示电话号码
verified_name	string	已验证名称
status	string	连接状态
quality_rating	string	质量评级
country_code	string	国家代码
country_dial_code	string	国家拨号代码
code_verification_status	string	验证码验证状态
account_mode	string	账户模式
host_platform	string	托管平台
messaging_limit_tier	string	消息发送限制层级
is_official_business_account	bool	是否为官方商业账户
total	int	总记录数
per_page	int	每页条数
current_page	int	当前页码

获取 WABA 账户信息

请求方式

GET /whatsapp/wabaInfo HTTP/1.1
Host: https://{your-domain}/api/open/v1

请求头

字段	类型	注释
X-API-Key	string	必填，API 密钥

请求参数

字段	类型	注释
waba_id	string	否，WABA账户ID，不传则返回该团队下所有WABA

返回的结果

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {
    “id”: “1234567890123456”,
    “name”: “My Business WhatsApp Account”,
    “timezone_id”: “1”,
    “message_template_namespace”: “ba30dd89_2ebd_41e4_b805_f2c05ae04cc9”,
    “account_review_status”: “APPROVED”,
    “business_verification_status”: “VERIFIED”,
    “country”: “US”,
    “ownership_type”: “SELF”,
    “primary_business_location”: “US”
  }
}

注：查询全部时，data 为以索引为 key 的对象列表，例如：

{
  “code”: 1,
  “msg”: “OK”,
  “data”: {
    “0”: {“id”: “918802267845274”, “name”: “My Business”},
    “1”: {“id”: “918802267845275”, “name”: “Another Business”}
  }
}

字段	类型	注释
id	string	WABA 账户 ID
name	string	账户名称
timezone_id	string	时区 ID
message_template_namespace	string	消息模板命名空间
account_review_status	string	账户审核状态
business_verification_status	string	企业认证状态
country	string	国家代码
ownership_type	string	所有权类型
primary_business_location	string	主要业务所在地

入门指导

概述

WhatsApp 开放 API 提供了一套完整的 WhatsApp Business API 接入能力，支持手机号管理、模板管理、消息发送、WABA 信息查询等功能。

先决条件：需要在JoinMC完成WABA账号申请，公司完成认证与账号状态正常，才能发送消息。申请WABA等操作指导可以查看帮助文档：https://www.kdocs.cn/l/cuxBnjmOoEtD

基础信息

Base URL: https://cn.joinmc.cn/api/open/v1
认证方式: 请求头 X-API-Key: {your_secret_key}（从 JoinMC打开社交账号页面选择WhatsApp页签，点击页面右上角的API设置按钮后获取
Content-Type: application/json
响应格式: JSON

通用响应结构

{
  “code”: 1,
  “msg”: “OK”,
  “data”: { … }
}

字段	类型	注释
code	int	1-成功，0-失败，400-参数错误，401-认证失败，403-无权限，404-未找到
msg	string	提示信息
data	object/array	返回数据

错误码说明

字段	类型	注释
1	int	成功
0	int	业务失败
400	int	参数错误
401	int	认证失败（API Key无效或缺失）
403	int	无权限访问该资源
404	int	资源未找到（WABA或手机号不存在）

注意事项

所有接口均需通过 X-API-Key 请求头认证，密钥从 JoinMC后台获取。
手机号列表接口会自动从 WhatsApp 官方同步最新数据。
模板列表接口会自动同步最新模板数据到本地库。
发送模板消息时，系统会自动判断是否收费并记录消费。
接口访问频率请合理控制，避免触发 WhatsApp 官方限制。

demo文件：demo py文件请用python执