Workflows

Workflows turn a single assistant prompt into a structured, multi-step call flow. Instead of one long system prompt that has to cover every situation, you draw the conversation as a graph: a reception step, a lookup step, a specialist step, a transfer to a human, a polite goodbye. Each step has its own focused instructions, and the assistant moves between steps based on transition rules you define.

Workflows are thoroughly tested and ready to use. They carry a Beta label until they have proven themselves at high call volumes and in rare edge cases.

When to use a workflow

A single well-written assistant handles most calls fine. Reach for a workflow when:

• The call has distinct phases — intake, verification, scheduling, hand-off — and one prompt trying to do all of them gets muddled.
• You need a guaranteed action mid-call — look something up, register a lead — without trusting the model to remember to call a tool.
• Different steps need different behaviour — a cheap fast model for small talk, a stronger model for the step that does the real work.
• The ending matters — always transfer to a human on request, always close the call politely.

Building blocks

Edges connect nodes. Each edge carries a description — a plain-language condition such as "The caller asks about available appointment slots" — that tells the assistant when to take it, and an optional message spoken during the hand-over. Transitions are exclusive: one transition at a time, and the conversation context carries over so the caller never repeats themselves.

Global nodes are conversation nodes reachable from anywhere without drawing edges. Mark a node as global (for example the reception) and describe when a caller should land there — the platform wires the transition into every other conversation step automatically.

Global prompt. Shared context — company name, tone of voice, language — goes in the workflow's global prompt, which is prepended to every conversation node. Node instructions stay short and specific.

Deterministic by design

The engine executes the things that must happen in code, not in the prompt:

• Tool nodes call your webhook themselves and always advance along their single outgoing edge — even when the call fails, the error lands in the conversation context so the next step can respond to it. No dead air, no forgotten lookups.
• Transfer nodes speak their announcement once and then dial. The transfer is started by the platform the moment the node becomes active.
• End nodes finish the goodbye line cleanly before hanging up.

The model decides when to move between steps; the platform guarantees what happens inside them.

The workflow and your assistant

A workflow does not replace your assistant — it drives it. When a call comes in on a number with a workflow attached:

One call, one transcript, one end-of-call report — exactly as without a workflow. This also means workflows work with every assistant configuration mode, including assistants resolved dynamically through the assistant-request webhook.

Workflows drive inbound phone calls. Outbound calls placed from the same number and web calls run the assistant's normal behaviour — attaching a workflow never changes those.

Per-step models, voices and transcribers. Every conversation step can override parts of the assistant, and every override is validated fail-closed at call start — a misconfiguration rejects before pickup, never mid-call:

• Model (llm_config): a different text model per step — a cheap fast model for small talk, a stronger one for the step that does the real work. Pipeline assistants only.
• Voice (voice): a different voice per step, within the assistant's provider — on realtime assistants the speech-to-speech voice, on pipeline assistants the text-to-speech voice. A receptionist and a specialist can genuinely sound like different people.
• Text-to-speech (tts_config) and speech recognition (stt_config): full per-step provider overrides including parameters — for example domain key terms or another language on one step. Pipeline assistants only; a realtime model speaks and listens itself.

Creating a workflow

Build visually in the dashboard under Workflows — the canvas supports drag-and-drop nodes, auto-layout, keyboard shortcuts and undo/redo — or create one via the API:

curl -X POST https://api.hmsovereign.com/api/v1/workflows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dental practice reception",
    "definition": {
      "version": 1,
      "entry_node": "reception",
      "nodes": [
        {
          "id": "reception",
          "type": "conversation",
          "instructions": "You are the receptionist. Handle general questions.",
          "first_line": "Good afternoon, Riverside Dental. How can I help you?"
        },
        { "id": "goodbye", "type": "end", "first_line": "Thanks for calling!" }
      ],
      "edges": [
        {
          "from": "reception",
          "to": "goodbye",
          "description": "The caller indicates the conversation is finished."
        }
      ]
    }
  }'

Definitions are validated on write: an invalid graph — an unreachable node, a missing transition description, a transfer without a valid number — is rejected with a list of specific errors. A workflow that saves is a workflow that runs. The full field reference lives in Workflow definitions.

Attaching it to a number

A workflow answers calls once it is attached to a phone number — in the number's settings in the dashboard, or via the API:

curl -X PATCH https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "workflow_id": "WORKFLOW_UUID" }'

Good to know:

• Pause without detaching. Set the workflow's is_active to false and attached numbers fall back to their assistant's normal behaviour immediately.
• Deletion is protected. A workflow that is still attached to numbers cannot be deleted (the API returns 409), so a live number never changes behaviour as a side effect.
• Transfers need a trunk. If the workflow contains a transfer node, the number needs a SIP trunk for transfers, same as the transfer tool.

API reference

• List workflows
• Create a workflow
• Get a workflow
• Update a workflow
• Delete a workflow
• Update a phone number (attach or detach with workflow_id)