Docs · Tools reference

AI connector

Tools reference

Every action an AI app can take in DMFast, and what it needs.

These are the 35 tools your AI app sees, straight from the DMFast server. You don't call them yourself: ask in plain words and the app picks the tool. Parameters marked ? are optional.

  • Reads only tools never change anything.
  • Makes changes tools save something in DMFast; most apps ask you to confirm first.
  • Reaches real people means the result goes out on Instagram, Messenger or to a buyer (a DM, a reply, an email or a refund).

Account

get_accountAccount and planReads only

The connected account on DMFast (an Instagram account or a Facebook Page): its plan and this month's usage against the plan's limits (people replied to, emails collected, account look-ups, AI credits), how many auto-replies are on, and the AI reply settings.

Auto-replies

list_auto_repliesList auto-repliesReads only

Every auto-reply on the account: what triggers it (comments, story replies or DMs with which keywords, on which post), what it sends, whether it's on, and how many people it has replied to. Check this before creating one, so a keyword isn't used twice.

get_auto_replyAuto-reply detailsReads only

One auto-reply's full setup (every message, the link, follower and email steps, reminder) and its last 30 days: people started, got the link, clicked it, emails collected.

id: string
The auto-reply's id, from list_auto_replies.
create_auto_replyCreate an auto-replyMakes changes

Create an auto-reply; it starts answering right away. When someone comments a keyword on a post (or replies to a story, or sends a DM with a keyword), DMFast can reply publicly under the comment, then DMs them the opening message. For comments it waits for them to answer that DM; for story replies and DMs it carries on at once: it checks they follow (optional), asks for their email (optional), then sends the final message with up to 3 link buttons, or a carousel of products. Instead of keywords it can start on a meaning (intent, AI). On a Facebook Page the DMs go to Messenger, and story replies and followers_only aren't available. Check list_auto_replies first so keywords don't clash; list_recent_posts gives post and story ids. Confirm the messages with the user before creating it.

trigger: "comment" | "story_reply" | "dm" | "live"
comment: someone comments on a post. story_reply: someone replies to a story. dm: someone sends a DM. live: someone comments during an Instagram Live (any Live; the DM goes out while the Live is on; Pro plan and up; no public replies).
keywords?: string[]
Words that trigger it, matched as whole words in any case, e.g. ["GUIDE"]. Empty (and no intent) = every comment, story reply or DM.
post_ids?: string[]
Comment auto-replies only: the posts to watch, from list_recent_posts (one or several, on every plan). Leave out to watch every post, including future ones.
post_id?: string
Comment auto-replies only: one post to watch (same as post_ids with one id).
story_id?: string
Story-reply auto-replies only: one live story, from list_recent_posts. Leave out to answer replies to every story.
name?: string
A short name for the dashboard. Default: the keywords and trigger, e.g. "GUIDE comments".
opening_message: string
The first DM. For comments it must invite a reply, e.g. "Hey {name}! Reply YES and I'll send you the guide": Instagram allows one message per comment until the person answers. In any message, {name} becomes their first name (or username) and {username} their handle.
public_replies?: string[]
Comment auto-replies only: public replies under the comment, one picked at random, e.g. ["Sent! Check your DMs 📩"]. Leave empty for none.
link_url?: string
The link to send (https://…), shown as a button. Leave out to send only the final message.
link_message?: string
The final message, sent with the link button. Default "Here you go:".
link_button?: string
Button label, at most 20 characters. Default "Open link".
more_links?: object[]
Up to 2 more links in the same DM after link_url, each its own button with its own click count (Pro plan and up). Send [] to remove them.
intent?: string
Start on a meaning instead of keywords (Growth plan and up): what people mean, e.g. "asks about the price" or "wants to collaborate". DMFast's AI matches comments or DMs that mean it, in any words or language, using 1 AI credit per match. keywords are then ignored. Keyword auto-replies are always checked first.
followers_only?: boolean
Send the link only to people who follow the account (Pro plan and up).
follow_prompt?: string
Message asking non-followers to follow first (with followers_only).
collect_email?: boolean
Ask for their email before sending the link; it's saved under Emails.
email_prompt?: string
Message asking for the email (with collect_email).
media_url?: string
A photo (JPG, PNG, GIF up to 8 MB), video (MP4, MOV, WebM up to 25 MB) or voice note (M4A, AAC, WAV up to 25 MB) to send just before the link, as a public https:// link: DMFast downloads and keeps a copy. "" removes it. Pro plan and up.
reminder_after_minutes?: integer
Send one reminder if they stop, after this many minutes (Pro plan and up): while DMFast waits for a follow or an email, or when they got the link and didn't open it. Skipped if they reply or tap. At most 1200 (Instagram's 24-hour window).
reminder_message?: string
The reminder's text (with reminder_after_minutes).
products?: object[]
Instead of one link: products sent as a swipeable carousel, each card with a photo, name, price and button. Only url is needed: missing details are read from the product page. link_message goes first, as text. Send [] to go back to a single link.
active?: boolean
Default true (live right away). false saves it paused.
update_auto_replyChange an auto-replyMakes changes

