# 模板资源说明

### 资源示例
```json
{
    "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 个标头组件

##### 文本标头

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

###### 位置参数示例

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

##### 媒体标头

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

###### 示例

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

#### 正文（BODY）

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

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

###### 位置参数示例

```json
{
  "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
###### 语法

```json
{
    "type": "BUTTONS",
    "buttons": [ // button 数组
        <BUTTON_1>,
        <BUTTON_2>,
        ...
    ]
}
```
  
##### 复制验证码按钮

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

###### 语法

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

##### 电话号码按钮

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

###### 语法

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

##### 快速回复按钮

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

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

有效分组的示例：

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

无效分组的示例：

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

###### 语法

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

##### 网址按钮

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

###### 语法

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

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

###### 示例

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

#### 页脚（FOOTER）

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

###### 语法

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

### AUTHENTICATION 模板

AUTHENTICATION 模板包括以下组件：

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

##### 简单模板创建示例：
* 无**安全免责声明**和**过期警告**
```json
{
    "name": "auth_ja",
    "language": "ja",
    "category": "AUTHENTICATION"
}
```

##### 带有提示的模板创建示例：
* BODY 和 FOOTER 组件必传
```json
{
    "name": "auth_en",
    "language": "en_US",
    "category": "AUTHENTICATION",
    "components": [
        {
            "type": "BODY",
            "add_security_recommendation": true // 安全免责声明（选填），bool类型
        },
        {
            "type": "FOOTER",
            "code_expiration_minutes": 5 // 过期警告（选填），1-90 的数字
        }
    ]
}
```