API for sending WhatsApp messages

📬 The Send Api, version 2.0

 

Want to reach your customers on WhatsApp? Our Sending WhatsApp API lets you send transactional WhatsApp messages (order confirmations, delivery updates, appointment reminders, one-time codes) right from your app or backend.

Messages are sent from your own WhatsApp Business Account, using templates approved by Meta.

 

📋 Before you start

  • Connect your WhatsApp Business Account to the project you send from, in WhatsApp → Settings. You will need your official WhatsApp Business Account details from Meta.
  • Create a WhatsApp template in WhatsApp → Templates and wait until Meta approves it. Only approved templates can be sent.
  • Copy the template's API key: open the template in WhatsApp → Templates; the API key is shown next to the preview, with Reveal and Copy buttons.

 

🔐 Step 1: Get Your Api Key

Before anything else, you’ll need an Api key to authenticate your requests.
Already have one? Great! Copy it to your clipboard.
Need one? You can generate it by heading over to Settings → Api Keys → Create New Api Key.

 

📨 Step 2: Add Your Api Key to the Request Header

When you’re ready to make your request, add your Api key into the header like this:

x-api-key: xxxx-xxxx-xxxx-xxxx
📋 Copy

 

🚀 Step 3: Send a POST Request to this endpoint

You’ll be sending a POST request to:

https://inbound.messengeros.com/2.0/send
📋 Copy

This is where the magic happens ✨

 

🧱 Step 4: Build your Payload


4.1. Send WhatsApp messages using templates approved by Meta

Here’s the format your JSON payload should follow:
Mandatory fields: template, phone_number.
{
    "project": "xxxxxx-xxxxxx-xxxx-xxxxx-xxxxxxxxx", // optional (if missing, the default Project will be used), can be found in Settings / Projects / Edit / Show Api Key
    "notification": {
        "whatsapp": [
            {
                "template": "xxxxxx-xxxxxx-xxxx-xxxxx-xxxxxxxxx", // the API key of an approved WhatsApp template, can be found in WhatsApp / Templates / Edit
                "recipients": [
                    {
                        "phone_number": "+407xxxxxxxx", // international format, with the country code
                        "name": "Recipient's full name (First name + Last name) or Company name", // optional, if you want to save the recipient's full name or company name
                        "first_name": "Recipient's first name", // optional, if you want to save the recipient's first and last name separately
                        "last_name": "Recipient's last name" // optional, if you want to save the recipient's first and last name separately
                    }
                ],
                "params": {
                    "first_name": "Alex",
                    "order_number": "#10234"
                } // optional, the values of the template variables, by name (see 4.2)
            }
        ]
    }
}
📋 Copy

4.2. Template variables

If your approved template body is:

Hi {{first_name}}, your order {{order_number}} has been shipped.

then "params": {"first_name": "Alex", "order_number": "#10234"} sends:

Hi Alex, your order #10234 has been shipped.
  • Give the values by variable name, as above. A variable used twice in the template takes a single value.
  • You can also give them as a list, in the order the variables first appear in the template: "params": ["Alex", "#10234"]. For templates written with numbered variables ({{1}}, {{2}}) you can use the numbers as names: {"1": "Alex", "2": "#10234"}.
  • Variables you leave out are filled from the recipient: first_name, last_name, name, email and phone_number from the contact, and any other name from the contact's custom fields (Audience / Contacts / View). For example, {{first_name}} is filled from the recipient's first_name without sending it in params.
  • A variable can have a fallback in the template, used when neither the request nor the contact gives a value: {{first_name|'client'}} sends client to a contact without a first name. This is the same syntax as in email and SMS templates.
  • Every variable must have a value. If one is missing, that recipient is not sent and the reason (for example Missing values for template variables: order_number) is shown in WhatsApp → Sent.
  • Each value is plain text, up to 1024 characters.
  • The same values are used for every recipient in the block. To personalise messages per recipient, send one block per recipient in the whatsapp list.
  • If the template has a text header with a variable (for example Your appointment at {{clinic}}), give its value by name, like the body's: "params": {"clinic": "Dental Plus", ...}. It is also filled from the contact and from a fallback in the template. A plain list of values only fills the body.
  • If the template has an image, video or document header, the file saved on the template is sent automatically.

4.3. Good to know
  • WhatsApp is sent from the WhatsApp Business Account connected to the project, so no delivery_provider is needed.
  • Contacts who opted out of WhatsApp are skipped.
  • Your account has a monthly WhatsApp sending limit. Messages over the limit are not sent; contact support to raise it.
  • You can send WhatsApp in the same request as email or SMS, by adding the whatsapp list next to the email or sms lists in notification.

 

✅ Step 5: Get a Confirmation

If everything looks good and your JSON is valid, the Api will respond with:

{"status": "received"}

This means we’ve accepted the request and your WhatsApp messages are being processed in the background.

 

👀 Step 6: Double check in your Sent WhatsApp messages

Once your request goes through, head over to WhatsApp → Sent to confirm that your message has been sent to the specified recipient. Replies from your contacts show up in WhatsApp → Inbox.
That’s it! 🎉

Need help or want to test it out? Let us know, we’re always here to support.

© MessengerOS