API Reference

The Wapicore Messaging API lets you send WhatsApp messages using your connected WABA. All requests are authenticated with an API key created in your dashboard.

Value
Base URLhttps://msg.wapicore.com.br/v1
ProtocolHTTPS only
FormatJSON (application/json)

Include your API key in every request:

http
Authorization: Bearer sk_live_xxxxxxxxxxxx
Your API key is created and managed in the dashboard under API Keys. Each key has scopes — use the narrowest scope needed for each service.

Messages

Send a WhatsApp message to any recipient. The phone_number_id is found in your dashboard under Numbers.

POST/v1/messages
Required scope: messages:send
FieldTypeRequiredDescription
phone_number_idstring✓Your WhatsApp phone number ID
tostring✓Recipient in E.164 format — e.g. +5511999999999
typestring✓text | template | image | audio | video | document | interactive
textobject—Required when type = text
templateobject—Required when type = template
image / audio / …object—Required for the matching media type
interactiveobject—Required when type = interactive

Text

bash
curl -X POST https://msg.wapicore.com.br/v1/messages \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "+5511999999999",
    "type": "text",
    "text": { "body": "Hello from Wapicore!" }
  }'
json
// 200 OK
{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "+5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "wamid.xxx" }]
}

Template

Required to initiate a conversation outside the 24-hour customer service window. Templates must be pre-approved by Meta before use.

bash
curl -X POST https://msg.wapicore.com.br/v1/messages \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "+5511999999999",
    "type": "template",
    "template": {
      "name": "order_confirmed",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Pedido #4821" }
          ]
        }
      ]
    }
  }'

Media

Supported types: image, audio, video, document, sticker. Pass either a public link or a Meta media id.

bash
curl -X POST https://msg.wapicore.com.br/v1/messages \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "+5511999999999",
    "type": "image",
    "image": {
      "link": "https://example.com/image.jpg",
      "caption": "Your order is packed!"
    }
  }'

Interactive

Supports button (up to 3 reply buttons) and list (up to 10 items).

bash
curl -X POST https://msg.wapicore.com.br/v1/messages \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "+5511999999999",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": { "text": "Choose an option:" },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "yes", "title": "Yes" } },
          { "type": "reply", "reply": { "id": "no",  "title": "No"  } }
        ]
      }
    }
  }'

Webhooks

Receive real-time events from WhatsApp — inbound messages, delivery status updates, and template status changes. Webhook endpoints are managed in your dashboard under Webhooks.

Setup

In the dashboard, create a webhook endpoint by providing:

FieldDescription
URLYour HTTPS endpoint — must return 200 within 5 seconds
Eventsmessage | message_status | template_status
SecretMinimum 16 characters — used to verify HMAC signatures
Wapicore retries failed deliveries up to 3 times with exponential backoff (30 s → 5 min → 30 min). Respond with 200 immediately and process asynchronously.

Event payloads

All events share the same envelope:

json
{
  "event": "message",
  "timestamp": "2026-07-09T14:22:00.000Z",
  "phoneNumberId": "1234567890",
  "data": { /* event-specific payload from Meta */ }
}
EventDescriptiondata content
messageInbound message receivedMeta message object
message_statusDelivery / read status updateMeta status object
template_statusTemplate approved / rejected / pausedMeta template status object

HMAC verification

Every delivery includes a X-Wapicore-Signature-256 header. Always verify it before processing the event.

javascript
import crypto from "crypto";

function verifyWebhook(rawBody, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)          // raw bytes — do NOT parse JSON first
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-wapicore-signature-256"];
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  const event = JSON.parse(req.body.toString());
  // ... process event
  res.status(200).send("OK");
});

Templates

Message templates must be approved by Meta before use. This API proxies to the Meta Graph API using your WABA credentials.

List templates

GET/v1/whatsapp/numbers/:numberId/templates
Required scope: templates:read
bash
curl https://msg.wapicore.com.br/v1/whatsapp/numbers/NUMBER_ID/templates \
  -H "Authorization: Bearer sk_live_xxxx"
json
{
  "templates": [
    {
      "id": "123456789",
      "name": "order_confirmed",
      "status": "APPROVED",
      "category": "UTILITY",
      "language": "pt_BR"
    }
  ]
}

Create template

POST/v1/whatsapp/numbers/:numberId/templates
Required scope: templates:write

Submits a template for Meta review. Simple utility templates are usually approved within minutes; marketing templates may take longer.

bash
curl -X POST https://msg.wapicore.com.br/v1/whatsapp/numbers/NUMBER_ID/templates \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmed",
    "language": "pt_BR",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Olá! Seu pedido {{1}} foi confirmado e será entregue em até {{2}} dias úteis."
      }
    ]
  }'
CategoryUse case
UTILITYTransactional — order confirmations, shipping updates, reminders
MARKETINGPromotions, offers, newsletters
AUTHENTICATIONOTPs and login verification codes

Delete template

DELETE/v1/whatsapp/numbers/:numberId/templates/:templateName
Required scope: templates:write
bash
curl -X DELETE https://msg.wapicore.com.br/v1/whatsapp/numbers/NUMBER_ID/templates/order_confirmed \
  -H "Authorization: Bearer sk_live_xxxx"

Errors

All errors return a JSON object with a human-readable message:

json
{ "error": "Human-readable error message" }
StatusMeaning
400Bad request — validation error, see message for details
401Unauthorized — missing or invalid API key
403Forbidden — valid key but missing required scope
404Resource not found
429Too Many Requests — rate limit exceeded, see Retry-After header
500Internal server error

Rate limits

Limits are applied per API key. When exceeded the API returns 429 with a Retry-After header indicating when to retry.

EndpointLimitWindow
POST /v1/messages100 requests1 minute
All other endpoints120 requests1 minute
Need higher throughput? Contact us — limits can be raised per account once your WABA tier supports it.