Change an auto-reply: turn it on or off, rename it, change its keywords, intent, posts or story, or edit any message, the links, the follower and email steps or the reminder. Only the fields you send change. Send an empty string to clear an optional text (e.g. link_url or intent), and reminder_after_minutes 0 to remove the reminder. Sending keywords switches an intent trigger back to keywords.

id: string
The auto-reply's id, from list_auto_replies.
active?: boolean
true turns it on, false pauses it.
name?: string
New name.
keywords?: string[]
New keywords (replaces the old ones). Empty = every comment, story reply or DM.
post_ids?: string[]
Comment auto-replies only: the posts to watch (replaces the old ones). [] watches every post.
post_id?: string
Comment auto-replies only: one post id from list_recent_posts, or "all" to watch every post.
story_id?: string
Story-reply auto-replies only: a live story's id, or "all" for every story.
opening_message?: string
The first DM. For comments it must invite a reply, e.g. "Hey {name}! Reply YES and I'll send you the guide": Instagram allows one message per comment until the person answers. In any message, {name} becomes their first name (or username) and {username} their handle.
public_replies?: string[]
Comment auto-replies only: public replies under the comment, one picked at random, e.g. ["Sent! Check your DMs 📩"]. Leave empty for none.
link_url?: string
The link to send (https://…), shown as a button. Leave out to send only the final message.
link_message?: string
The final message, sent with the link button. Default "Here you go:".
link_button?: string
Button label, at most 20 characters. Default "Open link".
more_links?: object[]
Up to 2 more links in the same DM after link_url, each its own button with its own click count (Pro plan and up). Send [] to remove them.
intent?: string
Start on a meaning instead of keywords (Growth plan and up): what people mean, e.g. "asks about the price" or "wants to collaborate". DMFast's AI matches comments or DMs that mean it, in any words or language, using 1 AI credit per match. keywords are then ignored. Keyword auto-replies are always checked first.
followers_only?: boolean
Send the link only to people who follow the account (Pro plan and up).
follow_prompt?: string
Message asking non-followers to follow first (with followers_only).
collect_email?: boolean
Ask for their email before sending the link; it's saved under Emails.
email_prompt?: string
Message asking for the email (with collect_email).
media_url?: string
A photo (JPG, PNG, GIF up to 8 MB), video (MP4, MOV, WebM up to 25 MB) or voice note (M4A, AAC, WAV up to 25 MB) to send just before the link, as a public https:// link: DMFast downloads and keeps a copy. "" removes it. Pro plan and up.
reminder_after_minutes?: integer
Send one reminder if they stop, after this many minutes (Pro plan and up): while DMFast waits for a follow or an email, or when they got the link and didn't open it. Skipped if they reply or tap. At most 1200 (Instagram's 24-hour window). 0 removes the reminder.
reminder_message?: string
The reminder's text (with reminder_after_minutes).
products?: object[]
Instead of one link: products sent as a swipeable carousel, each card with a photo, name, price and button. Only url is needed: missing details are read from the product page. link_message goes first, as text. Send [] to go back to a single link.
delete_auto_replyDelete an auto-replyMakes changesCan't be undone

Delete an auto-reply and its history for good. People in the middle of it get no further messages; emails it collected stay. To stop it for now instead, use update_auto_reply with active false. Confirm with the user first.

id: string
The auto-reply's id, from list_auto_replies.
reply_to_older_commentsReply to older commentsMakes changesReaches real people

Run a comment auto-reply on comments from the last 7 days that came in before it existed (or while it was off). DMFast DMs each matching commenter once, within a few minutes; people it already answered are skipped. Pro plan and up; not in the demo.

id: string
A comment auto-reply's id, from list_auto_replies.
list_recent_postsRecent postsReads only

The account's newest posts (Instagram posts and reels, or a Facebook Page's posts) with their ids and captions, which auto-replies watch each one, and the Instagram stories live now. Use post ids in post_ids for a comment auto-reply, and a story id as story_id for a story-reply one.

limit?: integer
How many posts (default 12).

Messages

list_conversationsList DM conversationsReads only

