Developer API

The Developer API provides a unified, API-key-authenticated interface for sending messages across WhatsApp, Instagram, and Facebook Messenger. Use it to integrate messaging into your backend systems, CRMs, and automation workflows.

Authentication

All Developer API endpoints use the x-api-key header. Generate an API key from Settings → Developer → API Keys in the SuperWaba dashboard.

x-api-key: sgk_90zR•••••••••8cnV
Content-Type: application/json

Invalid API key (401):

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Base URL

https://app.superwaba.com/api/developer/v1

Rate Limiting & Monthly Metering

All Developer API send-message endpoints and webhook event dispatches share a single monthly event counter per organization. When the cap is reached, both send-message calls and webhook deliveries are blocked until the next billing cycle.

Plan	Monthly Events
Insta / Starter	5,000
Growth	10,000
Pro	50,000
Enterprise	Unlimited

Rate limit reached (429):

{
  "success": false,
  "message": "Monthly API event limit reached (5000/5000). Upgrade your plan for more.",
  "code": "API_LIMIT_REACHED"
}

You can monitor current usage in Settings → Developer → Logs.

Response Format

All responses follow this envelope:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "message": "Human-readable error description",
  "code": "ERROR_CODE",
  "fix": "Suggested fix (when available)"
}

WhatsApp — Send Template Message

Send a pre-approved WhatsApp template message.

POST /v1/send-message

cURL

curl -X POST 'https://app.superwaba.com/api/developer/v1/send-message' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "919876543210",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "ORD-456" }
        ]
      }
    ]
  }
}'

Request Body

{
  "to": "919876543210",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "ORD-456" }
        ]
      }
    ]
  }
}

Parameters

Parameter	Type	Required	Description
`to`	string	Yes	Phone number in E.164 format without `+` (e.g. `"919876543210"`)
`type`	string	No	Message type. Default: `"template"`
`template.name`	string	Yes	Approved template name
`template.language.code`	string	Yes	Template language code (e.g. `"en"`)
`template.components`	array	No	Template variable values (header, body, button params)

Response — 201 Created

{
  "success": true,
  "data": {
    "waMessageId": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYZ...",
    "status": "sent",
    "conversationId": "conv_a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "contactId": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef"
  }
}

Response — 400 Missing Field

{
  "success": false,
  "message": "Missing required field: to",
  "code": "MISSING_FIELD",
  "fix": "Include \"to\" field with phone number in E.164 format (e.g. \"919876543210\")"
}

Response — 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Response — 429 Monthly Limit Reached

{
  "success": false,
  "message": "Monthly API event limit reached (5000/5000). Upgrade your plan for more.",
  "code": "API_LIMIT_REACHED"
}

Response — 500 Server Error

{
  "success": false,
  "message": "Internal server error"
}

Instagram — Send DM

Send a direct message to an Instagram user. Supports text, image, audio, video, file, like_heart, and media_share types.

POST /v1/instagram/send-message

Messaging Window

Standard messages must be sent within 24 hours of the user's last message.
Use tag: "HUMAN_AGENT" to extend the window to 7 days (for live-agent support only — Meta policy).

cURL — Text Message

curl -X POST 'https://app.superwaba.com/api/developer/v1/instagram/send-message' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "participantId": "17841400000000000",
  "type": "text",
  "text": "Hello from the API!"
}'

Request Body — All Types

Text:

{
  "participantId": "17841400000000000",
  "type": "text",
  "text": "Hello from the API!"
}

Image (public URL):

{
  "participantId": "17841400000000000",
  "type": "image",
  "mediaUrl": "https://example.com/photo.jpg"
}

Image (Meta CDN — preferred for speed):

{
  "participantId": "17841400000000000",
  "type": "image",
  "attachmentId": "1234567890"
}

Video:

{
  "participantId": "17841400000000000",
  "type": "video",
  "mediaUrl": "https://example.com/video.mp4"
}

Audio:

{
  "participantId": "17841400000000000",
  "type": "audio",
  "mediaUrl": "https://example.com/audio.mp3"
}

File:

