DM Automations

A DM automation sends a direct message when someone comments on your post or sends you a message. Blotato supports DM automations on Instagram and Facebook Pages. Twitter/X, TikTok, LinkedIn, Pinterest, Threads, Bluesky, and YouTube are not supported at this time.

Eight endpoints let you manage automations and inspect their activity:

• List DM Automations — GET /v2/dm-automations

• Get DM Automation — GET /v2/dm-automations/:id

• Create DM Automation — POST /v2/dm-automations

• Update DM Automation — PATCH /v2/dm-automations/:id

• Delete DM Automation — DELETE /v2/dm-automations/:id

• List Runs — GET /v2/dm-automations/:id/runs

• List Logs — GET /v2/dm-automations/:id/logs

• Get Analytics — GET /v2/dm-automations/:id/analytics

For the web app walkthrough, see DM Automations.

Before You Start

Blotato needs permission to read comments and read and send messages on your account.

If you connected your account before comments, messaging, or (for Instagram) follow gating launched, reconnect it so Blotato has the new permissions.

• For Instagram, see Connect Instagram.

• For Facebook, see Connect Facebook.

For Instagram comment triggers, the connected Instagram account must own the post. DM automations do not run on posts where your account appears only as a collaborator. If you co-authored a post, create the automation under the Instagram account that originally published the post.

How an Automation Runs

1. Someone comments on your post or sends your account a message.

2. Blotato matches the event against every live automation on the account.

3. A match starts a run for each live automation.

4. If the automation has a follow gate or email gate, Blotato waits for the contact to complete it.

5. Blotato sends the DM, then calls the webhook if one is configured.

6. The run reaches completed, failed, expired, or superseded.

A comment trigger answers with a private reply to the comment. A message trigger answers with a standard DM.

Your own comments and the messages your account sends never start a run.

Comments on Instagram collaborator posts do not start a run for the collaborator account. Use the owner account for the automation.

Testing a Comment Trigger

Test from a different Instagram or Facebook account. A comment posted by the same account connected to the automation is skipped, even when its text matches a trigger keyword.

Optional Steps

Set followGate, emailGate, or webhook to extend the run. Blotato runs the steps in a fixed order:

1. Follow gate (followGate, Instagram only). Sends the gate message with a confirm button, waits up to 1 hour for a reply, then checks whether the contact follows the account. A contact who does not follow gets the gate message again.

2. Email gate (emailGate). Sends the gate message, waits up to 1 hour for a reply, and reads the first email address out of it. A reply holding no email address returns the gate message. A match saves to the contact.

3. Your message (dmMessage plus buttons).

4. Webhook (webhook). Calls your endpoint after the message sends.

A run waiting on a gate reaches expired when the contact never answers inside the window, and superseded when a newer run starts waiting on the same contact.

While a run waits on a contact's reply, their next DM resumes the waiting run instead of starting a new run. A button tap never starts a run.

---

List DM Automations

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /dm-automations

Method: GET

Description

Returns your DM automations, ordered by creation time (most recent first). Use cursor-based pagination.

Query Parameters

Field	Type	Required	Description
limit	integer	No	Maximum automations to return (1-250). Default 50.
cursor	string	No	Cursor from a previous response. Pass it to fetch the next page.

Response

Status Code: 200 OK

{
  "items": [
    {
      "id": "flow_abc123",
      "accountId": "98434",
      "name": "Auto-DM links from comments",
      "platform": "instagram",
      "target": { "targetType": "instagram" },
      "trigger": {
        "type": "comment-received",
        "keywords": ["price", "link"],
        "postId": "post_xyz789",
        "isActive": true
      },
      "dmMessage": "Thanks for the interest! Tap below for the link.",
      "buttons": [
        { "type": "url", "title": "View link", "url": "https://blotato.com" }
      ],
      "emailGate": { "message": "Reply with your email and I will send it over." },
      "followGate": {
        "message": "Follow this account, then tap below.",
        "buttonTitle": "I'm following"
      },
      "webhook": {
        "method": "POST",
        "url": "https://example.com/blotato-webhook",
        "headers": { "x-source": "blotato" }
      },
      "isActive": true,
      "publishedVersionId": "ver_001",
      "createdAt": "2026-08-01T12:00:00Z",
      "updatedAt": "2026-08-02T09:30:00Z"
    }
  ],
  "cursor": "eyJz..."
}