Recent DM conversations, newest first: who, their last message, and whether Instagram's 24-hour reply window is still open. Includes chats started by auto-replies.

search?: string
Only people whose username or name contains this.
limit?: integer
How many (default 20).
get_conversationRead a conversationReads only

The messages in one DM conversation (newest 50), what's known about the person, how long the 24-hour reply window has left, and any scheduled DMs.

conversation_id?: string
The conversation's id, from list_conversations.
username?: string
Or the person's Instagram username (on a Facebook Page: their name).
send_dmSend a DMMakes changesReaches real people

Send a DM in an existing conversation as the account (Instagram, or Messenger for a Facebook Page), or schedule it with send_at (Pro plan and up). Both only allow it within 24 hours of the person's last message; get_conversation shows the time left. Send only what the user asked for, and show them the text first.

conversation_id?: string
The conversation's id, from list_conversations.
username?: string
Or the person's Instagram username (on a Facebook Page: their name).
text: string
The message, at most 1,000 characters.
send_at?: string
Optional: when to send it, as an ISO 8601 time with a timezone, e.g. 2026-10-06T18:00:00Z. It must fall inside the 24-hour window.
set_ai_repliesAI repliesMakes changes

Set up DMFast's AI assistant: replies to DMs and to comments that no auto-reply matched (on or off), what it should know (products, prices, FAQs, links), its tone (or the creator's own style), voice-note replies in their own voice, and the goal it steers DM chats towards. It answers in the language people write in, and only says it's an AI assistant when someone asks. Each reply uses 1 AI credit, and a voice note 4 more. Turning replies on needs the Growth plan or higher. Fields you leave out keep their current value.

enabled?: boolean
true: the AI answers DMs no auto-reply matched. false: it stays quiet.
comments?: boolean
true: the AI also posts short public replies under comments that need an answer (60 an hour, one per person a day).
instructions?: string
What the AI should know and how to answer. Replaces the current instructions.
tone?: "friendly" | "professional" | "playful" | "mine"
friendly, professional, playful, or mine: the creator's own style (see style).
style?: string
How the creator writes, for tone mine: greetings, emoji, slang, sentence length, languages they mix. Quote their real words. Empty clears it. (The AI page can also learn it from their posts and DMs.)
voice_replies?: boolean
true: AI DM replies go out as voice notes in the creator's own voice. Needs a voice made on the AI page first (recorded there, with their consent).
goal?: "none" | "email" | "link" | "call" | "follow"
What DM chats steer towards: none (just answer), email (ask for their email; saved under Emails), link (send them to goal_url), call (book a call at goal_url) or follow.
goal_url?: string
The link for the link and call goals (https://…).

Results

get_resultsResultsReads only

How the auto-replies are doing over a period: people reached (different people), DMs sent, link clicks, unique clickers, CTR (unique clickers ÷ people reached) and emails, with each auto-reply's funnel (started → got the link → clicked) ranked by people reached. Periods beyond 30 days need the Pro plan.

range?: "7d" | "30d" | "90d" | "12m" | "all"
The period (default 30d). 90d, 12m and all need Pro.
days?: "7" | "30" | "90"
Older form of range: 7, 30 or 90 days.
list_emailsCollected emailsReads only

Emails people shared: in auto-replies that ask for one and in chats with the AI assistant (with their username and where it came from), in the bio page's sign-up box, and in the store (lead magnet sign-ups with phone numbers, and buyers). Newest first.

limit?: integer
How many (default 50).
since?: string
Only emails collected on or after this date (YYYY-MM-DD).

Research

research_accountResearch an Instagram accountMakes changesReaches real people

Look up any public Instagram account (from any connected account, Facebook Pages included): followers, engagement rate (and how it compares for that size), posts per week, average likes and comments, the posts with the most comments, and the words it asks people to comment ("Comment GUIDE") with how those posts did. Good for keyword ideas from similar creators. A fresh look-up uses one of the plan's monthly look-ups; accounts looked up in the last day are free.

username: string
Instagram username or profile link, e.g. hubspot or instagram.com/hubspot.

Viral Script Lab (add-on)

viral_lab_outliersViral Script Lab: Reels beating their usual numbersReads only

Viral Script Lab (paid add-on): the Reels on the creator's watchlist of public Instagram accounts that got at least 3x the plays of that account's usual Reel (the median of its recent Reels, pinned ones left out), biggest first, plus the watchlist itself. Accounts refresh daily. It's a fact about past numbers, not a prediction. Use viral_lab_remix on one to write the creator's own version.

limit?: number
How many Reels, 1-50 (default 20).
viral_lab_remixViral Script Lab: write your version of a ReelMakes changesReaches real people

Viral Script Lab (paid add-on): writes the creator's own version of a Reel (any public Reel link, an outlier from viral_lab_outliers, or a saved idea's script_id): 3 hook options, a timed script (what to say, the on-screen text and the shot per beat, timed to the words), a caption, a comment keyword with its call to action, and the comment auto-reply's public reply, opening DM and link message. It writes in the creator's voice: their voice profile (niche, tone, how they film) and, once they've read their Reels on the Viral Script Lab voice page, how they really talk (the hooks they open with, lines from their own Reels, words they repeat, their pace and language mix) and scripts they pasted. It keeps the idea and structure, never the original's words, and never invents numbers or results. Also returns a 5-point checklist (checks, not a prediction) and a link that opens the auto-reply prefilled in DMFast (nothing is sent until the creator saves it). Uses 1 of the 60 remixes each month (10 during the free trial). Don't promise the user views: say it shows what's working and helps them make their version.