{
  "participantId": "17841400000000000",
  "type": "file",
  "mediaUrl": "https://example.com/document.pdf"
}

Like heart reaction:

{
  "participantId": "17841400000000000",
  "type": "like_heart"
}

Share an Instagram post:

{
  "participantId": "17841400000000000",
  "type": "media_share",
  "postId": "17890000000000000"
}

With HUMAN_AGENT tag (extends 24h window to 7 days):

{
  "participantId": "17841400000000000",
  "type": "text",
  "text": "Following up on your inquiry",
  "tag": "HUMAN_AGENT"
}

Parameters

Parameter	Type	Required	Description
`participantId`	string	Yes	Instagram-scoped user ID of the recipient
`type`	string	No	`"text"` \| `"image"` \| `"audio"` \| `"video"` \| `"file"` \| `"like_heart"` \| `"media_share"`. Default: `"text"`
`text`	string	Conditional	Message text (required when `type` is `"text"`)
`mediaUrl`	string	Conditional	Public URL of media file (for image/audio/video/file)
`attachmentId`	string	Conditional	Meta CDN attachment ID — preferred over `mediaUrl`
`postId`	string	Conditional	Instagram Post ID (required when `type` is `"media_share"`)
`tag`	string	No	`"HUMAN_AGENT"` — extends the 24h messaging window to 7 days

Response — 201 Created

{
  "success": true,
  "data": {
    "messageId": "mid.$cAAJsb3ADKF2mBRdvalgzRb3RNIHR"
  }
}

Response — 400 Missing participantId

{
  "success": false,
  "message": "Missing required field: participantId",
  "code": "MISSING_FIELD",
  "fix": "Include \"participantId\" — the Instagram-scoped user ID of the recipient"
}

Response — 400 Missing text

{
  "success": false,
  "message": "Missing required field: text",
  "code": "MISSING_FIELD",
  "fix": "Include \"text\" field with the message content"
}

Response — 400 Missing media

{
  "success": false,
  "message": "Missing required field: attachmentId or mediaUrl",
  "code": "MISSING_FIELD",
  "fix": "Include \"attachmentId\" (Meta CDN) or \"mediaUrl\" (public URL) for media messages"
}

Response — 400 Missing postId

{
  "success": false,
  "message": "Missing required field: postId",
  "code": "MISSING_FIELD",
  "fix": "Include \"postId\" — the Instagram Post ID to share"
}

Response — 400 Invalid Type

{
  "success": false,
  "message": "Unknown message type: sticker",
  "code": "INVALID_TYPE",
  "fix": "Supported types: text, image, audio, video, file, like_heart, media_share"
}

Response — 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Response — 404 Not Connected

{
  "success": false,
  "message": "Instagram not connected. Connect your Instagram account first."
}

Response — 429 Monthly Limit Reached

{
  "success": false,
  "message": "Monthly API event limit reached (5000/5000). Upgrade your plan for more.",
  "code": "API_LIMIT_REACHED"
}

Response — 500 Token Decryption Failed

{
  "success": false,
  "message": "Failed to decrypt Instagram token"
}

Response — 502 Meta API Error

Returned when the Meta Graph API rejects the message (e.g. outside the messaging window):

{
  "success": false,
  "message": "This message is sent outside of allowed window."
}

Response — 500 Internal Server Error

{
  "success": false,
  "message": "Internal server error"
}

Messenger — Send Message

Send a message via Facebook Messenger. Supports text, quick replies, button templates, generic templates (carousels), and URL attachments.

POST /v1/messenger/send-message

Messaging Window

Standard messages must be sent within 24 hours of the user's last message.
Use tag: "HUMAN_AGENT" to extend the window to 7 days (for live-agent support only).

cURL — Text Message

curl -X POST 'https://app.superwaba.com/api/developer/v1/messenger/send-message' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipientId": "1234567890",
  "type": "text",
  "text": "Hello from the API!"
}'

Request Body — All Types

Text:

{
  "recipientId": "1234567890",
  "type": "text",
  "text": "Hello from the API!"
}

Quick replies:

