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...

Example payload

{
  "object": "instagram",
  "entry": [{
    "id": "17841432111391196",
    "time": 1777476726126,
    "changes": [{
      "field": "comments",
      "value": {
        "id": "17890012345",
        "text": "Love this!",
        "from": {"id": "123456", "username": "user123"},
        "media": {"id": "18071354672638470"}
      }
    }]
  }]
}

Example payload

{
  "object": "instagram",
  "entry": [{
    "messaging": [{
      "sender": {"id": "2358708294634624"},
      "recipient": {"id": "17841432111391196"},
      "timestamp": 1777476725580,
      "message": {
        "mid": "aWdfZAG1f...",
        "text": "Hey, I'm interested!"
      }
    }]
  }]
}

Example payload

{
  "object": "instagram",
  "entry": [{
    "messaging": [{
      "sender": {"id": "2358708294634624"},
      "postback": {
        "title": "Get Started",
        "payload": "{\"flow_id\":\"abc\"}"
      }
    }]
  }],
  "idm_optimized_body": {
    "user_id": "6703dbc9-...",
    "flow_id": "0e3501b6-...",
    "sender_id": "2358708294634624"
  }
}

Example payload

{
  "flow_id": "0e3501b6-...",
  "sender_id": "2358708294634624",
  "sender_username": "user123",
  "question": "What's your email?",
  "question_type": "email",
  "custom_variable_name": "user_email",
  "user_response": "user@example.com",
  "skip": false,
  "attempt_no": "1",
  "timestamp": "2026-04-29 17:11:59"
}

Example payload

{
  "flow_id": "0e3501b6-...",
  "flow_name": "Lead Gen Flow",
  "sender_id": "2358708294634624",
  "sender_username": "user123",
  "completed_at": "2026-04-29 17:17:15",
  "tags": ["lead", "vip"],
  "response_variables": {
    "email": "user@example.com",
    "phone": "+919876543210",
    "address": "123 Main St"
  }
}

Node.js

const crypto = require('crypto');

function verify(body, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return computed === signature;
}

Python

import hmac, hashlib, json

def verify(payload, signature, secret):
    computed = hmac.new(
        secret.encode(),
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    return 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"}
  ]
}