发送消息

域名

• https://chat-api.incsapp.com

请求路由

• /external/messages/whatsapp

请求方式

• POST

请求头

• Content-Type: application/json
• certification-code: af92196e-0d07-3c1d-a631-a71c...

请求参数

请求参数列表

参数名	类型	必填	描述
to	string	是	收信人 WhatsApp 手机号，必须是国家码+手机号的纯数字格式，如 "8526841511234"
type	string	是	消息类型，支持模板消息：template，和普通消息（需要用户回复的24小时内可以发送）：text, image, video, audio, document

• 每种消息需要的参数见请求示例

请求示例

不包含参数的模板消息请求示例

{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "test_button_reply_1"
    }
}

包含参数的模板消息请求示例

• 发送包含header媒体参数的模板消息

{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "test_header_image_5",
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "image",
                        "image": {
                            "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/images/header-98403274893.png"
                        }
                    }
                ]
            }
        ]
    }
}

• 发送包含header文本参数和body文本参数的模板消息

{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "test_header_text_2",
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "text",
                        "text": "2025-10-01"
                    }
                ]
            },
            {
                "type": "body",
                "parameters":[
                    {
                        "type": "text",
                        "text": "the end of 2025"
                    },
                    {
                        "type": "text",
                        "text": "25OFF"
                    },
                    {
                        "type": "text",
                        "text": "25%"
                    }
                ]
            }
        ]
    }
}

• 发送包含COPY_CODE 按钮的模板消息

{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "test_button_code_1",
        "components": [
            {
                "type": "button",
                "sub_type": "COPY_CODE",
                "index": "0",
                "parameters": [
                    {
                        "type": "coupon_code",
                        "coupon_code": "843924"
                    }
                ]
            }
        ]
    }
}

text 消息示例

{
    "to": "85268411234",
    "type": "text",
    "text": "Hello"
}

image 消息示例

• 支持类型：.jpeg, .png
• 最大 5 MB

{
    "to": "85268411234",
    "type": "image",
    "image": {
        "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/images/header-98403274893.png"
    }
}

video 消息示例

• 支持类型：.3gp, .mp4
• 最大 16 MB
• Only H.264 video codec and AAC audio codec supported. Single audio stream or no audio stream only.

{
    "to": "85268411234",
    "type": "video",
    "video": {
        "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/videos/687710788353f.mp4"
    }
}

audio 消息示例

• 支持类型：.aac, .amr, .mp3, .m4a, .ogg
• 最大 16 MB

{
    "to": "85268411234",
    "type": "audio",
    "audio": {
        "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/videos/68771078812f353f.mp3"
    }
}

document 消息示例

• 支持类型：.txt, .xls, .xlsx, .doc, .docx, .ppt, .pptx, .pdf
• 最大 100 MB

{
    "to": "85268411234",
    "type": "document",
    "document": {
        "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/files/template.xls"
    }
}

AUTHENTICATION 模板消息示例

• components 为固定格式，不可变更，只能替换验证码部分

{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "authentication_ca",
        "components": [
            {
                "type"code": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "832590"123456" // 验证码
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "url",
                "index": "0",
                "parameters": [
                    {
                        "type": "text",
                        "text": "832590"  // 验证码
                    }
                ]
            }
        ]
    }
}

响应

成功响应示例

{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {
        "msg_id": "wamid.HBgLODUyNjg0MTUwMjYVAgARGBIyMUQ4RjA5MTY1NUJERjE3NjYA" // WhatsApp Msg ID
    },
    "error": {}
}

失败响应示例

{
    "status": "error",
    "code": 10002,
    "message": "(#132012) Parameter format does not match format in the created template",
    "data": {},
    "error": {}
}