reel_url?: string
A public Reel link, e.g. https://www.instagram.com/reel/ABC123/.
script_id?: string
A saved idea's id (from viral_lab_scripts), instead of reel_url.
angle?: string
Optional: what the creator's version should be about or offer, e.g. 'my free 7-day meal plan'.
language?: "en" | "es" | "pt-br" | "fr" | "de" | "it" | "nl" | "tr" | "ru" | "ar" | "hi" | "id" | "ja" | "ko" | "zh-tw" | "zh-cn"
Language to write the script in (default en).
viral_lab_scriptsViral Script Lab: saved ideas and scriptsReads only

Viral Script Lab (paid add-on): the creator's saved ideas and scripts, newest first, with their status (idea, scripted, recorded, scheduled, posted) and the day each is planned for. An idea may have no Reel behind it, only its topic. Pass script_id for one script in full (hooks, beats, caption, keyword, auto-reply messages and checklist).

script_id?: string
One script in full.
status?: "idea" | "scripted" | "recorded" | "scheduled" | "posted"
Only this status.
viral_lab_check_scriptViral Script Lab: check a script before filmingMakes changes

Viral Script Lab (paid add-on): checks a Reels script before the creator films it. Pass the script as text (any format; timings like [0-2s] make the timing checks exact, else they're estimated from the words) or a saved script's script_id from viral_lab_scripts. Returns the 5-point checklist (the hook ends by 2 seconds, 15 to 60 seconds long, a specific comment keyword, on-screen text in the first beat, the caption mentions the keyword: checks, not a prediction) and an AI review in the creator's voice: the 3 fixes to make first, each quoting its line, and 3 other hooks. Uses 1 of the 30 AI checks a day. Never present the result as predicted views, reach or a virality score.

script?: string
The script as text, up to 8000 characters.
script_id?: string
A saved script's id (from viral_lab_scripts), instead of script.

Store and calls

list_storeStore products and salesReads only

The account's store: digital products for sale (name, price, link, sales, revenue), whether payouts to the creator's bank are set up, and recent paid orders. Product links can go into an auto-reply's product carousel (create_auto_reply products).

create_store_productAdd a store productMakes changes

Add a digital product to the store, delivered as a private link (Notion page, Google Drive folder, course, community invite). Price 0 makes it a lead magnet: free for an email (and a phone number with ask_phone). It appears in the link in bio right away; payments are in INR via Razorpay. Files (PDFs etc.) are uploaded in the dashboard instead. Confirm the name and price with the user first.

title: string
Product name.
price_inr: number
Price in rupees, e.g. 499. 0 = free for an email (lead magnet).
ask_phone?: boolean
Free products only: also require a phone number.
delivery_url: string
The private https link buyers get after paying.
description?: string
What's inside and who it's for.
list_bookingsUpcoming 1-on-1 callsReads only

Upcoming booked calls (1-on-1 call products in the store): when, who, their email, phone and note, in the creator's time zone.

days?: integer
How far ahead (default 14 days).
cancel_bookingCancel a booked callMakes changesCan't be undoneReaches real people

Cancel an upcoming 1-on-1 call (booking_id from list_bookings). A paid call is refunded in full through Razorpay; the event leaves the creator's Google Calendar and the booker is emailed. Confirm with the user first: it can't be undone.

booking_id: string
From list_bookings.
refund_orderRefund a saleMakes changesCan't be undoneReaches real people

Refund a paid store order in full through Razorpay (order_id from list_store's recent sales). The buyer loses access, a call's booking is cancelled, and they're emailed. Confirm the order and amount with the user first: it can't be undone.

order_id: string
From list_store.

More

list_contactsContactsReads only

Everyone the account has talked to (people its auto-replies reached and people who wrote first), most recently active first: where each came from, their email if they shared one, whether they follow the account, and their link clicks.

search?: string
Part of a name, @username or email.
auto_reply_id?: string
Only people this auto-reply reached (an id from list_auto_replies), or "dm" for people who wrote first.
has_email?: boolean
Only people who shared an email.
follows?: boolean
Only people who follow the account (Instagram).
limit?: integer
How many (default 30).
list_ai_activityAI activityReads only

What DMFast's AI assistant did, newest first: DM and comment replies it sent, comments it chose not to answer (and why), auto-replies it started by meaning, with the credits each used, plus 30-day totals.

kind?: "dm_reply" | "comment_reply" | "intent" | "test"
Only this kind: dm_reply, comment_reply, intent or test.
limit?: integer
How many (default 20).
set_ice_breakersIce breakersMakes changesReaches real people

Set the account's ice breakers: up to 4 questions Instagram (in its phone app) or Messenger shows when someone opens a new chat with the account. When one is tapped, DMFast sends its reply (with an optional link button) or runs one of the account's DM auto-replies. Replaces the current ones; [] removes them. Confirm the questions and answers with the user first.

ice_breakers: object[]
create_courseCreate a courseMakes changes

Create a course in the store: modules of lessons (videos from YouTube, Vimeo, Loom or Google Drive, written lessons, links), sold on its own page like any product. Students get a private link to a course player that saves their progress. It's created hidden, for the creator to check in the dashboard, unless for_sale is true. Uploaded videos and files are added in the dashboard. Confirm the outline and price with the user first.

title: string
price_inr: number
Price in rupees; 0 = free for an email.
description?: string
What students learn and who it's for.
modules: object[]
for_sale?: boolean
true puts it on sale now; default false (hidden).
add_course_lessonsAdd lessons to a courseMakes changes

Add lessons to a course: at the end of a module (by its exact title), or in a new module with that title at the end. Videos are YouTube, Vimeo, Loom or Google Drive links.

course: string
The course's id (from list_store) or its page code.
module_title: string
An existing module's title, or a new module's.
lessons: object[]
get_courseCourse detailsReads only

A course's outline (modules and lessons, with which are free previews and which open later) and its students with their progress.

course: string
The course's id (from list_store) or its page code.
create_communityCreate a paid communityMakes changes

Sell access to one of the creator's Telegram groups or channels that DMFast's bot already runs (connected in the dashboard, Store → Communities on Telegram). Each buyer gets their own invite link; buying again extends their time; when it runs out the bot takes them out, after a reminder. Confirm the price and access period with the user first.

title: string
price_inr: number
Price per period in rupees; 0 = free for an email.
chat: string
The connected group or channel's name (or its id).
access: "1 month" | "3 months" | "6 months" | "1 year" | "for good"
What one purchase gives.
description?: string
get_communityCommunity membersReads only

A paid community's members: who's in the Telegram chat, who paid but hasn't joined, whose access ended, and until when each has access.

community: string
The community's id or page code (list_store shows them).
create_eventCreate an event or webinarMakes changes

Sell tickets to a live event: a webinar (online, with a join link only ticket holders see) or a meetup (in person, with a QR ticket checked in at the door). Free events take registrations for an email. Everyone registered gets the ticket by email with a calendar file, reminders a day and an hour before, and the replay once it's added. Confirm the date, time zone and price with the user first.

title: string
price_inr: number
Ticket price in rupees; 0 = free registration for an email.
starts_at: string
Local date and time in `timezone`, e.g. "2026-10-20 19:00".
timezone?: string
IANA zone, e.g. "Asia/Kolkata" (the default).
duration_min?: "30" | "45" | "60" | "90" | "120" | "180" | "240"
online?: boolean
true (default): a webinar or video call; false: in person.
join_url?: string
Online: the Zoom/Meet/YouTube Live link. Can be added later with update_event.
venue?: string
In person: the venue's name (required).
address?: string
capacity?: number
Seats; leave out for no limit.
description?: string
get_eventEvent attendeesReads only

An event's details (when, where, seats, join link, replay) and who's going: names, emails, ticket codes and who's checked in at the door.

event: string
The event's id or page code (list_store shows them).
update_eventSet an event's join or replay linkMakes changes

Adds or changes an online event's join link (shown on tickets and in reminders) or its replay link (emailed once to everyone with a ticket after the event; a different link is emailed again). Other changes are made in the dashboard, which also tells attendees.

event: string
The event's id or page code.
join_url?: string
replay_url?: string