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.

Base URL: https://viraldm.app/api/v1

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)

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

Automations API

Manage automated replies for DMs and comments.

List automations

GET/api/v1/automations

Create automation

POST/api/v1/automations

{
  "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

Type	Description
`DM_REPLY`	Reply to all incoming DMs
`KEYWORD_DM`	Reply only to DMs with specific words
`COMMENT_REPLY`	Public reply on comments
`COMMENT_TO_DM`	Comment + private DM with link/file
`STORY_REPLY`	Auto-reply to story replies
`MOOD_SHIELD`	Handle angry messages smartly

Subscribers API

GET/api/v1/subscribers

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

Query parameters

`tag`	Filter by tag
`leadScoreMin`	Minimum lead score (0-100)
`search`	Search username/email

Sequences (Drip Campaigns)

POST/api/v1/sequences

{
  "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

POST/api/v1/broadcasts

{
  "name": "Sale announcement",
  "message": "🔥 50% off this weekend only!",
  "attachmentUrl": "https://...",
  "segmentFilter": {
    "tags": ["hot-lead"],
    "leadScoreMin": 50,
    "isVip": false
  }
}

Webhooks

Set up incoming webhooks for real-time events.

POSThttps://your-app.com/webhook

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

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

Facebook Pages

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

/facebook/connect

YouTube Integration

Auto-reply to comments on your YouTube videos.

/youtube/connect

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 22 Indian languages
Fallback to template if AI fails

Pre-Conditions (Unique Feature)

`requireFollow`	Sender must follow your account
`requireCommentFirst`	Sender must have commented on a post first
`cooldownMinutes`	Don't reply to same user for X minutes
`notFollowingMessage`	Optional message if user not following

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"])

Need help? dev@viraldm.app