SociaHive Docs

Flow Patterns

Seven named patterns that cover most of what people build with SociaHive automation flows — keyword router, AI fallback, drip, comment-to-DM, and more.

SociaHive flows are graphs: nodes are actions or branches, edges are paths. Most flows are variations on a small set of patterns. Knowing them by name makes it easier to describe what you want to an AI assistant.

This is SociaHive's equivalent of a prompt library — opinionated, named patterns instead of an endpoint dump.

Keyword router

"If the comment says X, do A. If it says Y, do B. Otherwise do C."

[trigger: post_comment] → [condition: keyword "price"]  → [comment_reply: pricing]
                                            ↓ no
                                 [condition: keyword "demo"] → [comment_reply: demo link]
                                            ↓ no
                                 [comment_reply: thanks]

When: any auto-reply that branches on what the user said. MCP shortcut: generate_flow with description "Branch on keywords X, Y; default to Z". The AI picks condition nodes correctly.

AI fallback

"Try a template reply first. If the message doesn't match any template, hand off to AI."

[trigger: message] → [condition: matches template?] → [message: template]
                              ↓ no
                     [ai_response]
                              ↓
                     [condition: confident?] → [continue conversation]
                              ↓ no
                     [action: handoff_to_human]

When: customer support, inbound DMs where most messages are predictable but you want graceful degradation. Why this beats pure AI: template replies cost 0 credits and never hallucinate. AI only fires when the template can't.

Data collection funnel

"Ask name, then email, then qualifying question — drop into CRM."

[trigger: message] → [data_collection: first_name]
                           ↓
                    [data_collection: email]
                           ↓
                    [data_collection: company_size, choices=[1-10, 11-50, 51+]]
                           ↓
                    [action: add_tag "qualified-lead"]
                           ↓
                    [message: booking link]

When: lead capture, demo booking, applicant intake. Pro tip: data_collection nodes have built-in validation. Use email, phone, url types — SociaHive enforces format.

Drip with branches

"Day 0: welcome. Day 2: tutorial. Day 5: ask if they need help. Branch on reply."

[trigger: subscribe] → [message: welcome]
                           ↓
                    [delay: 2 days]
                           ↓
                    [message: tutorial]
                           ↓
                    [delay: 3 days]
                           ↓
                    [message: "still using us?"]
                       ↙       ↘
                  [yes]         [no/no_reply: 24h]
                    ↓                ↓
              [message: tips]   [action: tag "at-risk"]

When: onboarding sequences, course delivery, win-back flows.

Watch the gap

Long delays give people more time to lose interest. Tighter usually wins.

Comment → DM conversion

"Public comment reply ('DMing you now!') paired with a private DM."

[trigger: post_comment, keyword "info"] → [comment: "DMing you now! 📩"]
                                                       ↓
                                              [instagram: opening_dm, body="Here's the info..."]

When: the bread-and-butter Instagram play. Public reply boosts algorithm signal; DM moves the user to a higher-intent surface.

Instagram opening-DM rule

The first DM in this flow needs isOpeningDm: true — Meta blocks unsolicited DMs sent by businesses. The MCP generate_flow tool sets this automatically; if you're wiring nodes by hand, set it on the first message node after the public comment reply.

Webhook-on-completion

"When this flow finishes, ping our CRM."

