Skip to main content
A Custom API Workflow is a saved HTTP request an agent runs at a defined point in the conversation lifecycle. This page is the full reference. For where workflows fit alongside knowledge bases and built-in tools, start with Tools.
This is your agent calling your API. To call Vocily’s API from your own backend, see API Reference instead.

​
The two phases

A workflow’s name is unique per agent, used as its identifier elsewhere (letters, digits, and underscores; no dots).
There is no after-call phase. To send a transcript, analysis, or outcome to your system once the call is over, use webhooks (Agents → your agent → Settings → Webhooks) instead. A webhook is signed, retried on failure, and has a delivery log you can inspect - none of which a one-shot HTTP call at the end of a conversation can offer.

​
Activate an on-call workflow

Creating an on-call workflow does not make it callable by itself. The agent only sees it as a tool it can invoke when the workflow’s name appears in the prompt, greeting, or a system message, written in angle brackets:
Referencing a name that doesn’t exist yet, or that belongs to a Before Call workflow, is rejected when you save the prompt - the error names the unknown reference so you can add the workflow first or fix the typo.
If you never write <workflow_name> anywhere in the prompt, the agent will never call an on-call workflow - silently. There’s no error for this; it just never fires. If a workflow you built doesn’t seem to run, check for its <name> in the prompt first.
Before Call workflows need no such reference - they run automatically on every call.

​
Reference variables inside a workflow

Inside a workflow’s own URL, headers, query parameters, or body, every variable reference needs an explicit namespace prefix - there is no bare {{name}} shorthand here. This is different from using a variable in the prompt or greeting, where a bare {{name}} is always your own custom variable; see Variables for that shorthand and the <tool_name>, ||...||, and ((...)) prompt syntax. agent.* and call.* are not available inside a During Call workflow - the agent already has that context from the conversation itself. In the other direction, api.* and parameters don’t exist Before Call, because no conversation has started yet.

​
Field value modes

Each header, query parameter, path parameter, or body field can use one of these modes: A field marked Dynamic is what makes an on-call workflow feel like a real tool call: the agent extracts the value (an order number, a date, an email) from what the caller says, rather than you supplying it.

​
Required vs. optional fields

Every field is required by default (path parameters are always required). If a required field’s variable has no value when the workflow is about to run, the workflow does not send a request at all - it fails immediately, naming the missing variable. If an optional field’s variable has no value, that one field is simply left out of the request; everything else is sent normally.

​
Authenticate with a credential

Use a credential instead of pasting a secret into a header, so the value is never stored on the workflow and never shown again after you save it.
  1. Go to Settings → Credentials (workspace scope) and add a credential: give it a name and the secret value (an API key or token).
  2. In the workflow’s Headers, add a row for the header your API expects (for example X-Api-Key or Authorization), set its mode to Credential, and select the credential.
The value is write-only: no page or response ever shows it again - including this workflow’s own editor, once saved. To rotate it, replace the value on the credential itself; every workflow using it picks up the new value immediately, with nothing to update on the workflow. Deleting a credential that’s still selected in a workflow’s header is blocked until you remove it there.

​
Map a response for later use

A response mapping pulls one field out of an API’s JSON response and gives it a name you can reference elsewhere. Each mapping has a JSON path into the response ($ for the whole body, $.customer.name for a nested field, $.items[0] for an array element) and a target name. The target must be written as <namespace>.<this workflow's name>.<field>, where the namespace matches the workflow’s own phase - api. for During Call, pre. for Before Call. For example, a During Call workflow named lookup_order mapping $.status to api.lookup_order.status makes that value available as:
  • {{api.lookup_order.status}} inside another During Call workflow’s fields, or
  • {{api.lookup_order.status}} in the prompt - the same token either way. The whole response is {{api.lookup_order}}.
A Before Call workflow’s mapped field reads the same, with its own namespace: {{pre.tool_name.field}}. See Variables for the complete prompt-syntax list.

​
Test a workflow

Use Test API in the workflow editor before enabling it. The test always completes and shows you an outcome - it never shows a generic failure:
  • If your API answers with an error status, the test shows that real status code and body, so you can see exactly what your API sent back.
  • If the endpoint can’t be reached at all (wrong host, timeout), the test shows a message explaining why, with no status code - nothing answered.
Supply values for any Dynamic fields and any Variable fields you want to try, so the test reflects a real call as closely as possible.

​
What happens when a workflow fails

Behavior differs by phase, and only one of them tells the caller anything: A Before Call failure is deliberately quiet - a workflow that can’t be reached should never stop a call from happening. That means a broken Before Call workflow looks like an agent that suddenly doesn’t know who it’s talking to, rather than an error. If a prompt starts sounding generic, check the workflow before you check the prompt.

​
What’s next

  • Reference variables and the prompt-syntax shorthand in Variables.
  • Give the agent instructions for using a workflow’s result in Agent Core.
  • Run a full pass in Test before enabling a workflow for real calls.