WhatsApp Business API requires that the user sends the first message before the business can reply

Question

I checked the WhatsApp Business API documentation and couldn’t find a direct way to start a conversation without the customer initiating it.

Currently, I can send messages only after receiving a message from a customer:

const axios = require('axios');

const sendMessage = async () => {
    const response = await axios.post(
        "https://graph.facebook.com/v17.0/YOUR_PHONE_NUMBER_ID/messages",
        {
            messaging_product: "whatsapp",
            to: "CUSTOMER_PHONE_NUMBER",
            type: "text",
            text: { body: "Hello, how can we assist you?" }
        },
        {
            headers: {
                "Authorization": `Bearer YOUR_ACCESS_TOKEN`,
                "Content-Type": "application/json"
            }
        }
    );

    console.log(response.data);
};

sendMessage();

This works only if the customer has sent a message first. How can I modify this to initiate a new conversation?

Answer 1

To start a conversation on WhatsApp using the Business API, you must use a pre-approved message template. WhatsApp enforces this to prevent unsolicited messages. Free-form messages only work if the user has messaged first within the last 24 hours.

If you want to initiate contact, update your request to send a template message instead of a free-form message. Here’s a correct implementation:

const axios = require('axios');

const sendTemplateMessage = async () => {
    try {
        const response = await axios.post(
            "https://graph.facebook.com/v17.0/YOUR_PHONE_NUMBER_ID/messages",
            {
                messaging_product: "whatsapp",
                to: "CUSTOMER_PHONE_NUMBER",
                type: "template",
                template: {
                    name: "hello_user", // Must be an approved template
                    language: { code: "en_US" },
                    components: [
                        {
                            type: "body",
                            parameters: [
                                { type: "text", text: "John" } // Ensure this matches placeholders
                            ]
                        }
                    ]
                }
            },
            {
                headers: {
                    "Authorization": `Bearer YOUR_ACCESS_TOKEN`,
                    "Content-Type": "application/json"
                }
            }
        );

        console.log("Message sent successfully:", response.data);
    } catch (error) {
        if (error.response) {
            console.error("API Error:", error.response.data);
        } else {
            console.error("Request Error:", error.message);
        }
    }
};

sendTemplateMessage();

Common Errors and Fixes

1. (100) Invalid parameter: Incorrect template name --> Fix with use an approved template from WhatsApp Manager.
2. (131051) Message failed to send: Phone number issue --> Fix: ensure the number has WhatsApp active and is formatted correctly.
3. (200) Permission error: Missing permissions --> Fix: ensure the access token has message sending permissions.

If you want a simpler way to manage WhatsApp API without handling approvals and errors, consider Meta’s own WhatsApp Business Manager, Mekari Qontak, Twilio, or 360dialog. They streamline integration and compliance, reducing manual setup and troubleshooting.