[…flow…] → [last node] → [webhook: POST https://crm.example.com/lead, body=$context]

When: integration with external systems (HubSpot, Salesforce, custom CRMs) before native connectors land. Tip: the webhook node sends the entire flow execution context — every collected value, tag, variable. Easier than building data per-call.

Randomizer A/B/C/D

"Send variant A or B or C or D, 25/25/25/25."

[trigger] → [randomizer: 4 variants]
                ↓        ↓        ↓        ↓
            [msg: A] [msg: B] [msg: C] [msg: D]
                ↓        ↓        ↓        ↓
            [tag: A]  [tag: B] [tag: C] [tag: D]

When: A/B testing copy or AI prompts. Tag downstream so analytics filter by variant.

Variants

The randomizer (A/B test) step splits traffic between two and six variants.

Connecting buttons and branches

A step can lead on from more than one place: each button, quick reply and card button, each branch of a condition, randomizer, payment, AI step, booking or Ask-to-follow step, or the plain next output of a step without buttons. get_flow lists them for every step under outputs: the handle, the label (the button title or branch name) and connectedTo (the steps it leads to). Each entry in edges has the connection's id.

  • Connect with add_edge. Pass the output as sourceHandle, either its handle (button-1, yes, followed) or its label ("No, thanks", matched without regard to case). Leave it out for the plain next output. An output the step does not have is refused with the list of outputs it has, for example Valid outputs of Choose: button-0 (Yes, please), button-1 (No, thanks).
  • One connection per button or branch. Connecting a button that already leads somewhere is refused. Use update_edge to send it to another step. The plain next output can lead to several steps; they run one after another.
  • Re-point with update_edge: name the connection by edgeId, or by source and sourceHandle, and pass newTarget.
  • Remove with delete_edge: by edgeId, or by source and sourceHandle. When the plain output leads to several steps, add target.

WhatsApp buttons are numbered across the whole step: with two buttons in the first message and one in the second, the second message's button is button-2.

A branch with nothing connected ends the flow there for that person. Routing out of a payment or Ask-to-follow step that is already connected is changed in the flow editor.

Sending a file

A message step can send a file, such as a PDF menu or price list. Upload it first (upload_media_from_url for a file at a public URL, or request_media_upload then finalize_media_upload) and put the returned url in a file block. On WhatsApp the block goes in the step's whatsappContentBlocks:

{ "type": "file", "properties": { "fileUrl": "https://example.com/menu.pdf", "fileName": "Menu.pdf" } }

fileName is the name the person sees. WhatsApp sends the file as a document, and only inside the 24-hour window that opens when the person messages you. The same block works in Messenger and Telegram steps. A file block with no fileUrl is refused when the flow is turned on, and a PDF can't be used as post media.

Anti-patterns

  • Infinite loop. A flow whose last edge points back to its trigger. SociaHive's engine guards via max-depth, but you burn credits on the way.
  • 100-node monolith. If a flow has >30 nodes, split it. Use one to qualify, then trigger another via tag or sequence.
  • AI for trivial branches. A condition node is free; ai_response costs 5 credits. Don't pay 5 to decide "yes or no."

Pattern → goal mapping

GoalPattern
Reply faster to common DMsAI fallback
Build an email list off InstagramComment → DM, then data collection funnel
Send a course over 2 weeksDrip with branches
Route comments by intentKeyword router
Run an A/B testRandomizer
Hand off to a human inboxAI fallback (human-handoff variant)
Push lead data to your CRMWebhook-on-completion

Building one of these

The fastest way is to describe it to your AI assistant via MCP and let it call generate_flow. See the MCP setup guide to connect Claude / ChatGPT / Cursor, then prompt something like:

Build a SociaHive flow using the "comment → DM" pattern: when an Instagram comment contains "price" on any of my posts, reply publicly with "DMing you now! 📩" and send a DM with my pricing link.

Or wire it directly via the SDK — see the developer quickstart.

Changing a flow

generate_flow returns at once and builds in the background. get_flow reports progress in build.status: building, needs_clarification (with the question), failed or ready. Edits wait until it is ready.

A published flow can't be edited directly. Pick one of two ways:

  • Change it in place. deactivate_flow, edit with update_node, add_node or delete_node (for example update_node with keywords to change the trigger keywords), then activate_flow. The flow answers nobody while it is off.
  • Keep it running. duplicate_flow, edit the copy, activate_flow the copy, then deactivate_flow the original.

A prompt that does the first:

My "price" flow is live. Turn it off, add "cost" to its trigger keywords, then turn it back on.

On this page