# ManyChat-style automations

Ref-link entry points, comment-to-DM funnels with buttons, story-mention replies, repeat rules and handover to another inbox app, on Instagram and Facebook.

Build ManyChat-style automations on Instagram and Facebook from [Workflows](/products/automations/workflows) (a graph that runs on one messaging account when its trigger fires) and [comment automations](/comment-automations/create-comment-automation) (a keyword rule answering a comment or story with a DM).

## Before you start

An API key, the `accountId` of a connected Instagram or Facebook account in a profile ([connecting accounts](/guides/connecting-accounts)), and its inbox ([workflows need inbox access](/products/automations/workflows#workflows-need-inbox-access)).

| You want | Use |
|---|---|
| A link or QR code that starts a flow | A workflow with a [`referral` trigger](#ref-link-to-a-workflow) |
| An ad click that starts a flow | `workflowId` on [messaging ads](/platforms/meta-ads/messaging-ads#start-a-workflow-from-the-ad) and [boosts](/platforms/meta-ads/boost#a-messaging-boost-can-start-a-workflow) |
| Comment a keyword, get a DM | A [comment automation](#comment-to-dm-with-buttons), or a workflow with a `comment` trigger |
| Reply to story mentions | A [`story_mention`](#story-mentions) automation or workflow trigger |
| DM once per person, or on every comment | [`repeatPolicy`](#repeat-rules) |
| Let a human take over in another app | [Thread control](#handover-with-another-app) |
| Welcome screen, FAQ prompts, menu | [Greeting, ice breakers and persistent menu](#welcome-screen-and-menu) |

## Ref link to a workflow

An ig.me or m.me link with a `ref` parameter sends a referral that starts a `referral` workflow. This one answers the `spring-sale` link with buttons, waits for the tap and tags the contact:

```bash
curl -X POST "https://zernio.com/api/v1/workflows" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "platform": "instagram",
    "name": "Spring sale link",
    "nodes": [
      { "id": "n_trigger", "type": "trigger", "config": { "triggerType": "referral", "referral": { "ref": "spring-sale", "matchType": "exact" }, "cooldownHours": 24 } },
      { "id": "n_offer", "type": "send_message", "config": { "messageType": "text", "text": "Hi {{contact.name}}, here is 20% off everything this week.", "buttons": [ { "type": "url", "title": "Shop now", "url": "https://example.com/spring" }, { "type": "postback", "title": "Remind me later" } ] } },
      { "id": "n_wait", "type": "wait_for_reply", "config": { "timeoutMinutes": 1440, "saveAs": "answer" } },
      { "id": "n_tag", "type": "add_tag", "config": { "tag": "spring-sale" } },
      { "id": "n_end", "type": "end" }
    ],
    "edges": [
      { "id": "e1", "source": "n_trigger", "target": "n_offer" },
      { "id": "e2", "source": "n_offer", "target": "n_wait" },
      { "id": "e3", "source": "n_wait", "target": "n_tag", "sourceHandle": "reply" },
      { "id": "e4", "source": "n_wait", "target": "n_end", "sourceHandle": "timeout" },
      { "id": "e5", "source": "n_tag", "target": "n_end" }
    ]
  }'
```

Activate it with `POST /v1/workflows/{workflowId}/activate`.

- **`referral.ref`** with `matchType` `exact`, `prefix` or `any` (default) picks the links, so one account serves many campaigns.
- **Variables:** `{{referral.ref}}`, `{{referral.source}}`, `{{referral.type}}` and, for an ad click, `{{referral.adId}}`.
- **Postback without `payload`** gets `zernio:workflow:<this workflow id>`. Tapping "Remind me later" answers the pending `wait_for_reply`; `{{postback.title}}` is `Remind me later`.
- **`cooldownHours`** stops the same contact restarting it for a day.
- **Ads:** it also fires on click-to-message ads (Instagram, Facebook, click-to-WhatsApp). To pin an ad to one workflow regardless of triggers, set `workflowId` on the ad ([messaging ads](/platforms/meta-ads/messaging-ads#start-a-workflow-from-the-ad)).

## Comment to DM with buttons

### With a comment-triggered workflow

A `triggerType: "comment"` workflow starts with no conversation. The `send_message` right after the trigger is the private reply; the run continues in the conversation it opens.

Instagram refuses buttons, cards and attachments in a private reply to a non-follower, spending the comment's single private reply ([Send private reply](/comments/send-private-reply-to-comment)). So open with plain text, wait, then send buttons:

```json
{
  "nodes": [
    { "id": "n_trigger", "type": "trigger", "config": { "triggerType": "comment", "comment": { "keywords": ["guide"], "matchType": "contains", "platformPostId": "17912345678901234" } } },
    { "id": "n_open", "type": "send_message", "config": { "messageType": "text", "text": "Hey! Reply YES and I will send you the guide." } },
    { "id": "n_wait", "type": "wait_for_reply", "config": { "timeoutMinutes": 1440, "saveAs": "answer" } },
    { "id": "n_link", "type": "send_message", "config": { "messageType": "text", "text": "Here it is. Want the video walkthrough too?", "buttons": [ { "type": "url", "title": "Get the guide", "url": "https://example.com/guide.pdf" }, { "type": "postback", "title": "Send the video", "workflowId": "66d4a1b2c3e4f5a6b7c8d9e7" } ] } },
    { "id": "n_end", "type": "end" }
  ],
  "edges": [
    { "id": "e1", "source": "n_trigger", "target": "n_open" },
    { "id": "e2", "source": "n_open", "target": "n_wait" },
    { "id": "e3", "source": "n_wait", "target": "n_link", "sourceHandle": "reply" },
    { "id": "e4", "source": "n_wait", "target": "n_end", "sourceHandle": "timeout" },
    { "id": "e5", "source": "n_link", "target": "n_end" }
  ]
}
```

- **`comment: { keywords, matchType, platformPostId }`** filters by keyword and scopes to one post.
- **A button with `workflowId`** ("Send the video") starts that follow-up workflow instead of this one.
- **Variables:** `{{comment.text}}`, `{{comment.id}}` and `{{comment.platformPostId}}` hold the comment for the whole run.

### With a comment automation

No graph, plus a public reply, link tracking, follower rules and per-comment actions.

A postback `payload` of `zernio:workflow:<workflowId>` hands off to that workflow (active on the same account and profile), skipping its keyword or first-message condition.

```bash
curl -X POST "https://zernio.com/api/v1/comment-automations" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "name": "Guide giveaway",
    "platformPostId": "17912345678901234",
    "keywords": ["guide"],
    "matchMode": "word",
    "dmMessage": "Hey {{first_name}}! Tap below and I will send the guide.",
    "buttons": [ { "type": "postback", "title": "Send it", "payload": "zernio:workflow:66d4a1b2c3e4f5a6b7c8d9e7" } ],
    "commentReply": "Check your DMs, {{first_name}}!",
    "publicReplyPolicy": "always",
    "actions": { "likeComment": true }
  }'
```

| Field | What it does |
|---|---|
| `{{first_name}}`, `{{name}}`, `{{username}}` | From the commenter, in `dmMessage`, `commentReply`, their variations and button titles. Missing values become an empty string. |
| `publicReplyPolicy` | `publicReplyPolicy: "always"` posts `commentReply` whatever the audience rule, dedupe or DM outcome. Default `after_dm`: only after a successful DM. |
| `actions.likeComment`, `actions.hideComment` | Like or hide the matched comment, never blocking the DM. Skips are explained in the log's `likeSkipped` or `hideSkipped`. Instagram liking is in limited release ([Instagram comments](/platforms/instagram/inbox#comments)). |
| `quickReplies` | Up to 13 chips, not with `buttons` or `template`. Not rendered in Message Requests (where a first DM to a cold commenter lands): use buttons for first contact. |
| `dmMedia` | Image, video, audio clip or file, sent as a second message. |
| `isActive: false` | Creates the automation paused. |

[List automation logs](/comment-automations/list-comment-automation-logs) shows each attempt with `status`, `publicReplyPostedAt`, `gateButtonStatus` and link `clickCount`.

## Story mentions

When someone mentions the account in their Instagram story:

- **Comment automation** with `trigger: "story_mention"` sends `dmMessage` as a DM. Mentions carry no text or story id, so leave `keywords` empty and omit `platformPostId`.
- **Workflow** with `triggerType: "story_mention"` runs a full graph, with the story in `{{story.url}}`.
- **Story replies** arrive as messages. They start `inbound_message` workflows (with `{{story.id}}` and `{{story.url}}` set) and `story_reply` automations.
- **Live broadcasts:** keyword comments use the `live_comment` trigger, answered with a private reply while live.

## Repeat rules

`repeatPolicy` decides whether one person can get an automation's DM more than once:

```json
{ "repeatPolicy": { "mode": "every_comment", "cooldownHours": 24 } }
```

- **`once`** (default): one DM per person per door, ever. On reply-only platforms, one public reply per person per automation.
- **`every_comment`**: every new matching comment is eligible again; one comment is still answered at most once. `cooldownHours` (every_comment only) skips a repeat to the same person within that many hours.
- **`dedupeSameTextHours`** (across automations) skips the DM when the recipient got identical text (after personalisation) from this account within that many hours.
- **Workflows:** `cooldownHours` (1 to 720) on an `inbound_message`, `referral`, `story_mention`, `reaction` or `whatsapp_event` trigger blocks restarts by the same contact in the window.

## Handover with another app

Meta's conversation routing replaced the Handover Protocol on Instagram in October 2025. It lets a human work a thread in another app while Zernio steps aside: Page Inbox is `263902037430900`, the Instagram Inbox is `1217981644879628`.

Pass the thread when a human is needed:

```bash
curl -X POST "https://zernio.com/api/v1/inbox/conversations/66c3d2ae7b4f6c8d0e1f2a3b/thread-control" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "66b2e19d8c3f5a7e9d0b1c2d", "action": "pass", "targetAppId": "263902037430900", "metadata": "Customer asked for a human" }'
```

```json
{ "success": true, "control": { "owner": "other", "ownerAppId": "263902037430900" } }
```

While the other app owns the thread:

- **Inbound messages** still arrive on [`message.received`](/webhooks/inbox/message-received), flagged `metadata.standby: true`. No workflow or comment automation runs on them.
- **Sends** answer `409` `not_thread_owner` (see [If it fails](#if-it-fails)).
- **[`conversation.control_changed`](/webhooks/inbox/conversation-control-changed)** fires when Meta tells Zernio a thread was passed to it or taken from it, with `control.owner`, `control.previousOwner` and `control.ownerAppId`. Your own thread-control calls and `release` do not fire it.

Get it back with:

- **`action: "take"`**: Facebook Pages and Instagram accounts connected with Facebook Login. Meta accepts it only when the account has a default app set in conversation routing and has allowed Zernio to take control of conversations; otherwise it answers code `27`. A send refused with `not_thread_owner` already tries this once.
- **`"request"`**: asks the owner. Nothing changes until the owner passes it. Not available with Instagram Login.
- **`"release"`**: the thread goes idle and the account's default app answers next.

On Instagram Login connections only the owner can give the thread back. Making Zernio the default app in the account's conversation routing settings avoids the problem.

**Handoff node.** A `handoff` node ends the run as `exited` and flags the conversation for a human in Zernio. To pass the Meta thread too, call thread-control when [`workflow.run.completed`](/webhooks/inbox/workflow-run-completed) arrives with `execution.status: "exited"`.

## Welcome screen and menu

Any postback payload `zernio:workflow:<workflowId>` starts that workflow when tapped (active on the account and profile).

| Surface | Endpoint | Platforms |
|---|---|---|
| Greeting text | [`/v1/accounts/{accountId}/messenger-greeting`](/account-settings/set-messenger-greeting) | Facebook |
| Get Started button | [`/v1/accounts/{accountId}/messenger-get-started`](/account-settings/set-messenger-get-started) | Facebook |
| Ice breakers | [`/v1/accounts/{accountId}/messenger-ice-breakers`](/account-settings/set-messenger-ice-breakers) | Facebook |
| Ice breakers | [`/v1/accounts/{accountId}/instagram-ice-breakers`](/account-settings/set-instagram-ice-breakers) | Instagram |
| Persistent menu | [`/v1/accounts/{accountId}/messenger-menu`](/account-settings/set-messenger-menu) | Facebook, Instagram |
| Ice breakers and slash commands | [`/v1/whatsapp/conversational-automation`](/whatsapp/set-whatsapp-conversational-automation) | WhatsApp |

On WhatsApp a tapped prompt arrives as an ordinary message with its text; an `inbound_message` workflow keyed on that text answers it.

## Follow everything with webhooks

- **[`message.sent`](/webhooks/inbox/message-sent)** names what sent each message: `sentVia` plus `automationId`, `workflowId` and `executionId`, `broadcastId` or `sequenceId`.
- **[`workflow.run.started`, `workflow.run.completed` and `workflow.run.failed`](/webhooks/inbox)** follow each run.
- **[`contact.tag_added`, `contact.tag_removed` and `contact.field_changed`](/webhooks/inbox)** mirror what `add_tag`, `remove_tag` and `set_field` nodes write.
- **[`referral.received`](/webhooks/inbox/referral-received) and [`comment.received`](/webhooks/inbox/comment-received)** carry the raw entry events.

## How it behaves

- **Referral dedupe.** A workflow starts whether the referral arrives alone or rides the first message; the two are deduplicated per conversation within 60 seconds.
- **Missed webhooks.** Every 10 minutes Zernio reads the bound post (or the 5 newest posts for an account-wide automation) and runs Instagram and Facebook comments the webhook missed. A comment is answered at most once.
- **Overlap.** When a comment or story-mention automation and a workflow both match, the automation answers and the workflow does not start.
- **Reply-only platforms.** On TikTok, Threads, LinkedIn and YouTube a comment automation posts the public reply only; `commentReply` is required ([platform support](/platforms/compare#comments)).
- **Suppressions are logged** with `status: "skipped"` and the reason in `error`.
- **No double starts.** A redelivered platform event never starts the same workflow twice.

## If it fails

| Error | Cause | Fix |
|---|---|---|
| `409` `not_thread_owner` on a send | Another app owns the thread. `details.ownerAppId` names it when Meta reports it. | Facebook Login: `take` (needs a conversation routing default app and take-control permission). Instagram Login: wait for the owner to pass it, or make Zernio the default app in conversation routing. |
| `400` with `cooldownHours` | `cooldownHours` sent with `repeatPolicy` mode `once`. | Use it only with `every_comment`. |
| `400` on a DM field | A DM field on a reply-only platform (TikTok, Threads, LinkedIn, YouTube). | Send only `commentReply`. |
| Instagram private reply refused | Buttons, cards or attachments to a non-follower. The comment's single private reply is spent. | Open with plain text, send buttons after the reply. |

## Related

- [Workflows](/products/automations/workflows): every trigger, variable, operator and node.
- [Create comment automation](/comment-automations/create-comment-automation): every field.
- [Instagram](/platforms/instagram/inbox) and [Facebook](/platforms/facebook/inbox): DMs, message requests and handover per platform.
- [Message requests](/messages/accept-conversation-request): accept a DM from someone the account has not accepted yet.