Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gateway.connexease.com/llms.txt

Use this file to discover all available pages before exploring further.

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

All error codes with resolution steps.

​
Step 1 — Get Your API Key

Sign in to the Connexease Gateway Dashboard → App → Developers → Create API Key. You’ll receive a key prefixed with pk_ for production or sk_ for staging. 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. 
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." }
  }'
Response: 
{
  "isSuccess": true,
  "data": {
    "messaging_product": "whatsapp",
    "messages": [
      { "id": "wamid.FAKE_1711900000000000000" }
    ]
  }
}

​
Step 3 — Send a Real Message

Switch to your production key (pk_), 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 pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "905321234567",
    "type": "text",
    "text": { "body": "Hello! Your order has been confirmed." }
  }'
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 → Settings → Webhooks, enter your HTTPS URL, set a webhook secret, and select the events you want to receive.
EventDescription
messagesA user sent a message to your number
message_statusDelivery status changed (sent, delivered, failed)
readA user read your message
message_template_statusTemplate approved or rejected
accountAccount 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}`);
    }
  }
}

​
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

Template Messages

Use approved templates to start new conversations.

All Webhook Events

Full payload examples for every event type.

Error Handling

Every error code with recommended actions.

Billing

How Connexease and Meta fees work.