ViralDM API Documentation

Build powerful Instagram, Facebook, and YouTube automation with our REST API. Auto-reply DMs, comment automation, drip campaigns, broadcast messages, AI-powered smart replies in Hindi/English.

Authentication

All API requests require an API key. Get yours from Dashboard → API Keys.

Header-based

X-API-Key: your_api_key_here

Example request

curl https://viraldm.app/api/v1/automations \
  -H "X-API-Key: vdm_live_xxxxxxxxxx"

Quick Start (5 minutes)

1. Sign up at viraldm.app
2. Connect Instagram/Facebook/YouTube account
3. Create your first automation
4. Test with a real DM/comment
5. Enable AI for smart replies

Automations API

Manage automated replies for DMs and comments.

List automations

Create automation

{
  "name": "Welcome DM",
  "socialAccountId": "abc-123",
  "type": "DM_REPLY",
  "keywords": "hello,hi,welcome",
  "replyMessage": "Hey! Thanks for messaging 💜",
  "useAi": true,
  "requireFollow": true,
  "cooldownMinutes": 60
}

Automation Types

Scheduled Posts API

Schedule and manage Instagram / Facebook posts, Reels, and Stories. Scheduled items publish automatically at the set time.

List scheduled posts

Get one post

Schedule a post / reel / story

{
  "platform": "instagram",
  "postType": "REEL",            // POST | REEL | STORY (default POST)
  "content": "New drop 🔥 #sale",
  "scheduledFor": "2026-07-21T18:00:00+05:30",
  "mediaUrl": "https://cdn.example.com/reel.mp4"
}

REEL and STORY are Instagram-only and require mediaUrl (REEL = vertical video). POST needs either content or mediaUrl.

Edit a scheduled post

{
  "scheduledFor": "2026-07-21T21:00:00+05:30",
  "content": "Updated caption ✨"
}

Only works while the post is still SCHEDULED. Every field is optional — omitted fields keep their current value.

Cancel a scheduled post

Subscribers API

List all your subscribers with filtering by tags, lead score, VIP status.

Query parameters

Sequences (Drip Campaigns)

{
  "name": "Welcome Series",
  "socialAccountId": "abc-123",
  "trigger": {
    "type": "KEYWORD",
    "keywords": ["welcome", "start"]
  },
  "steps": [
    { "delayMinutes": 0, "message": "Hey! Welcome 💜" },
    { "delayMinutes": 60, "message": "Check out our plans..." },
    { "delayMinutes": 1440, "message": "Day 1 follow-up" }
  ]
}

Broadcasts API

Creating a broadcast does not send it. You get back the real recipient count so you can check it first; DMs only go out when you pass send: true.

{
  "name": "Sale announcement",
  "message": "🔥 50% off this weekend only!",
  "segment": "customers",
  "send": false
}

Body

Subscribers who opted out are excluded from both the count and the send, and anyone outside their 24-hour Instagram messaging window is skipped rather than failed.

Products API

Your digital store — files, locked content, courses, memberships, events, 1:1 sessions and external links.

Money units

Prices go in as rupees and come out as paise. Send 499 for ₹499; read it back as pricePaise: 49900. Sending paise on the way in would price the product at ₹49,900.

{
  "title": "Instagram Growth Playbook",
  "type": "DIGITAL_FILE",
  "price": 499,
  "comparePrice": 999,
  "gstPercent": 18,
  "stockLimit": 100,
  "deliverUrl": "https://drive.google.com/…",
  "deliverMessage": "Thanks! Your playbook is attached 💜"
}

PUT is a partial update — send only the fields you want to change, the rest are left alone. New products start as DRAFT and are not reachable on the web until you publish:

POST /api/v1/products/:id/status
{ "status": "PUBLISHED" }

Product types

Orders & sales

Buyers pay you directly over UPI — ViralDM is never in the money path and never holds your customers' funds. That means confirming a payment is your call, not ours.

POST /orders/:id/paid is for a server that has already seen the money land, for example your own payment webhook. It releases the product and books the revenue, so it is idempotent: confirming an order twice does not deliver twice. It is deliberately not available to AI agents over MCP.

GET /api/v1/store/stats?days=30

{
  "summary": {
    "revenuePaise": 1247500,
    "paidCount": 25,
    "avgOrderPaise": 49900,
    "conversionPct": 42,
    "startedCount": 59
  },
  "series":    [ { "date": "2026-08-01", "revenuePaise": 49900, "orders": 1 } ],
  "byProduct": [ { "title": "Growth Playbook", "paidCount": 25, "revenuePaise": 1247500 } ]
}

Revenue is counted on the day an order was paid, not the day the checkout began. conversionPct is null when no checkout has started — which is not the same as 0%.

Segments API

Named audiences with a live count of who is in each right now. Pass an id from here as a broadcast's segment.

Every segment is computed from current data rather than a saved list, so people join and leave as their behaviour changes. Opted-out subscribers are excluded from all of them.

Webhooks

Set up incoming webhooks for real-time events.

{
  "event": "dm_received",
  "subscriber": { "id": "sub_xxx", "username": "user1" },
  "message": "Hello",
  "automationTriggered": "Welcome DM"
}

Instagram Integration

Connect Instagram Business/Creator account via Instagram Login OAuth.

1. Account must be Business or Creator (not Personal)
2. OAuth flow: /dashboard/accounts/connect/instagram
3. Permissions: business_basic, manage_messages, manage_comments
4. Webhooks auto-subscribed on connect

Facebook Pages

Connect any Facebook Page you manage. Auto-detects linked Instagram accounts.

YouTube Integration

Auto-reply to comments on your YouTube videos.

Requires Google Cloud OAuth credentials.

AI Smart Replies

Enable useAi: true on any automation to get AI-generated contextual replies.

• Native Hindi, English, Hinglish support
• Detects mood and matches tone
• Supports 9 Indian languages
• Fallback to template if AI fails

Pre-Conditions (Unique Feature)

Subscriber Segmentation

Built-in CRM with auto lead scoring. Filter and target users by:

• Lead score (0-100, auto-calculated from mood)
• Tags (custom + auto-tagged)
• VIP status
• Activity (DMs sent, last active)
• Custom fields (collected via flows)

Node.js SDK

const ViralDM = require('@viraldm/sdk');
const client = new ViralDM({ apiKey: 'your_key' });

const automation = await client.automations.create({
  name: 'Welcome',
  type: 'DM_REPLY',
  keywords: ['hi', 'hello']
});

Python SDK

from viraldm import Client
client = Client(api_key="your_key")
client.automations.create(name="Welcome", type="DM_REPLY", keywords=["hi"])