WABA API

WABA Account & Templates

模板资源说明
创建模板
删除模板
获取模板详情
获取模板列表
获取WABA账号信息

模板资源说明

资源示例

{
    "template_id": "2445248382535213",
    "name": "test_all_components_1",
    "language": "en_US",
    "category": "MARKETING",
    "status": "REJECTED",
    "quality": "",
    "components": [
        {
            "type": "HEADER",
            "format": "IMAGE",
            "example": {
                "header_link": [
                    "https://waba-crm.oss-ap-southeast-1.aliyuncs.com/storage/img/ea/43d3741b272e9a84656e4cd7169d16.jpg"
                ]
            }
        },
        {
            "type": "BODY",
            "text": "A test template, first parameter: {{1}}, second parameter: {{2}}",
            "example": {
                "body_text": [
                    [
                        1,
                        2
                    ]
                ]
            }
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "COPY_CODE",
                    "example": "123456"
                },
                {
                    "type": "PHONE_NUMBER",
                    "text": "CALL",
                    "phone_number": "6281519236680"
                },
                {
                    "type": "URL",
                    "text": "Our site",
                    "url": "https://chat.incsapp.com?from=",
                    "example": "whatsapp"
                },
                {
                    "type": "QUICK_REPLY",
                    "text": "Need help?"
                }
            ]
        },
        {
            "type": "FOOTER",
            "text": "welcome"
        }
    ],
    "created_time": 1755254297,
    "updated_time": 1755254308,
    "status_updated_time": 0,
    "quality_updated_time": 0,
    "category_updated_time": 0
}

字段说明

字段名	类型	描述
template_id	string	whatsapp template id
name	string	模板名称，最长为100
language	string	whatsapp 允许的语言code列表，见下述支持的语言列表
category	string	模板类型，支持 MARKETING，UTILITY，AUTHENTICATION 模板类别可能发生变更，及时获取变更需要设置模板更新回调
status	string	whatsapp 审核状态，见下述模板状态，及时获取模板状态变更需要设置模板更新回调
quality	string	模板质量评分：UNKNOWN（待定），GREEN（高质量），YELLOW（中等质量），RED（低质量），及时获取模板质量评分变更需要设置模板更新回调
components	array	模板组件, 见下述模板组件
created_time	timestamp	模板创建时间
updated_time	timestamp	模板最后更新时间
status_updated_time	timestamp	模板状态最后更新时间
quality_updated_time	timestamp	模板质量评分最后更新时间
category_updated_time	timestamp	模板类别最后更新时间

支持的语言列表

语言	代码
南非荷兰语	af
阿尔巴尼亚语	sq
阿拉伯语	ar
阿塞拜疆语	az
孟加拉语	bn
保加利亚语	bg
加泰罗尼亚语	ca
中文（中国大陆）	zh_CN
中文（香港）	zh_HK
中文（台湾）	zh_TW
克罗地亚语	hr
捷克语	cs
丹麦语	da
荷兰语	nl
英语	en
英语（英国）	en_GB
英语（美国）	zh_CN
爱沙尼亚语	et
菲律宾语	fil
芬兰语	fi
法语	fr
德语	de
希腊语	el
古吉拉特语	gu
豪萨语	ha
希伯来语	he
印地语	hi
匈牙利语	hu
印尼语	id
爱尔兰语	ga
意大利语	it
日语	ja
卡纳达语	kn
哈萨克语	kk
韩语	ko
老挝语	lo
拉脱维亚语	lv
立陶宛语	lt
马其顿语	mk
马来语	ms
马拉雅拉姆语	ml
马拉地语	mr
挪威语	nb
波斯语	fa
波兰语	pl
葡萄牙语（巴西）	pt_BR
葡萄牙语（葡萄牙）	pt_PT
旁遮普语	pa
罗马尼亚语	ro
俄语	ru
塞尔维亚语	sr
斯洛伐克语	sk
斯洛文尼亚语	sl
西班牙语	es
西班牙语（阿根廷）	es_AR
西班牙语（西班牙）	es_ES
西班牙语（墨西哥）	es_MX
斯瓦希里语	sw
瑞典语	sv
泰米尔语	ta
泰卢固语	te
泰语	th
土耳其语	tr
乌克兰语	uk
乌尔都语	ur
乌兹别克语	uz
越南语	vi
祖鲁语	zu

模板状态

FAILED — 模板创建失败
APPROVED — 模板已通过模板审核并获得批准，现在可通过模板消息发送
PENDING — 模板已通过类别验证，将进入模板审核流程。
REJECTED — 模板未通过类别验证或模板审核。
PAUSED — 模板被暂停使用。

模板组件

AUTHENTICATION 类型不适用，见下述 AUTHENTICATION 模板
支持 HEADER, BODY, BUTTONS, FOOTER 四种组件