{
  "recipientId": "1234567890",
  "type": "quick_replies",
  "text": "What would you like to do?",
  "quickReplies": [
    { "title": "View Pricing", "payload": "PRICING" },
    { "title": "Talk to Agent", "payload": "AGENT" },
    { "title": "Track Order", "imageUrl": "https://example.com/track-icon.png" }
  ]
}

Button template (max 3 buttons):

{
  "recipientId": "1234567890",
  "type": "button_template",
  "buttonTemplateText": "How can we help you today?",
  "buttons": [
    { "type": "web_url", "title": "Visit Website", "url": "https://example.com" },
    { "type": "postback", "title": "Get Help", "payload": "HELP" },
    { "type": "phone_number", "title": "Call Us", "payload": "+919876543210" }
  ]
}

Generic template / Carousel (max 10 elements):

{
  "recipientId": "1234567890",
  "type": "generic_template",
  "elements": [
    {
      "title": "Product A",
      "subtitle": "Best seller — $29",
      "imageUrl": "https://example.com/a.jpg",
      "defaultAction": { "type": "web_url", "url": "https://example.com/a" },
      "buttons": [
        { "type": "web_url", "title": "Buy Now", "url": "https://example.com/a" },
        { "type": "postback", "title": "More Info", "payload": "INFO_A" }
      ]
    },
    {
      "title": "Product B",
      "subtitle": "New arrival — $19",
      "imageUrl": "https://example.com/b.jpg"
    }
  ]
}

Attachment via URL:

{
  "recipientId": "1234567890",
  "type": "attachment_url",
  "attachmentUrl": "https://example.com/brochure.pdf",
  "attachmentType": "file"
}

With HUMAN_AGENT tag:

{
  "recipientId": "1234567890",
  "type": "text",
  "text": "Following up on your request",
  "tag": "HUMAN_AGENT"
}

Parameters

Parameter	Type	Required	Description
`recipientId`	string	Yes	Facebook-scoped user ID (Page-Scoped ID) of the recipient
`type`	string	No	`"text"` \| `"quick_replies"` \| `"button_template"` \| `"generic_template"` \| `"attachment_url"`. Default: `"text"`
`text`	string	Conditional	Message text (required for `"text"` and `"quick_replies"`)
`quickReplies`	array	Conditional	Quick reply buttons: `[{ title, payload?, imageUrl? }]`
`buttonTemplateText`	string	Conditional	Text displayed above buttons (required for `"button_template"`)
`buttons`	array	Conditional	Button list (max 3): `[{ type, title, url?, payload? }]`
`elements`	array	Conditional	Carousel cards (max 10): `[{ title, subtitle?, imageUrl?, defaultAction?, buttons? }]`
`attachmentUrl`	string	Conditional	Public URL of file (required for `"attachment_url"`)
`attachmentType`	string	No	`"image"` \| `"video"` \| `"audio"` \| `"file"`. Default: `"file"`
`tag`	string	No	`"HUMAN_AGENT"` — extends the 24h messaging window to 7 days

Button Types

Type	Fields	Description
`web_url`	`title`, `url`	Opens a URL in a webview
`postback`	`title`, `payload`	Sends a postback event to your webhook
`phone_number`	`title`, `payload`	Opens the phone dialer with the given number

Response — 201 Created

{
  "success": true,
  "data": {
    "messageId": "mid.$cAAJsb3ADKF2mBRdvalgzRb3RNIHR"
  }
}

Response — 400 Missing recipientId

{
  "success": false,
  "message": "Missing required field: recipientId",
  "code": "MISSING_FIELD",
  "fix": "Include \"recipientId\" — the Facebook-scoped user ID of the recipient"
}

Response — 400 Missing text

{
  "success": false,
  "message": "Missing required field: text",
  "code": "MISSING_FIELD",
  "fix": "Include \"text\" field with the message content"
}

Response — 400 Missing text (quick_replies)

{
  "success": false,
  "message": "Missing required field: text (for quick_replies)",
  "code": "MISSING_FIELD",
  "fix": "Include \"text\" field — the prompt shown above the quick reply buttons"
}

Response — 400 Missing quickReplies

