The Instagram DM automation API.A keyword in, a conversation out.
Breakreach's DM automation API creates flows on an Instagram account with POST /v1/dm-automations: when someone DMs a keyword, mentions the account in a story, replies to a story or opens a ref link, Breakreach answers in their DMs and walks the steps you set (messages with a link button or choices, waits, a follow check, a handoff to your team), inside Meta's 24-hour window.
Checked against the API code on October 7, 2026. Breakreach is our product.
DM automations API endpoints5 endpoints, one API key.
- GET
/v1/dm-automationsThe workspace's automations with their stats and, for ref links, the link to share - POST
/v1/dm-automationsCreate one; subscribes the account to Meta's message webhooks - PATCH
/v1/dm-automations/:idChange the trigger or the steps, or pause with active false - DELETE
/v1/dm-automations/:idDelete it with its runs; people in the flow stop - GET
/v1/dm-automations/:id/runsEach person who went through it, every step, and how it ended
Base URL https://api.breakreach.com. Every call sends your key as Authorization: Bearer br_…; errors answer { "error": "…" } with a 4xx or 5xx status. Every parameter is in the OpenAPI spec.
What an automation takes
| Field | Type | What it does |
|---|---|---|
accountId | string, required on create | The Instagram account (or Facebook Page), from GET /v1/accounts |
trigger.type | keyword, any_message, story_mention, story_reply or ref | What starts it |
trigger.keywords | string[] | Up to 20, for keyword (required) and story_reply (optional); case and accents ignored |
trigger.ref | string | For ref: the code in ig.me/m/<username>?ref=<code> |
steps | step[], required on create | message, wait, condition or handoff; a step that branches is the last of its list |
reentry | once or always | once (default): a person goes through it once; always: again after cooldownHours |
active | boolean | false pauses it and lets the people in the flow go |
Which networks it coversChecked against the code, not a feature list.
| Network | DM automations | Triggers |
|---|---|---|
 Instagram | Yes, Professional accounts | Keyword, any DM, story mention, story reply, ref link |
 Facebook Pages (Messenger) | Waiting on Meta's review | Keyword, any DM, ref link |
   X, TikTok, LinkedIn, WhatsApp | No | Not supported |
How does a DM start a flow?Meta's webhook, then the steps.
Creating an automation subscribes the account to Meta's message webhooks. Every DM, quick reply tap, story mention, story reply and ref link reaches Breakreach within seconds. If the person isn't already in a flow on that account, the matching automation starts a run for them: a ref link goes to its automation, a story mention or reply to theirs, then keywords (exact before contains), then any DM.
A run walks the steps: it sends a message, waits, waits for a tap or a reply, checks a condition and follows a branch, until the flow ends or hands off. Each step lands in the run's log, which GET /v1/dm-automations/:id/runs returns.
Which steps can a flow have?
| Step | What it does |
|---|---|
| message | Text up to 1,000 bytes with {username} and {first_name}; a link button (clicks counted) or up to 13 quick-reply choices, each with its own branch |
| wait | Up to 23 hours, so the next message still lands inside the 24-hour window |
| condition | replied, keyword (in their reply), clicked (an earlier link button), each waited for up to withinMinutes; follows (Instagram), checked at once |
| handoff | Flags the conversation in the Breakreach Inbox for a person on the team, with a note, and ends the run |
Meta never reports a tap on a link button, so the button points to api.breakreach.com/l/…, which counts the click and redirects. Link previews and bots are redirected without being counted.
How does it stay inside Meta's rules?Replies only, within 24 hours, humans first.
Every run starts from something the person did, and nothing is sent first. Before each message, Breakreach checks that their last message is less than 24 hours old; if not, the run ends as window_closed and the message isn't sent. Each person is in one flow at a time per account.
When someone on your team answers by hand, in the Instagram app, Business Suite or the Breakreach Inbox, the person's run stops, and automations leave them alone for 12 hours. A conversation handed off triggers nothing until someone marks it done in the Inbox.
Which webhook events come with it?Five, signed like every Breakreach webhook.
dm_automation.started fires when a person enters a flow, dm_automation.handoff when a flow hands them to your team (the place to open a ticket or ping Slack), dm_automation.finished when a run ends for any reason, and dm_automation.failed when Meta refuses a message for good. message.received fires for every DM on an account with an automation; pick it on purpose, it's a firehose.
What limits apply?
| Limit | Value | Set by |
|---|---|---|
| Reply window | 24 hours after the person's last message | Meta |
| Message text | 1,000 bytes; 640 characters with a link button | |
| Choices per message | 13, labels up to 20 characters | Meta |
| Steps per automation | 40, branches 6 levels deep | Breakreach |
| Longest wait | 23 hours | Breakreach |
| Automations per workspace | 100 | Breakreach |
| Runs kept | 90 days | Breakreach |
Transient errors (Meta rate limits, a 5xx) are retried twice. A refusal for good, such as a person who blocked the account, ends the run as failed with the reason.
What does the DM automation API cost?
The Developer plan costs $5 a month per connected account up to 20, $3 from 21 to 100 and $2 after that, never per call or per post. The API also comes with every regular plan, from Starter at $29 a month for 5 accounts. Messages and runs aren't counted. An automation needs an active plan or trial on the workspace.
For AI agentsAgents get the same calls.As MCP tools, no code to write.
From an agent: “when people DM PRICE, ask if it's for a team, send the pricing page to individuals and hand teams to me” becomes one create_dm_automation call in Claude Code, Codex or ChatGPT.
list_dm_automationsThe automations and their stats, and an automation's latest runscreate_dm_automation“When someone DMs GUIDE, send the guide to followers and ask the others to follow first”update_dm_automationNew keywords, a new step, or pausedelete_dm_automationRemoves an automation and its runs
What the dm automations API doesn't do yetSo you know before you build.
- Message people first: every run answers something the person did
- Send after 24 hours: Breakreach doesn't use Meta's human agent tag
- Images, carousels or voice notes in a step: text, a link button or choices
- WhatsApp, X, TikTok or LinkedIn DMs
- Continue a Comment to DM private reply into a flow (planned)
The rest of the API (webhooks, workspaces per customer, connect links for your users, the price per connected account) is on the developers page.
The rest of the API
Questions, answered.
Short answers about the DM automations API.
Yes. Meta's Instagram API sends messages and quick replies within 24 hours of the person's last message. Breakreach's API wraps it in automations: POST /v1/dm-automations with a trigger and steps, and every matching DM starts the flow.
No. Breakreach's Meta app holds the approved messaging permission and receives the webhooks. Creating an automation subscribes the account; your code creates automations and, if you want, listens to the dm_automation webhooks.
Yes, on Instagram: a condition step with check follows asks Instagram whether the person follows the account, and branches. Pair the no branch with a choice like “I followed” that checks again.
The person's run stops at once, whether you answer in the Instagram app, Business Suite or the Breakreach Inbox, and automations leave them alone for 12 hours.
Not by default: reentry once runs it one time per person. With reentry always, they can start it again after cooldownHours (24 by default).
Your first call is five minutes away.From $5 a month per account.
Billed per connected account. Cancel anytime.