Skip to main content

Instagram

Instagram endpoints for sending direct 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 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​

ParameterTypeRequiredDescription
participantIdstringYesInstagram-scoped user ID of the recipient
typestringNo"text" | "image" | "audio" | "video" | "file" | "like_heart" | "media_share". Default: "text"
textstringConditionalMessage text (required when type is "text")
mediaUrlstringConditionalPublic URL of media file (for image/audio/video/file)
attachmentIdstringConditionalMeta CDN attachment ID - preferred over mediaUrl
postIdstringConditionalInstagram Post ID (required when type is "media_share")
tagstringNo"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"
}

List 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"
}