Field	Type	Description
items	array	List of automations. See DM Automation Object.
cursor	string	Cursor for the next page. Absent when there are no more automations.

---

Get DM Automation

Endpoint

URL: /dm-automations/:id

Method: GET

Description

Fetches a single automation by its Blotato ID, including its trigger and the message it sends.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Blotato ID of the automation.

Response

Status Code: 200 OK

{ "flow": { "id": "flow_abc123", "...": "..." } }

The flow object is a DM Automation Object.

---

Create DM Automation

Endpoint

URL: /dm-automations

Method: POST

Description

Creates a DM automation. When its trigger fires, the automation sends one direct message: text plus up to 3 link buttons. You can gate the message behind an Instagram follow check, ask for an email address first, or call a webhook after the message sends.

• Set followGate (Instagram only) to gate the message behind a follow check.

• Set emailGate to gate it behind the contact replying with an email address.

• Set webhook to call an external endpoint once the message sends.

An automation is created as a draft unless you pass isActive: true.

Request Body

{
  "accountId": "98434",
  "platform": "instagram",
  "target": { "targetType": "instagram" },
  "name": "Auto-DM links from comments",
  "trigger": {
    "type": "comment-received",
    "keywords": ["price", "link"],
    "postId": null
  },
  "dmMessage": "Thanks for the interest! Tap below for the link.",
  "buttons": [
    { "type": "url", "title": "View link", "url": "https://blotato.com" }
  ],
  "followGate": {
    "message": "Follow the account, then tap below.",
    "buttonTitle": "I'm following"
  },
  "emailGate": {
    "message": "Reply with your email and I'll send the link."
  },
  "webhook": {
    "method": "POST",
    "url": "https://example.com/hooks/leads",
    "headers": { "X-Api-Key": "secret" }
  },
  "isActive": true
}

Field	Type	Required	Description
accountId	string	Yes	Blotato ID of the connected account the automation runs on.
platform	string	Yes	instagram or facebook.
target	object	Yes	Where the automation listens and sends. See Target.
name	string	Yes	Automation label, 1-60 characters.
dmMessage	string	Yes	Message text, 1-640 characters.
buttons	array	Yes	Up to 3 link buttons. Pass [] for a plain-text message. See Button Object.
trigger	object or null	No	The event the automation listens for. See Trigger Object.
followGate	object or null	No	Instagram only. Holds the message back until the contact follows the account. See Follow Gate Object.
emailGate	object or null	No	Holds the message back until the contact replies with an email address. See Email Gate Object.
webhook	object or null	No	Endpoint Blotato calls once the message sends. See Webhook Object.
isActive	boolean	No	true publishes the automation immediately. Default false.

An automation needs a trigger, a non-empty dmMessage of 640 characters or fewer, and a valid http(s) URL on every button before it goes live. A gate you set needs its own message, and a webhook you set needs a valid http(s) url.

Response

Status Code: 201 Created

{ "flow": { "id": "flow_abc123", "isActive": true, "...": "..." } }

---

Update DM Automation

Endpoint

URL: /dm-automations/:id

Method: PATCH

Description

Updates an automation. Each field present in the patch replaces that field. Omitted fields stay unchanged. Pass null for trigger, followGate, emailGate, or webhook to remove it.

The connected account, platform, and target are fixed at creation. To run on a different account, create a new automation.

Request Body

The patch is nested under a patch key.

{
  "patch": {
    "dmMessage": "New reply text",
    "buttons": [],
    "isActive": true
  }
}

