API Documentation

Wabiss API

Use this API to send messages and access chats, contacts, groups, and instance status.

1. Create and connect one instance from dashboard.
2. Generate an API key from API Keys page.
3. Pass `Authorization: Bearer <api_key>` for all `/api/v1/*` requests.

Authentication

All `/api/v1/*` endpoints require Bearer token auth.

Authorization: Bearer wa_your_api_key_here

Messaging APIs

Credits are deducted only for successful sends.

{
  "to": "919876543210",
  "message": "Hello from Wabiss"
}

{
  "to": "919876543210",
  "url": "https://example.com/photo.jpg",
  "caption": "Invoice image"
}

{
  "to": "919876543210",
  "url": "https://example.com/report.pdf",
  "caption": "Monthly report"
}

{
  "to": "919876543210",
  "url": "https://example.com/audio.mp3"
}

{
  "to": "919876543210",
  "latitude": 12.9716,
  "longitude": 77.5946,
  "name": "Bengaluru"
}

{
  "to": "919876543210",
  "message": "Choose one",
  "buttons": [
    { "body": "Yes" },
    { "body": "No" }
  ],
  "title": "Confirmation",
  "footer": "Reply now"
}

{
  "to": "919876543210",
  "message": "Pick a plan",
  "buttonText": "View plans",
  "sections": [
    {
      "title": "Plans",
      "rows": [
        { "id": "starter", "title": "Starter", "description": "500 credits (1 credit per message)" },
        { "id": "pro", "title": "Pro", "description": "2000 credits (1 credit per message)" }
      ]
    }
  ]
}

{
  "numbers": ["919876543210", "919999999999"],
  "message": "Bulk campaign message"
}

{
  "templateName": "password_reset_v1",
  "languageCode": "en",
  "recipients": [
    {
      "to": "919876543210",
      "templateParams": ["Jenesh"],
      "templateButtonParams": ["?token=abc123"]
    },
    {
      "to": "919999999999",
      "templateParams": ["Rahul"],
      "templateButtonParams": ["?token=xyz789"]
    }
  ]
}

Success Response

Use data for new integrations. Top-level messageId and credits fields are kept for backward compatibility.

{
  "success": true,
  "requestId": "req_7f83e8a2c5f0d9ab",
  "timestamp": "2026-03-20T11:52:10.225Z",
  "message": "Message sent successfully",
  "data": {
    "messageId": "3EB09ABD621F9593655F51",
    "waMessageId": "true_919876543210@c.us_3EB09ABD621F9593655F51",
    "to": "919876543210",
    "type": "text",
    "status": "sent",
    "sentAt": "2026-03-20T11:52:10.224Z",
    "credits": {
      "used": 1,
      "remaining": 636
    }
  },
  "meta": {
    "version": "v1",
    "endpoint": "/api/v1/send/text",
    "instanceId": "inst_abc123",
    "apiKey": "wa_abcd...wxyz"
  },
  "messageId": "3EB09ABD621F9593655F51",
  "creditsUsed": 1,
  "creditsRemaining": 636
}

Meta Cloud API Instances

The same send endpoints work for both WhatsApp Web QR instances and Meta Cloud API instances. Wabiss routes automatically based on the instance attached to your API key.

Send Template Message

Meta requires approved templates for the first message to a contact outside the 24-hour customer service window.

1. Create or fetch approved template in your selected Meta instance.
2. Use `POST /api/v1/send/template` with `templateName`, `languageCode`, and variables.
3. If template has URL buttons with `{{1}}`, pass values in `templateButtonParams`.

POST /api/v1/send/template

{
  "to": "919876543210",
  "templateName": "password_reset_v1",
  "languageCode": "en",
  "templateParams": ["Jenesh"],
  "templateButtonParams": ["?token=abc123"]
}

Use array values only, in exact template variable order.

{
  "to": "919876543210",
  "templateName": "string (required)",
  "languageCode": "en | en_US | ...",
  "templateParams": ["bodyVar1", "bodyVar2"],
  "templateButtonParams": ["urlVar1", "urlVar2"],
  "components": [
    {
      "type": "header|body|button",
      "parameters": []
    }
  ]
}

If you send `components`, Wabiss forwards them as-is to Meta. If not, Wabiss auto-builds body/button components from stored template + params.

Bulk Personalized Template Send

Use one template and send to many users with per-recipient variables via /send/template-bulk.

{
  "templateName": "password_reset_v1",
  "languageCode": "en",
  "recipients": [
    {
      "to": "919876543210",
      "templateParams": ["Jenesh"],
      "templateButtonParams": ["?token=abc123"]
    },
    {
      "to": "919999999999",
      "templateParams": ["Rahul"],
      "templateButtonParams": ["?token=xyz789"]
    }
  ]
}

Send Media with Meta

For Meta instances, use a public HTTPS media URL. Supported media types are image, document, audio, and video.

{
  "to": "919876543210",
  "mediaUrl": "https://example.com/invoice.pdf",
  "mediaType": "document",
  "message": "Invoice attached"
}

