Skip to main content

Messenger

Facebook Messenger endpoints for sending messages and listing conversations. All endpoints use API-key authentication and the standard response envelope — see Getting Started for x-api-key, base URL, and rate limits.

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​

ParameterTypeRequiredDescription
recipientIdstringYesFacebook-scoped user ID (Page-Scoped ID) of the recipient
typestringNo"text" | "quick_replies" | "button_template" | "generic_template" | "attachment_url". Default: "text"
textstringConditionalMessage text (required for "text" and "quick_replies")
quickRepliesarrayConditionalQuick reply buttons: [{ title, payload?, imageUrl? }]
buttonTemplateTextstringConditionalText displayed above buttons (required for "button_template")
buttonsarrayConditionalButton list (max 3): [{ type, title, url?, payload? }]
elementsarrayConditionalCarousel cards (max 10): [{ title, subtitle?, imageUrl?, defaultAction?, buttons? }]
attachmentUrlstringConditionalPublic URL of file (required for "attachment_url")
attachmentTypestringNo"image" | "video" | "audio" | "file". Default: "file"
tagstringNo"HUMAN_AGENT" - extends the 24h messaging window to 7 days

Button Types​

TypeFieldsDescription
web_urltitle, urlOpens a URL in a webview
postbacktitle, payloadSends a postback event to your webhook
phone_numbertitle, payloadOpens 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 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"
}