Workflows contract

Endpoints

The stored shape

{
  "wf_route001": {
    "id": "wf_route001",
    "name": "Talk to the team",
    "description": "Use when the caller wants a person, or agrees to be connected to the team.",
    "steps": [
      {
        "id": "ask",
        "type": "collect_information",
        "label": "Language and reason",
        "config": {
          "items": [
            { "id": "language", "label": "Preferred language", "type": "choice", "choices": ["English", "Spanish"] },
            { "id": "reason", "label": "Why they want a person", "type": "text", "required": false }
          ]
        }
      },
      {
        "id": "route",
        "type": "condition",
        "config": { "cases": [{ "id": "spanish", "field": "collected.language", "op": "equals", "value": "Spanish" }] },
        "outputs": {
          "spanish": [
            {
              "id": "to_team",
              "type": "transfer",
              "config": { "destination": { "kind": "team", "teamId": "team_es" }, "introduction": "{{contact.firstName}} would like help in Spanish. {{collected.reason}}" },
              "outputs": {
                "connected": [{ "id": "note", "type": "add_note", "config": { "note": "Transferred to the Spanish team." } }],
                "nobody_available": [{ "id": "later", "type": "steer_agent", "config": { "guidance": "Nobody is free. Offer a callback." } }],
                "not_connected": []
              }
            }
          ],
          "otherwise": [
            {
              "id": "to_roster",
              "type": "transfer",
              "config": { "destination": { "kind": "roster" }, "introduction": "I have {{contact.firstName}} on the line. {{collected.reason}}" }
            }
          ]
        }
      }
    ]
  }
}

• A workflow is { id, name, description, steps }. id is wf_ and 8 lowercase letters or digits, stable for the workflow’s life. name is 1 to 60 characters, description 1 to 3000.
• A step is { id, type, label?, config, outputs?, outputLabels? }. id is up to 40 of a-z 0-9 _ -, unique in the workflow. label is up to 120 characters.
• outputLabels optionally maps existing output ids to display names of up to 120 characters. It changes only the labels in the editor and canvas; conditions, ids and execution stay the same. Omit a label to use its default.
• outputs exists only on a node that has outputs, one list of steps per output. A node with outputs ends its list: what follows it goes on one of its outputs. An output may be left empty or absent.

The catalogue

Rules a save enforces

• Collect information is the only way the AI supplies inputs. A node reads collected.<id> only after the Collect information node that gathers it, and response.<key> only on the Success output of the Webhook with response that maps it. An item id has one definition in a workflow, and no item may be named like a node’s argument (slot_id, event_id, confirmed, from_date, days, earliest, latest).
• After a Transfer’s Connected output only instant and after nodes and Conditions: the AI has left the call. A call makes one transfer attempt; a fallback transfer goes only on Nobody available.
• Put on DND ends the lead’s journey. Only internal steps can follow it on its path, in one list, and they still run for the stopped lead: add_tag, remove_tag, set_field, move_stage, add_note, notify_teammate and send_webhook. Nothing that contacts the lead or needs the AI on the call can follow it, and no Condition. Book appointment needs a Find slots node earlier on its path. Find slots has one calendar or routing rules over required collected items, with no default calendar.
• Tags are chosen in their node, one per node, never by the AI. On the native CRM there are no tags: data.subAccount.nativeCrm is true, tagNodes is false, and a save holding a tag node is refused. It has no pipelines or email either, so Move stage and Send email are refused there too. The two rules compose: on the native CRM only Set field, Add note, Notify teammate and Send webhook can follow Put on DND, and the refusal names only those. The overview of a sub-account also says nativeCrm.
• Every step that names something in the sub-account is checked when it is new or changed: the custom fields it writes (Set field field, a Collect information item’s field) by id; the custom fields it reads (a Condition case’s field, Check zip code’s field, a Webhook with response field from a contact field) by id or key; Move stage’s pipeline and stage; the calendars of Find slots and Cancel appointment, which must be active and listed by the calendars lookup for their system; the team or rep a Transfer names (destination.teamId, destination.repId), which must be the sub-account’s agency’s (reps and teams lookups). A reference inside text ({{contact.custom.…}}) is not checked: an unknown one is left empty.
• A workflow books on calendars from one system: every Find slots calendarId and routing[].calendarId and every Cancel appointment calendarIds entry, on any branch, is native (cal_ and 20 hex characters), Cal.com (calcom:<event type id>), Calendly (calendly:<event type uuid>) or GoHighLevel (any other id without a name: prefix), never two of them. A calendar still to fill counts for none, and so does one the sub-account’s CRM cannot book on (a GoHighLevel calendar on a native sub-account, which going live refuses with calendar_not_on_crm), so it can be replaced one setting at a time. A new or changed workflow that mixes them is refused with invalid_workflow.
• A Book appointment whose Find slots names a Cal.com or Calendly calendar needs the caller’s email first: a Collect information item, required, saving to contact.email, earlier on its path (before it in its own steps, or before the branch it is in). A new or changed workflow without one is refused with invalid_workflow, with stepId pointing at the Book appointment. The booking itself asks the caller only for the time, and for their timezone when times are offered in it and none is on file.
• What a step saves to a field must fit the field’s kind (the kind the custom_fields and contact_fields lookups give). A Collect information item saved to a field takes the answer type of its kind: phone for a phone field, email, date, number for a number or amount, choice of the field’s options for a dropdown, multi_choice (or choice) of its options for a multi-select, boolean for yes or no; a text field takes any single answer. A fixed Set field value must be one the field holds: a number written plainly, a full phone number with its country code (+14155550100), an email address, a date as YYYY-MM-DD, one of a dropdown’s options, or a multi-select’s options separated by commas. A file upload, signature or text box list field (kind unsupported) cannot be set. A value made from {{references}} is checked on the call, where a value that does not fit is not saved. An item saved before, unchanged, is not checked again. An item saved to no field is kept for the call only.
• On a call, a phone number is saved in E.164: one given without its country code takes the sub-account’s country (its calling line’s, else its timezone’s) where that country’s numbers are known, and is asked for again otherwise (a save made after the call keeps one it cannot place as given). A trunk 0 after the country code (+44 07700 900123) and an extension are left out. An email is saved lowercased, a date as YYYY-MM-DD, several choices as the list of options.
• A setting the client fills for their business (a calendar, a tag, who takes a transfer, the covered zip codes, a choice item’s choices, an item’s label) may be left empty on an explicit draft: it is incomplete, not invalid, and it is listed in the agent’s setup.items as a setup item. An agent that is not an explicit draft refuses it on save as setup_incomplete, and Prepare agent refuses any agent that still has a setup item. See Setup items.
• Every agent must retain Stop contact, including conversation-only agents. Its workflow id, name and first Put on DND action cannot be deleted, replaced or placed behind a condition. API and AI edits follow the same rule. It has its own slot alongside twenty custom workflows; an older agent missing it gains it on save/build. Internal steps after DND remain editable.
• New agents also start with Schedule a callback unless already covered or their configuration cannot use it, and always have two always-on tools: Return the delegated result (respond_to_voice) and end_call. Neither can be removed, and a save adds them to an older agent that lacks them. end_call no longer ends a call: the agent says goodbye and the call ends on its own. Earlier conversations and Messages stay optional.