{
  "success": false,
  "message": "Missing required field: quickReplies",
  "code": "MISSING_FIELD",
  "fix": "Include \"quickReplies\" array with at least one { title } object"
}

Response — 400 Missing buttonTemplateText

{
  "success": false,
  "message": "Missing required field: buttonTemplateText",
  "code": "MISSING_FIELD",
  "fix": "Include \"buttonTemplateText\" — the text shown above the buttons"
}

Response — 400 Missing buttons

{
  "success": false,
  "message": "Missing required field: buttons",
  "code": "MISSING_FIELD",
  "fix": "Include \"buttons\" array (max 3) with { type, title, url/payload }"
}

Response — 400 Missing elements

{
  "success": false,
  "message": "Missing required field: elements",
  "code": "MISSING_FIELD",
  "fix": "Include \"elements\" array (max 10) — each with { title } at minimum"
}

Response — 400 Missing attachmentUrl

{
  "success": false,
  "message": "Missing required field: attachmentUrl",
  "code": "MISSING_FIELD",
  "fix": "Include \"attachmentUrl\" — a public URL to the file"
}

Response — 400 Invalid Type

{
  "success": false,
  "message": "Unknown message type: sticker",
  "code": "INVALID_TYPE",
  "fix": "Supported types: text, quick_replies, button_template, generic_template, attachment_url"
}

Response — 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Response — 404 Not Connected

{
  "success": false,
  "message": "Messenger not connected. Connect your Facebook Page first."
}

Response — 400 Token Missing

{
  "success": false,
  "message": "Messenger token not stored — reconnect the account"
}

Response — 429 Monthly Limit Reached

{
  "success": false,
  "message": "Monthly API event limit reached (5000/5000). Upgrade your plan for more.",
  "code": "API_LIMIT_REACHED"
}

Response — 500 Token Decryption Failed

{
  "success": false,
  "message": "Failed to decrypt Messenger token"
}

Response — 502 Meta API Error

Returned when the Meta Graph API rejects the message:

{
  "success": false,
  "message": "This message is sent outside of allowed window."
}

Response — 500 Internal Server Error

{
  "success": false,
  "message": "Internal server error"
}

Notes

Button titles are truncated to 20 characters.
Button templates support a maximum of 3 buttons.
Generic templates (carousels) support up to 10 elements, each with up to 3 buttons.
Quick reply titles are truncated to 20 characters.
If no payload is provided for quick replies, the title is auto-converted to uppercase with underscores (e.g. "View Pricing" → "VIEW_PRICING").

List Templates

Retrieve all approved WhatsApp message templates for your organization.

GET /v1/templates

cURL

curl -X GET 'https://app.superwaba.com/api/developer/v1/templates' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "hello_world",
      "language": "en",
      "status": "APPROVED",
      "category": "MARKETING",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}, welcome to SuperWaba!"
        }
      ]
    },
    {
      "id": "template_def456",
      "name": "order_update",
      "language": "en",
      "status": "APPROVED",
      "category": "UTILITY",
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{1}}, your order {{2}} has been shipped."
        }
      ]
    }
  ]
}

Response — 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

List Conversations

Retrieve conversation lists for each channel.

WhatsApp Conversations

GET /v1/conversations/whatsapp

cURL:

curl -X GET 'https://app.superwaba.com/api/developer/v1/conversations/whatsapp?page=1&limit=20' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Query parameters:

Parameter	Type	Default	Description
`page`	number	`1`	Page number
`limit`	number	`20`	Results per page (max: 100)

Response — 200 OK:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "conv_a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "contact": {
          "name": "Priya Sharma",
          "phone": "+919876543210"
        },
        "last_message": "Hi, I need help with my order",
        "status": "open",
        "updated_at": "2026-05-26T14:22:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 42
    }
  }
}

Response — 401 Invalid API Key:

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Instagram Conversations

GET /v1/conversations/instagram

cURL:

curl -X GET 'https://app.superwaba.com/api/developer/v1/conversations/instagram' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Response — 200 OK:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "t_100123456789",
        "updated_time": "2026-05-26T14:22:00.000Z",
        "participants": [
          {
            "id": "17841400000000000",
            "username": "priya_sharma",
            "name": "Priya Sharma"
          }
        ]
      }
    ]
  }
}