Field	Type	Required	Description
name	string	No	New automation label, 1-60 characters.
trigger	object or null	No	Replaces the trigger. See Trigger Object.
dmMessage	string	No	Replaces the message text, 1-640 characters.
buttons	array	No	Replaces the buttons. Pass [] to remove every button.
followGate	object or null	No	Replaces the follow gate. Pass null to remove it. Instagram only. See Follow Gate Object.
emailGate	object or null	No	Replaces the email gate. Pass null to remove it. See Email Gate Object.
webhook	object or null	No	Replaces the webhook. Pass null to remove it. See Webhook Object.
isActive	boolean	No	true publishes the automation. false moves it to draft. Omit to keep the current state.

Content changes to a live automation publish as soon as the request succeeds. Content changes to a draft stay saved until you pass isActive: true.

A live automation needs a trigger. To clear the trigger, pass isActive: false in the same request.

Response

Status Code: 200 OK

{ "flow": { "id": "flow_abc123", "...": "..." } }

---

Delete DM Automation

Endpoint

URL: /dm-automations/:id

Method: DELETE

Description

Archives an automation. Its trigger stops listening and the automation stops firing. Runs already in flight finish.

Response

Status Code: 200 OK

Returns the archived DM Automation Object.

---

List Runs

Endpoint

URL: /dm-automations/:id/runs

Method: GET

Description

Returns the execution runs of one automation, ordered by start time (most recent first). A run is one execution: one comment or message matched the trigger, and Blotato acted on it.

Use this endpoint to check whether an automation fires and why a reply did not go out.

Query Parameters

Field	Type	Required	Description
limit	integer	No	Maximum runs to return (1-250). Default 50.
cursor	string	No	Cursor from a previous response. Pass it to fetch the next page.

Response

Status Code: 200 OK

{
  "items": [
    {
      "id": "run_abc123",
      "contactId": "1784000000",
      "platform": "instagram",
      "status": "failed",
      "error": { "code": 20102, "message": "Messaging window has expired" },
      "createdAt": "2026-08-02T09:30:00Z",
      "updatedAt": "2026-08-02T09:30:04Z"
    }
  ],
  "cursor": "eyJz..."
}

See Run Object.

---

List Logs

Endpoint

URL: /dm-automations/:id/logs

Method: GET

Description

Returns the execution logs written as an automation's runs progress, ordered by creation time (most recent first). Pass flowRunId to narrow the logs to a single run.

Query Parameters

Field	Type	Required	Description
flowRunId	string	No	Only return logs belonging to this run. Omit to return logs across every run.
limit	integer	No	Maximum logs to return (1-250). Default 50.
cursor	string	No	Cursor from a previous response. Pass it to fetch the next page.

Response

Status Code: 200 OK

{
  "items": [
    {
      "id": "log_abc123",
      "flowRunId": "run_abc123",
      "nodeId": "nd_9fJ2",
      "level": "info",
      "message": "Queued message for send",
      "context": { "messageId": "msg_abc123" },
      "createdAt": "2026-08-02T09:30:01Z"
    }
  ],
  "cursor": "eyJz..."
}

See Log Object.

---

Get Analytics

Endpoint

URL: /dm-automations/:id/analytics

Method: GET

Description

Returns all-time run totals for one automation.

Response

Status Code: 200 OK

{
  "analytics": {
    "triggered": 412,
    "completed": 398,
    "failed": 9
  }
}

Field	Type	Description
triggered	integer	Runs started by a matching comment or message.
completed	integer	Runs where the DM settled as sent.
failed	integer	Runs where the DM did not send.

A run stays open until its message settles, so completed plus failed is sometimes lower than triggered.

---

DM Automation Object