When the call ends

After the call

{
  "afterCall": {
    "steps": [
      { "id": "first", "type": "set_field", "config": { "field": "contact.firstName", "value": "{{call.caller_first_name}}" } },
      { "id": "last", "type": "set_field", "config": { "field": "contact.lastName", "value": "{{call.caller_last_name}}" } }
    ]
  }
}

Tool names and renames

How a workflow runs across AI turns

{
  "success": false,
  "detail": "Ask for what is missing, then call again.",
  "needs_information": [{ "id": "reason", "label": "Why they want a person", "question": "What would you like to talk to the team about?" }]
}

{
  "workflow": {
    "name": "Book a first visit",
    "description": "Use when a caller with no appointment wants to book a visit.",
    "steps": [
      { "id": "slots", "type": "find_slots", "config": { "calendarId": "cal_visits" } },
      { "id": "book", "type": "book_appointment", "config": { "mode": "book_only" }, "outputs": { "booked": [] } }
    ]
  }
}

Field references

Secret headers

Lookups

Brain templates

• description says the business logic in words: who it is for, what the call does, the fallback, and that texting is off.
• direction is outbound, inbound or either: the campaigns it suits.
• logic is the same logic in a few values, so a builder can match an agent’s logic to a template:

  Key	Values
  booking	none, single (one calendar) or routed (one question’s answer picks the calendar; there is no default calendar)
  cancel	whether a lead can cancel an appointment on the call
  transfer	none; primary: a transfer is a main path whenever the caller wants a person, side by side with booking; first_with_booking_fallback: an interested lead is transferred, and booking is offered only when the transfer ends Nobody available or Not connected
  direction	inbound, outbound or either
  texting	whether it texts: false in every template

• workflows are keyed by a name local to the template. In a step’s config, { "$fill": id } stands for a setting filled from values.<id> (as says how: a list, the answers, the calendars, routing rules), and { "$workflow": key } for the id another of its workflows gets in the agent.
• prompt is the starting Brain in the shared format: # Identity (who the agent is, how it carries itself, the call’s details and a few don’ts), # Steps to follow (the Hook, said word for word when the call starts, then each step’s line and goal) and # Conversational FAQ. It names the agent as {{agent_name}}, its saved name, and speaks with the Layer 1 variables: {{first_name}}, {{full_name}}, {{business_name}}, {{direction}} and the rest. A template states no business fact and holds no [bracketed] placeholder, so placeholders is always empty: the builder writes the business’s own lines and FAQs.
• toFill lists the settings the client fills for their business: id (its key in values), label, kind, value (its JSON Schema) and settings, every { workflow, step, setting } it fills. Every other setting is valid as published.

{
  "id": "booking_one_calendar",
  "toFill": [
    {
      "id": "calendar",
      "label": "The calendar appointments are booked on",
      "kind": "calendar",
      "value": { "type": "string", "pattern": "^[a-zA-Z0-9_:-]{1,200}$", "description": "A calendar id from the sub-account’s calendars lookup." },
      "settings": [
        { "workflow": "book", "step": "slots", "setting": "calendarId" },
        { "workflow": "cancel", "step": "cancel", "setting": "calendarIds" }
      ]
    }
  ]
}

