send_flow_to_contacts
Run an EXISTING interactive flow for each listed contact right now, outside any trigger — as if each of them had just triggered it. Use it when the WHOLE message is the flow — its first block's text, media and buttons are what the recipient sees. To send your own custom text with buttons that run a flow on tap, prefer send_message with buttons: [{ text, flowId }]; it needs no wrapper flow. The flow starts at its start block for every recipient, and any {{var|name}} inside it resolves against that recipient's own variable context. No deploy is needed — the runtime compiles the flow on demand — but the flow must already be applied (use the ids apply_actions returned). Contacts are targeted by contactId only (from list_contacts), 1 to 50 per call. Duplicates are collapsed. Each contact is dispatched independently: one bad id fails its own row in results and the others still go out, so read sent/failed, not just the absence of an error. An unsubscribed contact, or a contact whose bot is not active, is refused — the same rule send_message applies. Nothing is queued for it; its row has ok: false, the reason in error, and refused set to contact_unsubscribed or bot_inactive. A sleeping bot is not refused: it is woken first. BROADCAST and OPERATION flows are rejected — a broadcast flow runs in an audience scope (send it with its broadcast) and an operation runs in system context (use run_operation). For a large audience this is the WRONG tool: create a broadcast whose flow filter selects the audience, and launch that once. Requires the send_flow_to_contact permission. NOT idempotent and not reversible — every call reaches real people again and a sent message cannot be recalled. Confirm the flow and the exact recipient list with the user before calling, and never retry a timed-out call blindly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| flowId | Yes | Required. Id of the already-applied INTERACTIVE flow to run. Broadcast and operation flows are rejected. | |
| params | No | Optional. Literal values for the flow's declared input params (see `inputParams` in get_flow_context), keyed by param id. They are run-scoped — the flow reads them as {{param|<paramId>}} — and a required param left out rejects the whole call before anyone is messaged. | |
| contactIds | Yes | Required. Between 1 and 50 FlowCastle contact ids (from list_contacts) — NOT platform ids. Each one receives its own run of the flow. | |
| applicationId | No | Application (workspace) id. Optional: an application-scoped key (app_...) defaults to its own application, but a personal key (usr_...) has no default and omitting it fails with MCP_APPLICATION_REQUIRED. Call list_applications to get the id. |