标头（HEADER）

标头是出现在模板消息顶部的可选组件。

支持文本和媒体（图片、视频、文档）。

所有模板仅限拥有 1 个标头组件

文本标头

您可以选择将标头文本添加到消息模板。标头组件中的消息文本支持用于编程配置的参数。

位置参数示例

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our new sale starts {{1}}!",
  "example": {
    "header_text": [
      "December 1st"
    ]
  }
}

媒体标头

媒体标头可以是 IMAGE、VIDEO 或 DOCUMENT（如 PDF），必须是一个公网可访问的 URL。用于定义媒体标头的语法适用于所有媒体类型。

示例

{
    "type": "HEADER",
    "format": "IMAGE",
    "example": {
        "header_link": [
            "https://waba-crm.oss-ap-southeast-1.aliyuncs.com/storage/img/ea/43d3741b272e9a84656e4cd7169d16.jpg"
        ]
    }
}

正文（BODY）

正文组件代表消息模板的核心文本内容，它是一个仅包含文本的模板组件。所有模板都必须使用它。

正文组件中的消息文本支持用于编程配置的参数。

位置参数示例

{
  "type": "BODY",
  "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
  "example": {
    "body_text": [
      "the end of August", "25OFF", "25%"
    ]
  }
}

按钮（BUTTONS）

按钮是可选的互动式组件，在用户轻触时会执行特定操作。一个模板中可混合使用最多 10 个按钮组件，然而同一类型的单个按钮数量和按钮组合有限制。限制内容如下。

支持 COPY_CODE, PHONE_NUMBER, QUICK_REPLY, URL

语法

{
    "type": "BUTTONS",
    "buttons": [ // button 数组
        <BUTTON_1>,
        <BUTTON_2>,
        ...
    ]
}

复制验证码按钮

当应用用户轻触复制验证码按钮时，该按钮会将文本字符串（在通过模板消息发送模板时定义）复制到设备的剪贴板。一个模板仅限拥有 1 个复制验证码按钮。

语法

{
  "type": "COPY_CODE",
  "example": "<EXAMPLE>"
}

电话号码按钮

当应用用户轻触时，电话号码按钮会拨打指定的公司电话号码。一个模板仅限拥有 1 个电话号码按钮。

语法

{
  "type": "PHONE_NUMBER",
  "text": "<TEXT>",
  "phone_number": "<PHONE_NUMBER>"
}

快速回复按钮

快速回复按钮是自定义的纯文本按钮，在应用用户轻触时会立即向您发送包含指定文本字符串的消息。常见的用例之一是能让客户轻松退订任何营销消息的按钮。

一个模板仅限拥有 10 个快速回复按钮。如果结合使用快速回复按钮和其他按钮，必须将按钮分为 2 组：快速回复按钮和非快速回复按钮。如果分组不正确，API 将返回一个错误，表示组合无效。

有效分组的示例：

快速回复、快速回复
快速回复、快速回复、网址、电话
网址、电话、快速回复、快速回复

无效分组的示例：

快速回复、网址、快速回复
网址、快速回复、网址

语法

{
  "type": "QUICK_REPLY",
  "text": "<TEXT>"
}

网址按钮

当应用用户轻触时，网址按钮会在设备的默认网页浏览器中加载指定的网址。一个模板仅限拥有 2 个网址按钮。

语法

{
  "type": "URL",
  "text": "<TEXT>",
  "url": "<URL>",

  # Required if <URL> contains a variable
  "example": [
    "<EXAMPLE>"
  ]
}

示例

{
  "type": "URL",
  "text": "Shop Now",
  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
  "example": [
    "summer2023"
  ]
}

页脚（FOOTER）

页脚是可选的纯文本组件，紧跟正文组件之后出现。一个模板仅限拥有 1 个页脚组件。

语法

{
  "type": "FOOTER",
  "text": "<TEXT>"
}

AUTHENTICATION 模板

AUTHENTICATION 模板包括以下组件：

固定的预设文本：<VERIFICATION_CODE> 是您的验证码。
安全免责声明（可选）：为安全起见，请勿共享该验证码。
过期警告（可选）：这组验证码将在 <NUM_MINUTES> 分钟后过期。
复制代码按钮。

简单模板创建示例：

无安全免责声明和过期警告

{
    "name": "auth_ja",
    "language": "ja",
    "category": "AUTHENTICATION"
}

带有提示的模板创建示例：

BODY 和 FOOTER 组件必传

{
    "name": "auth_en",
    "language": "en_US",
    "category": "AUTHENTICATION",
    "components": [
        {
            "type": "BODY",
            "add_security_recommendation": true // 安全免责声明（选填），bool类型
        },
        {
            "type": "FOOTER",
            "code_expiration_minutes": 5 // 过期警告（选填），1-90 的数字
        }
    ]
}