Response — 404 Not Connected:

{
  "success": false,
  "message": "Instagram not connected. Connect your Instagram account first."
}

Response — 500 Token Error:

{
  "success": false,
  "message": "Failed to decrypt Instagram token"
}

Messenger Conversations

GET /v1/conversations/messenger

cURL:

curl -X GET 'https://app.superwaba.com/api/developer/v1/conversations/messenger' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Response — 200 OK:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "t_100987654321",
        "updated_time": "2026-05-26T14:22:00.000Z",
        "unread_count": 2,
        "participants": [
          {
            "id": "1234567890",
            "name": "Priya Sharma"
          }
        ]
      }
    ]
  }
}

Response — 404 Not Connected:

{
  "success": false,
  "message": "Messenger not connected. Connect your Facebook Page first."
}

Response — 500 Token Error:

{
  "success": false,
  "message": "Failed to decrypt Messenger token"
}

List Contacts

GET /v1/contacts

cURL

curl -X GET 'https://app.superwaba.com/api/developer/v1/contacts?page=1&limit=20&search=priya' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number
`limit`	number	`20`	Results per page (max: 100)
`search`	string	—	Search by name or phone number

Response — 200 OK

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
        "name": "Priya Sharma",
        "phone": "+919876543210",
        "email": "priya@example.com",
        "tags": ["vip", "returning"],
        "created_at": "2026-03-10T08:00:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 150
    }
  }
}

Response — 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Create / Update Contact

POST /v1/contacts

cURL

curl -X POST 'https://app.superwaba.com/api/developer/v1/contacts' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "phone": "919876543210",
  "name": "Priya Sharma",
  "email": "priya@example.com",
  "tags": ["lead", "vip"],
  "attributes": {
    "company": "Acme Inc",
    "source": "website"
  }
}'

Request Body

{
  "phone": "919876543210",
  "name": "Priya Sharma",
  "email": "priya@example.com",
  "tags": ["lead", "vip"],
  "attributes": {
    "company": "Acme Inc",
    "source": "website"
  }
}

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Phone number (E.164 format without `+`)
`name`	string	No	Contact display name
`email`	string	No	Email address
`tags`	string[]	No	Array of tag strings
`attributes`	object	No	Custom key-value attributes

Response — 201 Created

{
  "success": true,
  "data": {
    "id": "contact_new12345-6789-01ab-cdef-abcdefabcdef",
    "phone": "919876543210",
    "name": "Priya Sharma",
    "email": "priya@example.com",
    "tags": ["lead", "vip"]
  }
}

Response — 400 Missing Phone

{
  "success": false,
  "message": "phone is required"
}

Response — 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Webhooks

Get Webhook Configuration

GET /v1/webhooks

curl -X GET 'https://app.superwaba.com/api/developer/v1/webhooks' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Response — 200 OK:

{
  "success": true,
  "data": {
    "webhook": {
      "id": "wh_a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "url": "https://your-server.com/webhooks/superginie",
      "events": [
        "message.received",
        "message.sent",
        "message.delivered",
        "message.read",
        "message.failed",
        "contact.created",
        "contact.updated",
        "conversation.opened",
        "conversation.closed"
      ],
      "status": "active",
      "secret": "whsec_abc123..."
    }
  }
}

Register or Update Webhook

POST /v1/webhooks

curl -X POST 'https://app.superwaba.com/api/developer/v1/webhooks' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://your-server.com/webhooks/superginie",
  "events": ["message.received", "message.sent", "conversation.closed"],
  "signing_secret": "whsec_your_secret"
}'

Request Body:

{
  "url": "https://your-server.com/webhooks/superginie",
  "events": [
    "message.received",
    "message.sent",
    "message.delivered",
    "message.read",
    "message.failed",
    "contact.created",
    "contact.updated",
    "conversation.opened",
    "conversation.closed"
  ],
  "signing_secret": "whsec_your_secret"
}