{ "id": "front_desk", "brainTemplateId": "transfer_then_booking", "name": "Front desk" }

{
  "id": "front_desk",
  "brainTemplateId": "booking_several_calendars",
  "name": "Front desk",
  "values": {
    "question": "Is this your first visit with us?",
    "answers": [
      { "answer": "First visit", "calendarId": "cal_first_visits" },
      { "answer": "Been before", "calendarId": "cal_follow_ups" }
    ]
  }
}

• The runtime builds the agent the template makes and the create checks it like any save: its workflows, and every calendar, team and rep it names must be the sub-account’s (calendars active). name defaults to the template’s name.
• Its workflow ids are derived from the agent id: a retry with the same id and body is the same agent; other values for that id are a 409.
• Creation automatically requests preparation for testing (setupStarted: true), with a paused campaign like every new agent. While settings remain incomplete, it keeps provisioningPolicy: "explicit" and runs only test calls; setup.items lists what still needs filling before real calls. Read setup.status for progress.
• The response is the create’s: data.agent (with its workflows) and data.campaign.

{
  "success": false,
  "error": "workflow_resource_not_found",
  "message": "Something this workflow step uses could not be found. Please choose it again.",
  "code": "workflow_resource_not_found",
  "workflowId": "wf_mqe8x9v8",
  "stepId": "slots",
  "field": "values.calendar"
}

Setup items

• workflow_setting: a setting still to fill, where it is (workflowId, stepId, field such as calendarId, destination, items[0].choices) and what to do (message);
• prompt_placeholder: a Brain template [bracketed] placeholder still in the prompt (field: "brain.prompt", placeholder). Templates no longer hold any, so this appears only for an older prompt that still does.

• saves as an explicit draft, and can be edited step by step until none is left;
• takes test calls. A browser or phone test runs every workflow; a setting not filled yet runs on test data, marked as test data in the workflow’s answer (testData, and a sentence in its detail): a test calendar for a calendar not chosen, nobody available for a transfer with nobody chosen (even on a real-effect phone test), any answer for a question with no answers yet, and nothing done for a tag not chosen. Build with AI’s roleplay sets it up for test calls; the agent then reads setup.testOnly: true;
• is not prepared or put live. Prepare agent is refused with setup_incomplete, naming the first item (workflowId, stepId, field) and listing every one in setupItems; a campaign whose agent takes test calls only cannot be activated; and the runtime refuses its real calls and texts.

{
  "success": false,
  "error": "setup_incomplete",
  "message": "Some settings are missing. Please finish the highlighted steps.",
  "code": "setup_incomplete",
  "workflowId": "wf_book0001",
  "stepId": "slots",
  "field": "calendarId",
  "setupItems": [
    { "kind": "workflow_setting", "workflowId": "wf_book0001", "workflowName": "Book appointment", "stepId": "slots", "node": "find_slots", "field": "calendarId", "message": "Some settings are missing. Please finish the highlighted steps." }
  ]
}

Layer 1 variables

Errors

{
  "success": false,
  "error": "workflow_resource_not_found",
  "message": "Something this workflow step uses could not be found. Please choose it again.",
  "code": "workflow_resource_not_found",
  "workflowId": "wf_book0001",
  "stepId": "slots",
  "field": "routing[1].calendarId"
}

Examples

{
  "ifVersion": "REPLACE_WITH_LOADED_VERSION",
  "workflow": {
    "name": "Look up the account",
    "description": "Use when the caller gives an account number.",
    "steps": [
      { "id": "ask", "type": "collect_information", "config": { "items": [{ "id": "account", "label": "Account number", "type": "text" }] } },
      {
        "id": "lookup",
        "type": "webhook_request",
        "config": {
          "url": "https://api.example.com/accounts",
          "method": "POST",
          "headers": { "Authorization": { "secret": { "value": "Bearer REPLACE_WITH_TOKEN" } } },
          "fields": [{ "name": "account", "source": "collected", "item": "account" }],
          "resultMapping": { "plan": "account.plan" }
        },
        "outputs": {
          "success": [{ "id": "found", "type": "steer_agent", "config": { "guidance": "Their plan is {{response.plan}}." } }],
          "failed": [{ "id": "missing", "type": "steer_agent", "config": { "guidance": "The account was not found. Ask them to check the number." } }]
        }
      }
    ]
  }
}

{
  "workflows": {
    "wf_callbk01": {
      "id": "wf_callbk01",
      "name": "Schedule a callback",
      "description": "Use when the lead wants the AI to call them back later.",
      "steps": [
        { "id": "time", "type": "collect_information", "config": { "items": [{ "id": "callback_time", "label": "When to call back", "type": "text" }] } },
        { "id": "schedule", "type": "schedule_ai_call", "config": { "timeFrom": "callback_time" } }
      ]
    }
  }
}

Related

• Build a TFU Live agent
• Capabilities and workflows
• TFU Live API overview