1"use strict";(globalThis.webpackChunkflowera_docs=globalThis.webpackChunkflowera_docs||[]).push([[2492],{8731(e,n,s){s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>i,default:()=>h,frontMatter:()=>a,metadata:()=>r,toc:()=>d});const r=JSON.parse('{"id":"agentflow/nodes/start-triggers/batch-run","title":"Batch Run Trigger","description":"A Batch Run fires your flow once for many recipients \u2014 one run per row of a list. Instead of a single execution, each fire pulls a list of contacts from a data source (an uploaded CSV or a live query over your leads) and runs the flow once per contact, each on their own conversation. The classic use is a WhatsApp template campaign: upload 1,000 contacts, fire once, and every contact gets a personalized run.","source":"@site/docs/agentflow/nodes/start-triggers/batch-run.md","sourceDirName":"agentflow/nodes/start-triggers","slug":"/agentflow/nodes/start-triggers/batch-run","permalink":"/docs/agentflow/nodes/start-triggers/batch-run","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":10,"frontMatter":{"title":"Batch Run Trigger","sidebar_label":"Batch Run","sidebar_position":10},"sidebar":"agentflowSidebar","previous":{"title":"Scheduled Run","permalink":"/docs/agentflow/nodes/start-triggers/scheduled-run"},"next":{"title":"Agent","permalink":"/docs/agentflow/nodes/agent"}}');var t=s(5723),o=s(4315);const a={title:"Batch Run Trigger",sidebar_label:"Batch Run",sidebar_position:10},i="Batch Run Trigger",l={},d=[{value:"How it works",id:"how-it-works",level:2},{value:"Adding a batch run",id:"adding-a-batch-run",level:2},{value:"Data sources",id:"data-sources",level:2},{value:"Row mapping",id:"row-mapping",level:2},{value:"Session continuity",id:"session-continuity",level:2},{value:"Safety features",id:"safety-features",level:2},{value:"Example",id:"example",level:2},{value:"Inspecting results",id:"inspecting-results",level:2},{value:"Tips",id:"tips",level:2},{value:"Related",id:"related",level:2}];function c(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"batch-run-trigger",children:"Batch Run Trigger"})}),"\n",(0,t.jsxs)(n.p,{children:["A ",(0,t.jsx)(n.strong,{children:"Batch Run"})," fires your flow once for ",(0,t.jsx)(n.strong,{children:"many recipients"})," \u2014 one run per row of a list. Instead of a single execution, each fire pulls a list of contacts from a data source (an uploaded CSV or a live query over your leads) and runs the flow once per contact, each on their own conversation. The classic use is a WhatsApp template campaign: upload 1,000 contacts, fire once, and every contact gets a personalized run."]}),"\n",(0,t.jsxs)(n.p,{children:["A batch run is a ",(0,t.jsx)(n.a,{href:"/docs/agentflow/nodes/start-triggers/scheduled-run",children:"Scheduled Run"})," with fan-out turned on \u2014 it uses the same trigger types, timezones, and lifecycle. This page covers what fan-out adds."]}),"\n",(0,t.jsx)(n.admonition,{type:"note",children:(0,t.jsxs)(n.p,{children:["Batch runs are set up in the ",(0,t.jsx)(n.strong,{children:"Automations"})," section, not on the Start node's canvas. See ",(0,t.jsx)(n.a,{href:"/docs/automations/",children:"Automations"})," for the full management experience."]})}),"\n",(0,t.jsx)(n.h2,{id:"how-it-works",children:"How it works"}),"\n",(0,t.jsx)(n.p,{children:"When the automation fires, Flowera reads your data source, turns each record into a row, and runs the flow once per row:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsx)(n.li,{children:"The timer fires (one-shot or recurring \u2014 same as a scheduled run)."}),"\n",(0,t.jsxs)(n.li,{children:["Flowera ",(0,t.jsx)(n.strong,{children:"materializes rows"})," from your data source."]}),"\n",(0,t.jsx)(n.li,{children:"Each row runs the flow independently, so one failure never blocks the rest."}),"\n",(0,t.jsx)(n.li,{children:"Every row reports its own outcome (sent, failed, or skipped)."}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"adding-a-batch-run",children:"Adding a batch run"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["In ",(0,t.jsx)(n.strong,{children:"Automations"}),", create an automation and choose ",(0,t.jsx)(n.strong,{children:"Batch (per recipient)"})," as the execution mode."]}),"\n",(0,t.jsxs)(n.li,{children:["Pick the ",(0,t.jsx)(n.strong,{children:"flow"})," to run."]}),"\n",(0,t.jsxs)(n.li,{children:["Choose a ",(0,t.jsx)(n.strong,{children:"data source"})," \u2014 upload a CSV, or build a live lead query."]}),"\n",(0,t.jsxs)(n.li,{children:["Set ",(0,t.jsx)(n.strong,{children:"row mapping"})," to connect list columns to your flow's variables."]}),"\n",(0,t.jsx)(n.li,{children:"Set the schedule and timezone, then save."}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"data-sources",children:"Data sources"}),"\n",(0,t.jsxs)(n.table,{children:[(0,t.jsx)(n.thead,{children:(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.th,{children:"Source"}),(0,t.jsx)(n.th,{children:"Where rows come from"})]})}),(0,t.jsxs)(n.tbody,{children:[(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.strong,{children:"CSV upload"})}),(0,t.jsx)(n.td,{children:"An uploaded spreadsheet of contacts. Preview the first rows before firing."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.strong,{children:"Lead query"})}),(0,t.jsx)(n.td,{children:"A live query over your workspace's leads, filtered to the segment you want."})]})]})]}),"\n",(0,t.jsx)(n.h2,{id:"row-mapping",children:"Row mapping"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"Row mapping"})," connects each row's columns to your flow's state keys, so the flow can personalize per recipient. For a CSV with a ",(0,t.jsx)(n.code,{children:"name"})," column feeding a state key ",(0,t.jsx)(n.code,{children:"customerName"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"name \u2192 customerName\n"})}),"\n",(0,t.jsxs)(n.p,{children:["Inside the flow you then read ",(0,t.jsx)(n.code,{children:"{{$flow.state.customerName}}"}),". Unmapped columns are still carried on the row but aren't injected into flow state."]}),"\n",(0,t.jsx)(n.h2,{id:"session-continuity",children:"Session continuity"}),"\n",(0,t.jsxs)(n.p,{children:["Each row runs on a chat ",(0,t.jsx)(n.strong,{children:"session"}),", resolved so a batch run lands on the ",(0,t.jsx)(n.strong,{children:"same"})," conversation a real inbound message would \u2014 letting a campaign continue an existing thread instead of starting a throwaway one. You can set a session template (e.g. ",(0,t.jsx)(n.code,{children:"whatsapp-{phone}-..."}),"), reuse a lead's existing session, or let Flowera generate one."]}),"\n",(0,t.jsx)(n.h2,{id:"safety-features",children:"Safety features"}),"\n",(0,t.jsx)(n.p,{children:"Fan-out includes guardrails so a campaign behaves responsibly:"}),"\n",(0,t.jsxs)(n.table,{children:[(0,t.jsx)(n.thead,{children:(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.th,{children:"Feature"}),(0,t.jsx)(n.th,{children:"What it does"})]})}),(0,t.jsxs)(n.tbody,{children:[(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.strong,{children:"Suppression list"})}),(0,t.jsx)(n.td,{children:"Contacts who opted out are skipped before any message is sent."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.strong,{children:"Cross-fire dedup"})}),(0,t.jsx)(n.td,{children:"A recurring campaign skips contacts it already messaged
1in a prior fire (on by default), so a daily send doesn't re-message the same person."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.strong,{children:"Canary rollout"})}),(0,t.jsx)(n.td,{children:"For larger batches, a small slice is sent first; the rest release only if the canary looks healthy."})]}),(0,t.jsxs)(n.tr,{children:[(0,t.jsx)(n.td,{children:(0,t.jsx)(n.strong,{children:"Per-fire row cap"})}),(0,t.jsx)(n.td,{children:"An optional limit on how many rows a single fire processes."})]})]})]}),"\n",(0,t.jsx)(n.admonition,{type:"tip",children:(0,t.jsxs)(n.p,{children:["Leave ",(0,t.jsx)(n.strong,{children:"cross-fire dedup"})," on for recurring campaigns so contacts aren't messaged repeatedly. Turn it off only when you intentionally want to re-blast the same list each fire."]})}),"\n",(0,t.jsx)(n.h2,{id:"example",children:"Example"}),"\n",(0,t.jsxs)(n.p,{children:["A one-time WhatsApp promo: upload ",(0,t.jsx)(n.code,{children:"contacts.csv"})," (columns ",(0,t.jsx)(n.code,{children:"name"}),", ",(0,t.jsx)(n.code,{children:"phone"}),"), map ",(0,t.jsx)(n.code,{children:"name \u2192 customerName"}),", set a one-shot fire time, and save. On fire, each contact gets a personalized run of your template flow on their own WhatsApp session. Suppressed and already-messaged contacts are skipped automatically."]}),"\n",(0,t.jsx)(n.h2,{id:"inspecting-results",children:"Inspecting results"}),"\n",(0,t.jsxs)(n.p,{children:["After a fire, each row reports a status \u2014 ",(0,t.jsx)(n.strong,{children:"success"}),", ",(0,t.jsx)(n.strong,{children:"failed"}),", or a ",(0,t.jsx)(n.strong,{children:"skipped"})," reason (suppressed, already-sent, and so on). Review per-row outcomes to see exactly who was reached and why any were skipped."]}),"\n",(0,t.jsx)(n.h2,{id:"tips",children:"Tips"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"Preview your CSV or lead query before firing to confirm the rows and columns look right."}),"\n",(0,t.jsxs)(n.li,{children:["Use ",(0,t.jsx)(n.strong,{children:"row mapping"})," to personalize every run \u2014 greet each contact by name, reference their data."]}),"\n",(0,t.jsxs)(n.li,{children:["For a single scheduled run with no recipient list, use a plain ",(0,t.jsx)(n.a,{href:"/docs/agentflow/nodes/start-triggers/scheduled-run",children:"Scheduled Run"})," instead."]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"related",children:"Related"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/agentflow/nodes/start-triggers/scheduled-run",children:"Scheduled Run trigger"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/automations/",children:"Automations"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/agentflow/nodes/start-triggers/whatsapp-trigger",children:"WhatsApp trigger"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"/docs/agentflow/nodes/start",children:"Start node"})}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(c,{...e})}):c(e)}},4315(e,n,s){s.d(n,{R:()=>a,x:()=>i});var r=s(2155);const t={},o=r.createContext(t);function a(e){const n=r.useContext(o);return r.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:a(e.components),r.createElement(o.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.