Quickstart

The Connexease Gateway sits between your application and the Meta WhatsApp Cloud API. You send a single HTTP request with your API key — the Gateway handles authentication with Meta, enforces rate limits, tracks billing, and returns a standard response. This guide walks you through the full flow from key creation to receiving your first delivery confirmation.

Send a Message

Text, media, and template message reference.

Set Up Webhooks

Receive incoming messages and delivery updates.

Authentication

API key management and webhook security.

Error Codes

Messaging API error codes with resolution steps.

Step 1 — Get Your API Key

Sign in to the Connexease Gateway Dashboard, open your application, and go to Developer → API Keys → + Create API Key. Give the key a name, choose an expiry, and copy the value. The key is shown in full only at the moment it is created. Keep it in an environment variable — never commit it to source control.

Never expose your API key in frontend code, mobile apps, or public repositories. All requests must come from your backend server.

Step 2 — Test in Sandbox

Before touching a real WhatsApp number, use is_fake=true to verify your integration end-to-end. The full pipeline runs — auth is checked, rate limits apply, billing balance is validated — but the Meta API call is skipped and a fake message ID is returned. Sandbox mode is a query parameter, not a separate key: use the same API key here as in production.

curl -X POST "https://api.gateway.connexease.com/v1/wa/message?is_fake=true" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "905321234567",
    "type": "text",
    "text": { "body": "Hello! This is a test." }
  }'

import requests

response = requests.post(
    "https://api.gateway.connexease.com/v1/wa/message",
    params={"is_fake": "true"},
    headers={
        "Authorization": "Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "messaging_product": "whatsapp",
        "to": "905321234567",
        "type": "text",
        "text": {"body": "Hello! This is a test."}
    }
)
print(response.json())

const response = await fetch(
  'https://api.gateway.connexease.com/v1/wa/message?is_fake=true',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: '905321234567',
      type: 'text',
      text: { body: 'Hello! This is a test.' }
    }),
  }
);
console.log(await response.json());

payload := map[string]any{
    "messaging_product": "whatsapp",
    "to":   "905321234567",
    "type": "text",
    "text": map[string]any{"body": "Hello! This is a test."},
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST",
    "https://api.gateway.connexease.com/v1/wa/message?is_fake=true",
    bytes.NewReader(body),
)
req.Header.Set("Authorization", "Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)

Response:

{
  "isSuccess": true,
  "data": {
    "messaging_product": "whatsapp",
    "messages": [
      { "id": "wamid.FAKE_1711900000000000000" }
    ]
  }
}

Step 3 — Send a Real Message

Remove is_fake and use a real recipient number. Phone numbers must include the country code without +, spaces, or dashes — e.g. 905321234567 or 14155552671.

curl -X POST https://api.gateway.connexease.com/v1/wa/message \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "905321234567",
    "type": "text",
    "text": { "body": "Hello! Your order has been confirmed." }
  }'

import requests

response = requests.post(
    "https://api.gateway.connexease.com/v1/wa/message",
    headers={
        "Authorization": "Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "messaging_product": "whatsapp",
        "to": "905321234567",
        "type": "text",
        "text": {"body": "Hello! Your order has been confirmed."}
    }
)
print(response.json())

const response = await fetch('https://api.gateway.connexease.com/v1/wa/message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messaging_product: 'whatsapp',
    to: '905321234567',
    type: 'text',
    text: { body: 'Hello! Your order has been confirmed.' }
  }),
});
console.log(await response.json());

Response:

{
  "isSuccess": true,
  "data": {
    "messaging_product": "whatsapp",
    "contacts": [
      { "input": "905321234567", "wa_id": "905321234567" }
    ],
    "messages": [
      { "id": "wamid.HBgNOTA1Mzk5ODc2NTQzFQIAERgSM0Y3RDg5..." }
    ]
  }
}

Store data.messages[0].id — the wamid — in your database. You’ll use it to match incoming delivery status webhooks in Step 5.

Step 4 — Set Up Your Webhook Endpoint

Go to Dashboard → App → Developer → Webhook, enter your HTTPS URL, set a webhook secret, and select the events you want to receive.

Event	Description
`messages`	A user sent a message to your number
`message_status`	Delivery status changed (sent, delivered, failed)
`read`	A user read your message
`message_template_status`	Template approved or rejected
`account`	Account or phone number update

Your endpoint must return HTTP 200 within 5 seconds. Process events asynchronously.

app.post('/webhook', (req, res) => {
  const auth = req.headers['authorization'];
  if (auth !== `Bearer ${process.env.WEBHOOK_SECRET}`) {
    return res.status(401).send('Unauthorized');
  }
  res.sendStatus(200);
  setImmediate(() => processEvent(req.body));
});

function processEvent(body) {
  const changes = body?.entry?.[0]?.changes ?? [];
  for (const change of changes) {
    const value = change.value;
    for (const msg of value?.messages ?? []) {
      console.log(`[${msg.type}] from ${msg.from}`);
    }
    for (const status of value?.statuses ?? []) {
      console.log(`${status.id} → ${status.status}`);
    }
  }
}

@app.route('/webhook', methods=['POST'])
def webhook():
    if request.headers.get('Authorization') != f"Bearer {os.environ['WEBHOOK_SECRET']}":
        return '', 401
    payload = request.get_json()
    threading.Thread(target=process_event, args=(payload,), daemon=True).start()
    return '', 200

def process_event(body):
    changes = body.get('entry', [{}])[0].get('changes', [])
    for change in changes:
        value = change.get('value', {})
        for msg in value.get('messages', []):
            print(f"[{msg['type']}] from {msg['from']}")
        for status in value.get('statuses', []):
            print(f"{status['id']} → {status['status']}")

Step 5 — Track Delivery Status

Once your webhook is live, the Gateway will POST a message_status event every time the delivery state of a message changes. Match it to your original send using the wamid.

{
  "entry": [{
    "changes": [{
      "field": "messages",
      "value": {
        "statuses": [{
          "id": "wamid.HBgNOTA1Mzk5ODc2NTQzFQ...",
          "status": "delivered",
          "timestamp": "1711900450",
          "recipient_id": "905321234567"
        }]
      }
    }]
  }]
}

isSuccess: true on the send response means the message was accepted, not delivered. delivered only arrives via webhook.

Next Steps

Create Templates

Create and submit templates for Meta approval before you send them.

All Webhook Events

Full payload examples for every event type.

Error Handling

Messaging API error codes with recommended actions.

Billing

How Connexease and Meta fees work.

Getting Started

Essentials

Send a Message

Set Up Webhooks

Authentication

Error Codes

Step 1 — Get Your API Key

Step 2 — Test in Sandbox

Step 3 — Send a Real Message

Step 4 — Set Up Your Webhook Endpoint

Step 5 — Track Delivery Status

Next Steps

Create Templates

All Webhook Events

Error Handling

Billing

Send a Message

Set Up Webhooks

Authentication

Error Codes

​Step 1 — Get Your API Key

​Step 2 — Test in Sandbox

​Step 3 — Send a Real Message

​Step 4 — Set Up Your Webhook Endpoint

​Step 5 — Track Delivery Status

​Next Steps

Create Templates

All Webhook Events

Error Handling

Billing

Step 1 — Get Your API Key

Step 2 — Test in Sandbox

Step 3 — Send a Real Message

Step 4 — Set Up Your Webhook Endpoint

Step 5 — Track Delivery Status

Next Steps