创建模板

域名

https://api.incsapp.com

请求路由

/external/templates

请求方式

POST

请求头

Content-Type: application/json
certification-code: f484bd42-4a0c-39d....

请求参数

请求参数列表

参数名	类型	必填	描述
name	string	是	模板名称，最大长度100
language	string	是	语言code
category	string	是	模板类别：MARKETING，UTILITY
components	array	否	模板内容

请求参数示例

{
    "name": "test_api_2",
    "language": "en_US",
    "category": "MARKETING",
    "components": [
        {
            "type": "BODY",
            "text": "A API test template, first variable: {{1}}, second variable: {{2}}",
            "example": {
                "body_text": [
                    [1, 2]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "Good night"
        }
    ]
}

响应

成功响应示例

响应说明参见模板资源说明

{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {
        "template_id": "4166201267033543",
        "name": "test_api_2",
        "language": "en_US",
        "category": "MARKETING",
        "status": "REJECTED",
        "quality": "",
        "components": [
            {
                "type": "BODY",
                "text": "A API test template, first variable: {{1}}, second variable: {{2}}",
                "example": {
                    "body_text": [
                        [
                            1,
                            2
                        ]
                    ]
                }
            },
            {
                "type": "FOOTER",
                "text": "Good night"
            }
        ],
        "created_time": 1755076187,
        "updated_time": 1755076201,
        "status_updated_time": 0,
        "quality_updated_time": 0,
        "category_updated_time": 0
    },
    "error": {}
}

失败响应示例

{
    "status": "error",
    "code": 400,
    "message": "category require",
    "data": {},
    "error": {}
}

删除模板

域名

https://api.incsapp.com

请求路由

/external/templates/{template_id}

请求方式

DELETE

请求头

certification-code: f484bd42-4a0c-39d....

请求参数

响应

成功响应示例

{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {},
    "error": {}
}

失败响应示例

{
    "status": "error",
    "code": 400,
    "message": "The template is not found.",
    "data": {},
    "error": {}
}

获取模板详情

域名

https://api.incsapp.com

请求路由

/external/templates/{template_id}

请求方式

GET

请求头

certification-code: f484bd42-4a0c-39d....

请求参数

响应

成功响应示例

响应说明参见模板资源说明

{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {
        "template_id": "4166201267033543",
        "name": "test_api_2",
        "language": "en_US",
        "category": "MARKETING",
        "status": "PENDING",
        "quality": "",
        "components": [
            {
                "type": "BODY",
                "text": "A API test template without variables"
            }
        ],
        "created_time": 1755076188,
        "updated_time": 1755077570,
        "status_updated_time": 1755077464,
        "quality_updated_time": 0,
        "category_updated_time": 0
    },
    "error": {}
}

失败响应示例

{
    "status": "error",
    "code": 400,
    "message": "The template is not found.",
    "data": {},
    "error": {}
}

获取模板列表

域名

https://api.incsapp.com

请求路由

/external/templates

请求方式

GET

请求头

certification-code: f484bd42-4a0c-39d....

请求参数

请求参数列表

参数名	类型	必填	描述
last_id	string	否	上一页的最后一条数据 template_id
count	int	否	每页数据量，默认10，最大为100条
with_analytics	bool	否	设置为 true 查看模板发送数据分析

响应

成功响应示例

响应说明参见模板资源说明

{
    "status": "success",
    "code": 200,
    "message": "",
    "data": [
        {
            "template_id": "4166201267033543",
            "name": "test_api_2",
            "language": "en_US",
            "category": "MARKETING",
            "status": "PENDING",
            "quality": "",
            "components": [
                {
                    "type": "BODY",
                    "text": "A API test template without variables"
                }
            ],
            "created_time": 1755076188,
            "updated_time": 1755077570,
            "status_updated_time": 1755077464,
            "quality_updated_time": 0,
            "category_updated_time": 0,
            "analytics": {
                "sent": 898,
                "delivered": 2334,
                "read": 873,
                "failed": 188
            }
        }
    ],
    "error": {}
}

获取WABA账号信息

域名

https://api.incsapp.com

请求路由

/external/account

请求方式

GET

请求头

certification-code: f484bd42-4a0c-39d....

请求参数

响应示例

{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {
        "display_phone_number": "+62 ...", // 显示号码
        "verified_name": "Interkoneksi Indo Teknologi (IIT)", // 显示名
        "name_status": "APPROVED", // 表示显示名的批准状态
        "status": "CONNECTED", // 业务电话号码的状态必须为“CONNECTED”，该号码才能通过 API 收发消息。
        "quality_rating": "GREEN", // 号码质量评分
        "messaging_limit_tier": "TIER_1K", // 每日发消息上限
        "id": "30270...." // phone id
    },
    "error": {}
}