Parameter	Type	Required	Description
`url`	string	Yes	HTTPS URL to receive webhook POST events
`events`	string[]	Yes	Array of event types to subscribe to
`signing_secret`	string	No	Secret sent as `X-Webhook-Secret` header for verification

Response — 200 OK:

{
  "success": true,
  "data": {
    "webhook": {
      "id": "wh_a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "url": "https://your-server.com/webhooks/superginie",
      "events": ["message.received", "message.sent", "conversation.closed"],
      "status": "active"
    }
  }
}

Response — 400 Invalid URL:

{
  "success": false,
  "message": "Webhook URL must use HTTPS"
}

Remove Webhook

DELETE /v1/webhooks

curl -X DELETE 'https://app.superwaba.com/api/developer/v1/webhooks' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Response — 200 OK:

{
  "success": true,
  "message": "Webhook removed"
}

API Request Logs

GET /v1/logs

cURL

curl -X GET 'https://app.superwaba.com/api/developer/v1/logs?page=1&limit=20' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number
`limit`	number	`20`	Results per page (max: 100)

Response — 200 OK

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "log_a1b2c3d4",
        "method": "POST",
        "path": "/v1/instagram/send-message",
        "status_code": 201,
        "request_body": {
          "participantId": "17841400000000000",
          "type": "text"
        },
        "response_body": {
          "messageId": "mid.XXXX"
        },
        "ip_address": "203.0.113.42",
        "user_agent": "curl/8.1.2",
        "duration_ms": 1066,
        "created_at": "2026-05-26T17:39:00.000Z"
      },
      {
        "id": "log_e5f6g7h8",
        "method": "POST",
        "path": "/v1/instagram/send-message",
        "status_code": 502,
        "request_body": {
          "participantId": "17841400000000000",
          "type": "text"
        },
        "response_body": {
          "error": "This message is sent outside of allowed window."
        },
        "ip_address": "203.0.113.42",
        "user_agent": "curl/8.1.2",
        "duration_ms": 903,
        "created_at": "2026-05-26T17:38:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 44,
      "totalPages": 3
    }
  }
}

Response — 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

Webhook Events for API Messages

When you send a message via the Developer API, a message.sent webhook event is dispatched (if you have an active webhook subscription).

Instagram text message sent via API:

{
  "event": "message.sent",
  "timestamp": "2026-05-26T14:30:00.000Z",
  "webhook_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": {
    "channel": "instagram",
    "message_id": "mid.$cAAJsb3ADKF2mBRdvalgzRb3RNIHR",
    "to": "17841400000000000",
    "type": "text",
    "content": {
      "text": "Hello from the API!"
    },
    "status": "sent",
    "timestamp": "2026-05-26T14:30:00.000Z"
  }
}

Messenger carousel sent via API:

{
  "event": "message.sent",
  "timestamp": "2026-05-26T14:30:00.000Z",
  "webhook_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": {
    "channel": "messenger",
    "message_id": "mid.YYYY",
    "to": "1234567890",
    "type": "generic_template",
    "content": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "generic",
          "elements": [
            {
              "title": "Product A",
              "subtitle": "Best seller — $29",
              "image_url": "https://example.com/a.jpg",
              "buttons": [
                { "type": "web_url", "title": "Buy Now", "url": "https://example.com/a" }
              ]
            }
          ]
        }
      }
    },
    "status": "sent",
    "timestamp": "2026-05-26T14:30:00.000Z"
  }
}

WhatsApp template sent via API:

{
  "event": "message.sent",
  "timestamp": "2026-05-26T14:30:00.000Z",
  "webhook_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": {
    "channel": "whatsapp",
    "message_id": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYZ...",
    "to": "919876543210",
    "type": "template",
    "content": {
      "template": {
        "name": "order_update",
        "language": "en"
      }
    },
    "status": "sent",
    "timestamp": "2026-05-26T14:30:00.000Z"
  }
}

See Webhook Events for the full list of events, payload formats, and the Express.js/Python server examples.

Authentication​

Base URL​

Rate Limiting & Monthly Metering​

Response Format​

WhatsApp — Send Template Message​

cURL​

Request Body​

Parameters​

Response — 201 Created​