Get Approved Templates

GET /api/v1/instances/:instanceId/templates
Authorization: Bearer YOUR_API_KEY

Create Template

Submitted templates must be approved by Meta before they can be used for delivery.

POST /api/v1/instances/:instanceId/templates

{
  "name": "order_update",
  "category": "UTILITY",
  "language": "en_US",
  "bodyText": "Hi {{1}}, your order {{2}} is confirmed.",
  "bodySample": "Jenesh, ORD-1024",
  "footerText": "Wabiss Notifications",
  "quickReplies": ["Track order", "Contact support"]
}

Message Logs & Report

Fetch outgoing and incoming message logs history with robust filtering and pagination.

POST /api/v1/report/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "instanceId": "6a06dcd8f00a3613f23d805a",
  "status": "sent",
  "limit": 5
}

Request Body Parameters

Response Example

{
  "success": true,
  "data": [
    {
      "id": "6a06e901f00a3613f23d80b5",
      "instanceId": "6a06dcd8f00a3613f23d805a",
      "messageId": "msg_1710500122000",
      "to": "919876543210",
      "type": "template",
      "status": "sent",
      "creditsUsed": 419,
      "direction": "outgoing",
      "error": null,
      "sentAt": "2026-03-20T11:52:10.000Z",
      "deliveredAt": "2026-03-20T11:52:12.000Z",
      "readAt": "2026-03-20T11:53:05.000Z",
      "createdAt": "2026-03-20T11:52:10.225Z",
      "content": {
        "to": "919876543210",
        "templateName": "password_reset_v1",
        "languageCode": "en",
        "templateParams": ["Jenesh"]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1,
    "count": 1
  }
}

Important Meta Rules

1. Use the same Wabiss API key in Authorization header. Do not put Meta access token in Postman API requests.
2. Free-form text is allowed inside the 24-hour customer service window.
3. Cold outreach must use an approved Meta template.
4. Incoming messages and delivery status are received on the Meta webhook URL shown in Meta Settings.

Meta Template Guide

Use this section when sending template APIs from Postman or your backend service.

Field Mapping (`/send/template`)

Accepted Format

{
  "templateParams": ["A", "B"],
  "templateButtonParams": ["otp123"]
}

URL Button Example

For template button URL like `https://site.com/reset/{{1}}`, pass only replacement value in `templateButtonParams`.

{
  "to": "919876543210",
  "templateName": "password_reset_v1",
  "languageCode": "en",
  "templateParams": ["Jenesh"],
  "templateButtonParams": ["abc123token"]
}

Bulk Template Example

{
  "templateName": "tender_service_update_v2",
  "languageCode": "en",
  "recipients": [
    {
      "to": "919876543210",
      "templateParams": ["AG TENDER", "Jenesh", "A12BC", "https://example.com/t/A12BC", "Please review soon."],
      "templateButtonParams": ["reminder_1.pdf", "details_1.pdf"]
    },
    {
      "to": "919999999999",
      "templateParams": ["AG TENDER", "Rahul", "A12BD", "https://example.com/t/A12BD", "Only 2 hours left."],
      "templateButtonParams": ["reminder_2.pdf", "details_2.pdf"]
    }
  ]
}

Meta Developer Webhook Setup

To receive incoming messages and delivery status updates for your Meta instances, you must configure a webhook inside your Facebook Developer console.

Webhook Events

Wabiss can push WhatsApp events to your endpoint using the instance webhook URL configured in Instance settings.

Current Event List

`incoming_message` Payload

{
  "event": "incoming_message",
  "instanceId": "inst_abc123",
  "message": {
    "from": "919876543210@c.us",
    "body": "Hello",
    "timestamp": 1712143512
  }
}

Receiver Example

app.post('/my-webhook', express.json(), (req, res) => {
  const payload = req.body;
  // TODO: store/queue payload
  return res.status(200).json({ ok: true });
});

Important Notes

1. Set webhook URL per instance from dashboard when creating or editing an instance.
2. Respond quickly with HTTP 200; slow endpoints may miss delivery.
3. Current implementation sends incoming message webhook only. Delivery/read status is available in Message Logs and Reports APIs.

Postman Collection

Import this once and test every API route without manually writing requests.

1. Download collection and environment from buttons below.
2. Import both into Postman.
3. Set `api_key` variable with your generated key.
4. Set `instance_id` variable to your own instance `_id` or `instanceId` key.
5. Run requests folder-by-folder (Messaging, Meta Cloud).
6. For Meta template testing, start with: `Send Template (Meta Instance)` and `Send Template Bulk (Meta Instance)`.

Common Errors

Meta Template Troubleshooting

{
  "success": false,
  "requestId": "req_7f83e8a2c5f0d9ab",
  "timestamp": "2026-03-20T11:53:22.111Z",
  "error": "Insufficient credits (1 credit required)",
  "code": "BILLING_INSUFFICIENT_CREDITS",
  "details": null,
  "meta": {}
}