Field	Type	Description
id	string	Blotato automation ID.
accountId	string	ID of the connected account the automation runs on.
name	string	Automation label.
platform	string	instagram or facebook.
target	object	See Target.
trigger	object	The event the automation listens for. Absent when no trigger is set. See Trigger Object.
dmMessage	string	Message text sent when the trigger fires.
buttons	array	Link buttons attached to the message. See Button Object.
followGate	object	Follow gate on the automation. Absent when no follow gate is set. See Follow Gate Object.
emailGate	object	Email gate on the automation. Absent when no email gate is set. See Email Gate Object.
webhook	object	Webhook on the automation. Absent when no webhook is set. See Webhook Object.
isActive	boolean	true when the automation is live and listening.
publishedVersionId	string or null	ID of the published version. null for a draft.
createdAt	string	ISO 8601 timestamp when the automation was created.
updatedAt	string	ISO 8601 timestamp of the most recent edit.

Target

Field	Type	Required	Description
targetType	string	Yes	instagram or facebook.
pageId	string	For Facebook	ID of the Facebook Page, from subaccounts. Required when targetType is facebook.

Trigger Object

Field	Type	Required	Description
type	string	Yes	comment-received or message-received.
keywords	array	Yes	Words or phrases the comment or message must contain. Pass [] to fire on every comment or message.
postId	string or null	No	Comment triggers only. Blotato ID of the post to watch. null watches every post and reel on the account.
isActive	boolean	No	false stops the trigger listening while the automation stays published. Default true.

Keyword matching ignores case, matches whole words, and tolerates line breaks inside a multi-word keyword. A comment or message fires the automation when it contains any one of the keywords.

postId is a Blotato post ID, so per-post targeting works on posts published through Blotato. Get it from List Published Posts. To act on a post published outside Blotato, leave postId as null and rely on keywords.

Button Object

Field	Type	Required	Description
type	string	Yes	url. Link buttons are the only type buttons accepts.
title	string	Yes	Button label, up to 20 characters.
url	string	Yes to publish	http(s) URL the button opens.

To send quick-reply chips or postback buttons, use Send Message.

Instagram renders buttons in the Instagram mobile app only. A recipient reading the DM on instagram.com in a desktop browser sees the message text with no buttons. To work around this issue, you can add the URL directly to the message text, and Instagram will render it as a clickable link. Set buttons or put a URL inside dmMessage, not both, since a message carrying both leaves the URL unclickable on desktop. For a desktop audience, pass buttons: [] and put the URL in dmMessage. See Instagram Limitations.

Follow Gate Object

Instagram only. Holds dmMessage back until the contact follows the account.

Field	Type	Required	Description
message	string	Yes	Gate message text, 1-640 characters. Blotato sends it with a confirm button under it.
buttonTitle	string	No	Label on the confirm button, up to 20 characters. Default I'm following.

Blotato sends the gate message, waits up to 1 hour for a reply, then reads the contact's follower status. A contact who follows receives dmMessage. A contact who does not receives the gate message again.

• The gate message always goes first. Instagram grants access to follower status once the contact opens a DM thread with the account, so the gate message precedes the check.

• An unknown follower status sends dmMessage. Instagram withholds follower status for a contact who never granted profile access, and Blotato proceeds rather than blocking them.

• A confirmed follow lasts 30 days. Blotato reuses the result for 30 days. A negative result is never reused.

• The confirm button is a postback button Blotato manages. You set its label only. See Instagram Limitations.

• Any reply advances the gate. Blotato runs the follower check on the contact's next DM, whatever it says. The tap is a shortcut, not a requirement.

• The account needs a button-tap subscription. Blotato subscribes the account at connect time. An account connected before DM automations and follow gating landed does not reliably receive a tap, and runs reach expired. Reconnect the account to fix it.

• Instagram renders the confirm button in the mobile app only. A contact reading on instagram.com in a desktop browser sees the gate message with nothing to tap. Write message to ask for a typed reply, for example "Reply FOLLOWING once you have", so a desktop audience still advances.

Email Gate Object

Holds dmMessage back until the contact replies with an email address.

Field	Type	Required	Description
message	string	Yes	Gate message text, 1-640 characters.

Blotato sends the gate message, waits up to 1 hour for a reply, and reads the first email address out of it. A reply holding no email address returns the gate message and Blotato waits again. A match saves to the contact and dmMessage sends.

Blotato checks the shape of the address, not whether the mailbox exists. Read a captured address through the Webhook Object.

