使用WhatsApp Cloud API发送轮播模板报错：需启用交互式模板

错误信息 #

{
    "error": {
        "message": "(#100) Invalid parameter",
        "type": "OAuthException",
        "code": 100,
        "error_data": {
            "messaging_product": "whatsapp",
            "details": "Carousel template messages require interactive template to be enabled."
        },
        "fbtrace_id": "AoSOKx70Cbw_U6nZ-AWiizA"
    }
}

背景信息 #

• 使用已通过WhatsApp审核的轮播模板，模板在WhatsApp Manager中可见且激活
• API请求已设置messaging_product: "whatsapp"
• 已验证模板审核状态、格式，确认电话ID和令牌正确

问题核心解析 #

这里的"interactive template to be enabled"并非指模板本身需要单独开启某个开关，而是涉及账户权限配置和API请求格式规范两个核心点。

具体解决步骤 #

1. 检查企业账户的交互式消息权限 #

登录WhatsApp商业管理平台，进入账户设置：

• 确认你的WhatsApp Business Account（WABA）已开通交互式消息功能：部分新创建的账户可能默认未开启该权限，需在WABA设置的「功能」板块中启用
• 确认发送号码已关联到开通了交互式功能的WABA下

2. 修正API请求格式 #

你当前的请求将消息类型设为"type": "template"，但轮播模板属于交互式模板，需要调整请求结构：

• 将顶级type字段改为"interactive"，而非"template"
• 调整interactive字段结构，嵌套你的模板信息（交互式模板的参数传递逻辑与普通文本模板不同）

适配你的轮播模板的正确请求结构示例：

{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "<to number>",
    "type": "interactive",
    "interactive": {
        "type": "template",
        "template": {
            "name": "carousel_template_media_cards_v1_0",
            "language": {
                "code": "en_US"
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "text": "Pablo"},
                        {"type": "text", "text": "20%"},
                        {"type": "text", "text": "20OFF"}
                    ]
                },
                {
                    "type": "carousel",
                    "cards": [
                        {
                            "card_index": 0,
                            "components": [
                                {"type": "header", "parameters": [{"type": "image", "image": {"id": "1442330163593795"}}]},
                                {"type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [{"type": "payload", "payload": "more-aloes"}]},
                                {"type": "button", "sub_type": "url", "index": "1", "parameters": [{"type": "text", "text": "blue-elf"}]}
                            ]
                        },
                        {
                            "card_index": 1,
                            "components": [
                                {"type": "header", "parameters": [{"type": "image", "image": {"id": "1442330163593795"}}]},
                                {"type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [{"type": "payload", "payload": "more-crassulas"}]},
                                {"type": "button", "sub_type": "url", "index": "1", "parameters": [{"type": "text", "text": "buddhas-temple"}]}
                            ]
                        },
                        {
                            "card_index": 2,
                            "components": [
                                {"type": "header", "parameters": [{"type": "image", "image": {"id": "1442330163593795"}}]},
                                {"type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [{"type": "payload", "payload": "more-echeverias"}]},
                                {"type": "button", "sub_type": "url", "index": "1", "parameters": [{"type": "text", "text": "black-prince"}]}
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

3. 确认模板的类型标记 #

在WhatsApp Manager中查看模板详情：

• 确保模板被标记为交互式模板（而非普通文本模板）：如果模板创建时选错类型，即使审核通过也无法正常发送，需重新创建正确类型的模板

额外排查点 #

• 确认发送号码的权限：确保该号码有权限发送交互式消息（部分测试号码可能限制功能）
• 检查模板参数是否完全匹配：轮播模板的每个卡片参数（如图像ID、按钮payload）必须与模板定义完全一致

内容的提问来源于stack exchange，提问作者Namshad Cookee