Send Your First WhatsApp Message via API

Before you start

You need two things, both from your Ghala dashboard:

1. A connected WhatsApp number. The connection wizard (Dashboard → Add WhatsApp Account) walks you through Meta authorization and verification, and hands you your own credentials.
2. An API key. Create one under Developer → Credentials. Keys look like ghala_...; keep them in an environment variable, never in code or git.

All requests go to:

https://api.ghala.io/api/v1

with your key in the Authorization header.

Send a text message

Phone numbers use full international format without + (e.g. 255712345678).

cURL

curl -X POST https://api.ghala.io/api/v1/messages \
  -H "Authorization: Bearer $GHALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "255712345678",
    "type": "text",
    "text": { "body": "Hello from Ghala!" }
  }'

Node.js

const res = await fetch("https://api.ghala.io/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GHALA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "255712345678",
    type: "text",
    text: { body: "Hello from Ghala!" },
  }),
})
const data = await res.json()
console.log(data)

Python

import os, requests

res = requests.post(
    "https://api.ghala.io/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['GHALA_API_KEY']}"},
    json={
        "to": "255712345678",
        "type": "text",
        "text": {"body": "Hello from Ghala!"},
    },
)
print(res.json())

A successful send returns the message ID and status:

{
  "success": true,
  "data": {
    "message_id": "wamid.HBgM...",
    "status": "sent"
  }
}

Send it to your own WhatsApp number first; the message should land on your phone within seconds.

The 24-hour rule

WhatsApp distinguishes two kinds of outbound message:

• Session messages (free-form text, like the one above) can only be sent within 24 hours of the customer's last message to you. Outside that window they will fail.
• Template messages work any time; they use a pre-approved template and are how you start conversations, send reminders, and run campaigns.

If your test message fails, this is the most common reason: message your business number from your phone first to open the session window, then retry.

Send a template message

Create and submit templates under Templates in the dashboard (Meta approval usually takes minutes to a few hours). Then:

curl -X POST https://api.ghala.io/api/v1/messages \
  -H "Authorization: Bearer $GHALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "255712345678",
    "type": "template",
    "template": {
      "name": "order_update",
      "language": { "code": "en" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "John" },
            { "type": "text", "text": "1042" }
          ]
        }
      ]
    }
  }'

Parameters fill the template's {{1}}, {{2}} placeholders in order.

What happens after "sent"

sent only means WhatsApp accepted the message. Delivery and read receipts arrive asynchronously as webhook events, and so do your customers' replies. That's the second half of any integration:

→ Set up webhooks to receive replies and status updates in real time.

For every endpoint, parameter, and error code, see the API Reference.