InstantDM API Documentation

Platform

Official Meta Business Partner
Built on Meta Graph API v25.0

Base URL

https://api.instantdm.com

Dashboard

https://app.instantdm.com

API Endpoint

POST https://api.instantdm.com/api-webhook

Webhook Config

Settings → Integrations → Webhook Configuration

API Keys

Settings → Integrations → API Keys

Example Request

curl -X POST https://api.instantdm.com/api-webhook \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_message",
    "type": "dm",
    "recipient_id": "2358708294634624",
    "message": {"text": "Hello!"}
  }'

Webhook delivery format

POST https://your-webhook-url.com
Content-Type: application/json
X-Event-Type: comment
X-Timestamp: 2026-04-29T15:32:06+00:00
X-Webhook-Signature: a1b2c3d4...

Payload types

comment, dm_received, postback
  → Raw Instagram webhook payloads
    (same structure Meta sends)

question_answered, flow_completed
  → InstantDM-specific structured data

Example payload

{
  "entry": [{
    "id": "17841435672868203",
    "time": 1778223729,
    "changes": [{
      "value": {
        "from": {
          "id": "27021621630806157",
          "username": "pvamsi.krishna.73"
        },
        "media": {
          "id": "17933258556187263",
          "media_product_type": "REELS"
        },
        "id": "18114716611826474",
        "text": "2013",
        "recipient_id": "17841435672868203",
        "sender_id": "27021621630806157"
      },
      "field": "comments"
    }],
    "object": "instagram"
  }]
}

Example payload

{
  "object": "instagram",
  "entry": [{
    "time": 1778223729706,
    "id": "17841476961942794",
    "messaging": [{
      "sender": {
        "id": "978239761327698"
      },
      "recipient": {
        "id": "17841476961942794"
      },
      "timestamp": 1778223722476,
      "message": {
        "mid": "aWdfZAG1faXRlbToxOklHTWVz...",
        "text": "New"
      }
    }]
  }]
}

Example payload

{
  "object": "instagram",
  "entry": [{
    "time": 1778223725146,
    "id": "17841408795204378",
    "messaging": [{
      "sender": {
        "id": "2031528510825908"
      },
      "recipient": {
        "id": "17841408795204378"
      },
      "timestamp": 1778223723887,
      "postback": {
        "title": "Started following you! 👍",
        "payload": "{\"from\": {\"id\": \"2031528510825908\", \"username\": \"__zain_z\"}, \"media\": {\"id\": \"17939513463036158\", \"media_product_type\": \"REELS\"}, \"text\": \"prompt\", \"recipient_id\": \"17841408795204378\", \"sender_id\": \"2031528510825908\", \"user_id\": \"e10b1fc8-cade-4608-99cd-ce269bee2a2b\", \"creator_username\": \"dr_amina_nijas\", \"comment_reply\": true, \"story_reply\": false, \"dm_reply\": false}",
        "mid": "aWdfZAG1faXRlbToxOklHTWVz..."
      }
    }]
  }]
}

Example payload

{
  "flow_id": "5a0441b5-6589-4452-b8bf-90902c865893",
  "sender_id": "2031528510825908",
  "sender_username": "__zain_z",
  "question": "What's your name?",
  "question_type": "text",
  "custom_variable_name": "user_name",
  "user_response": "Zain",
  "skip": false,
  "attempt_no": "1",
  "timestamp": "2026-05-06 04:45:30.123456"
}

Example payload

{
  "flow_id": "5a0441b5-6589-4452-b8bf-90902c865893",
  "flow_name": "Lead Capture Flow",
  "sender_id": "2031528510825908",
  "sender_username": "__zain_z",
  "completed_at": "2026-05-06 04:46:15.654321",
  "attempt_no": "1",
  "tags": ["hot-lead", "interested"],
  "response_variables": {
    "user_name": "Zain",
    "email": "zain@example.com",
    "interest": "pricing"
  },
  "question_responses": [
    {
      "question": "What's your name?",
      "question_type": "text",
      "custom_variable_name": "user_name",
      "user_response": "Zain",
      "skip": false
    },
    {
      "question": "What's your email?",
      "question_type": "email",
      "custom_variable_name": "email",
      "user_response": "zain@example.com",
      "skip": false
    }
  ]
}

Node.js

const crypto = require('crypto');

function verify(rawBody, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(rawBody) // use raw body, not parsed
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

Python

import hmac, hashlib

def verify(raw_body, signature, secret):
    computed = hmac.new(
        secret.encode("utf-8"),
        raw_body.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature)

Available actions

post_comment   — Reply to a comment
send_message   — Send a DM or comment private reply

Request

{
  "action": "post_comment",
  "comment_id": "17890012345",
  "comment_text": "Thanks! Check your DM"
}

Response

{
  "message": "Comment reply posted",
  "comment_id": "17890012346"
}

DM Message

{
  "action": "send_message",
  "type": "dm",
  "recipient_id": "2358708294634624",
  "message": {"text": "Hello!"}
}

Comment Private Reply

{
  "action": "send_message",
  "type": "comment_reply",
  "comment_id": "17890012345",
  "message": {"text": "Here's the link..."}
}

Text

{"text": "Hello!"}

Image

{"attachment": {"type": "image",
  "payload": {"url": "https://example.com/photo.jpg"}}}

Video

{"attachment": {"type": "video",
  "payload": {"url": "https://example.com/video.mp4"}}}

Audio

{"attachment": {"type": "audio",
  "payload": {"url": "https://example.com/audio.mp3"}}}

Button Template

{"attachment": {"type": "template",
  "payload": {
    "template_type": "button",
    "text": "Choose an option:",
    "buttons": [
      {"type": "web_url", "title": "Visit", "url": "https://..."},
      {"type": "web_url", "title": "More", "url": "https://..."}
    ]
  }
}}

Quick Replies

{"text": "Pick one:",
  "quick_replies": [
    {"content_type": "text", "title": "A", "payload": "A"},
    {"content_type": "text", "title": "B", "payload": "B"}
  ]
}