Webhook Object

Endpoint Blotato calls after dmMessage sends.

Field	Type	Required	Description
method	string	Yes	GET, POST, PUT, PATCH, or DELETE.
url	string	Yes	Public http(s) endpoint, 1-2048 characters.
headers	object	No	String keys and string values sent with the request, for example an API key.

Every method except GET carries a JSON body with Content-Type: application/json. GET carries no body.

With emailGate set on the automation:

{ "email": "[e-mail]" }

With no emailGate:

{}

Rule	Behavior
Address	The host must resolve to a public address. Private, loopback, link-local, and cloud metadata ranges return error code 20304.
Protocol	http and https only.
Redirects	Blotato does not follow them. Point the automation at the final URL.
Timeout	10 seconds.
Response body	Blotato reads the first 16 KB.
Error response	A non-2xx status gets logged with its status, and the run still completes.
Failure	A blocked address, a DNS failure, or a timeout fails the run with error code 20304.
Headers	Redacted from run logs, so a key never lands in a log entry.

This webhook is separate from the webhook publish target, which sends post content to your endpoint at publish time.

Run Object

Field	Type	Description
id	string	Blotato run ID. Pass it as flowRunId to List Logs.
contactId	string	Social platform ID of the person who triggered the run.
platform	string	instagram or facebook.
status	string	See Run Status Values.
error	object	Set only when status is failed. Holds code and message.
createdAt	string	ISO 8601 timestamp when the run started.
updatedAt	string	ISO 8601 timestamp of the most recent run update.

Run Status Values

Status	Meaning
running	Executing a step.
waiting	Waiting for the DM to settle, or waiting on the contact to answer a gate.
completed	The DM sent.
expired	The contact never answered a gate inside the 1-hour window. Nothing further sent.
superseded	A newer run started waiting on the same contact, so this one stopped.
failed	The DM did not send. Read error.
expired	The run waited too long for the contact to complete a gate.
superseded	A newer matching event replaced this run.

Log Object

Field	Type	Description
id	string	Blotato log ID.
flowRunId	string	ID of the run this log belongs to.
nodeId	string or null	ID of the step the log came from. null for run-level entries.
level	string	info, warning, or error.
message	string	Description of the step.
context	object	Step-specific details, for example the message ID.
createdAt	string	ISO 8601 timestamp when the log was written.

---

Platform Rules

Instagram and Facebook set these rules, not Blotato. A message outside an allowed window reaches status failed on the run.

• Comment trigger. Blotato answers with a private reply to the comment. Both platforms allow one private reply per comment, within 7 days of the comment. A comment that already received a private reply, through Blotato or another tool, rejects the second reply.

• Message trigger. Blotato replies within 24 hours of the person's last message.

• No cold outreach. An automation only answers people who comment or message first.

• A reply during a gate continues the run. While a run waits on a contact's answer, their next DM resumes the waiting run instead of starting a new one. A button tap never starts a run.

See Messaging Windows.

Active Contacts

Every DM an automation sends counts toward your plan's monthly active-contacts limit, the same as a message sent through Send Message. Reaching the same person twice in a month counts once.

See Active Contacts.

---

Errors

Status	Reason
404	The automation was not found. Returned by Get DM Automation and Delete DM Automation only.
422	The automation is invalid for publishing (error code 20303), or the connected account is missing (error code 5000). Setting followGate on a facebook automation returns 20303.
500	Unexpected server error.

A webhook failure surfaces on the run, not on the request. A blocked address, a DNS failure, or a timeout fails the run with error code 20304. See Error Reference.

Rate Limits

Endpoint	Limit
GET /dm-automations	60 / min
GET /dm-automations/:id	60 / min
POST /dm-automations	30 / min
PATCH /dm-automations/:id	30 / min
DELETE /dm-automations/:id	30 / min
GET /dm-automations/:id/runs	60 / min
GET /dm-automations/:id/logs	60 / min
GET /dm-automations/:id/analytics	60 / min