Response — 400 Missing Field​

Response — 401 Invalid API Key​

Response — 429 Monthly Limit Reached​

Response — 500 Server Error​

Instagram — Send DM​

Messaging Window​

cURL — Text Message​

Request Body — All Types​

Parameters​

Response — 201 Created​

Response — 400 Missing participantId​

Response — 400 Missing text​

Response — 400 Missing media​

Response — 400 Missing postId​

Response — 400 Invalid Type​

Response — 401 Invalid API Key​

Response — 404 Not Connected​

Response — 429 Monthly Limit Reached​

Response — 500 Token Decryption Failed​

Response — 502 Meta API Error​

Response — 500 Internal Server Error​

Messenger — Send Message​

Messaging Window​

cURL — Text Message​

Request Body — All Types​

Parameters​

Button Types​

Response — 201 Created​

Response — 400 Missing recipientId​

Response — 400 Missing text​

Response — 400 Missing text (quick_replies)​

Response — 400 Missing quickReplies​

Response — 400 Missing buttonTemplateText​

Response — 400 Missing buttons​

Response — 400 Missing elements​

Response — 400 Missing attachmentUrl​

Response — 400 Invalid Type​

Response — 401 Invalid API Key​

Response — 404 Not Connected​

Response — 400 Token Missing​

Response — 429 Monthly Limit Reached​

Response — 500 Token Decryption Failed​

Response — 502 Meta API Error​

Response — 500 Internal Server Error​

Notes​

List Templates​

cURL​

Response — 200 OK​

Response — 401 Invalid API Key​

List Conversations​

WhatsApp Conversations​

Instagram Conversations​

Messenger Conversations​

List Contacts​

cURL​

Query Parameters​

Response — 200 OK​

Response — 401 Invalid API Key​

Create / Update Contact​

cURL​

Request Body​

Parameters​

Response — 201 Created​

Response — 400 Missing Phone​

Response — 401 Invalid API Key​

Webhooks​

Get Webhook Configuration​

Register or Update Webhook​

Remove Webhook​

API Request Logs​

cURL​

Authentication

Base URL

Rate Limiting & Monthly Metering

Response Format

WhatsApp — Send Template Message

cURL

Request Body

Parameters

Response — 201 Created

Response — 400 Missing Field

Response — 401 Invalid API Key

Response — 429 Monthly Limit Reached

Response — 500 Server Error

Instagram — Send DM

Messaging Window

cURL — Text Message

Request Body — All Types

Parameters

Response — 201 Created

Response — 400 Missing participantId

Response — 400 Missing text

Response — 400 Missing media

Response — 400 Missing postId

Response — 400 Invalid Type

Response — 401 Invalid API Key

Response — 404 Not Connected

Response — 429 Monthly Limit Reached

Response — 500 Token Decryption Failed

Response — 502 Meta API Error

Response — 500 Internal Server Error

Messenger — Send Message

Messaging Window

cURL — Text Message

Request Body — All Types

Parameters

Button Types

Response — 201 Created

Response — 400 Missing recipientId

Response — 400 Missing text

Response — 400 Missing text (quick_replies)

Response — 400 Missing quickReplies

Response — 400 Missing buttonTemplateText

Response — 400 Missing buttons

Response — 400 Missing elements

Response — 400 Missing attachmentUrl

Response — 400 Invalid Type

Response — 401 Invalid API Key

Response — 404 Not Connected

Response — 400 Token Missing

Response — 429 Monthly Limit Reached

Response — 500 Token Decryption Failed

Response — 502 Meta API Error

Response — 500 Internal Server Error

Notes

List Templates

cURL

Response — 200 OK

Response — 401 Invalid API Key

List Conversations

WhatsApp Conversations

Instagram Conversations

Messenger Conversations

List Contacts

cURL

Query Parameters

Response — 200 OK

Response — 401 Invalid API Key

Create / Update Contact

cURL

Request Body

Parameters

Response — 201 Created

Response — 400 Missing Phone

Response — 401 Invalid API Key

Webhooks

Get Webhook Configuration

Register or Update Webhook

Remove Webhook

API Request Logs

cURL