使用WhatsApp Cloud API批量发送个性化图片消息的故障排查

我尝试通过Meta（Facebook）WhatsApp Cloud API向多个联系人发送带个性化姓名的图片消息，读取存储有手机号和姓名的Excel文件来实现消息个性化。以下是我使用的简化Python代码：

import pandas as pd
import requests
import time

ACCESS_TOKEN = ""  
EXCEL_FILE = "contacts.xlsx"          
PHONE_COLUMN = "phone"                
NAME_COLUMN = "name"                   
IMAGE_LINK = "https://raw.githubusercontent.com/ghazdevlper-ux/Images/main/Independece.JPG"  
DELAY_SECONDS = 5                     

df = pd.read_excel(EXCEL_FILE)
contacts = df[[PHONE_COLUMN, NAME_COLUMN]].dropna()
url = "https://graph.facebook.com/v22.0/<your_whatsapp_phone_number_id>/messages"
headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}

for _, row in contacts.iterrows():
    phone = str(row[PHONE_COLUMN])
    name = str(row[NAME_COLUMN])

    payload = {
        "messaging_product": "whatsapp",
        "to": phone,
        "type": "template",
        "template": {
            "name": "image_template",
            "language": {"code": "en"},
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "image",
                            "image": {"link": IMAGE_LINK}
                        }
                    ]
                },
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "text": name}
                    ]
                }
            ]
        }
    }

    try:
        response = requests.post(url, headers=headers, json=payload)
        print(f"Sent to {phone}: {response.status_code} - {response.text}")
    except Exception as e:
        print(f"Error sending to {phone}: {e}")

    time.sleep(DELAY_SECONDS)

问题现象 #

我预期每个联系人能收到包含图片及个性化姓名的消息，但API要么报错、未发送图片，要么返回发送成功但收件人未收到消息。

已做排查 #

• 反复核对ACCESS_TOKEN和WhatsApp手机号ID
• 尝试使用GitHub上的公开可访问图片链接
• 验证消息模板包含image类型的头部

问题解决建议 #

1. 消息模板的合规性与匹配度

• 确认在Meta Business Manager中创建的image_template已通过审核，且结构完全匹配API请求：头部必须设置为图片类型，body部分需包含对应文本占位符（如{{1}}），占位符数量和类型要与payload中的parameters对应。
• 检查模板语言代码是否与请求中的"en"一致，若目标联系人使用其他语言，需同步调整language.code的值。

2. 手机号格式规范

• Excel中的手机号必须是E.164标准格式（带国家代码前缀，例如+8613xxxxxxxxx），不能仅填写本地号码。API会拒绝格式不符合要求的号码。

3. 图片链接的有效性

• 图片链接必须是HTTPS协议，服务器需支持HEAD请求，图片大小不超过5MB，格式为JPG/PNG。可通过curl -I <图片链接>验证链接是否正常返回200状态码。
• 避免使用有防盗链限制或临时存储的链接，确保链接长期可访问。

4. API权限与限流问题

• 检查ACCESS_TOKEN是否拥有whatsapp_business_messaging权限，可在Meta Graph API Explorer中单独测试单个请求，确认权限正常。
• 若返回发送成功但收件人未收到，可能触发了Rate Limit，建议将DELAY_SECONDS调整为10秒以上，降低发送频率。

5. 请求结构细节校验

• 确保URL中的<your_whatsapp_phone_number_id>已替换为实际的号码ID，不能保留占位符。
• 确认payload中header的image参数使用link字段（对应外部图片），若使用Meta媒体库中的图片，需替换为id字段并传入媒体ID。

6. 单号码测试验证

• 先使用单个测试号码（如自己的WhatsApp账号）测试请求，确认能正常接收消息后，再进行批量发送，排除批量操作带来的干扰。

内容的提问来源于stack exchange，提问作者WAY TO LEARN GOOD