Call variables

Call variables are the data one call carries: the person's first name, an order number, a balance, an appointment time, a list of items. You declare the variables an agent uses once, write them into the agent's greeting, workflow lines, instructions and SMS templates as {{name}}, and each call supplies its own values.

• A literal line — the greeting, a workflow line, an SMS — is spoken or sent with the values filled in.
• The agent's instructions name variables but never contain their values: {{balance}} reads as balance, and the values reach the model as data, in one block the model is told never to follow as instructions.

Declare the variables

An agent's variables, SMS templates and caller lookup live in one config, read with GET /v1/agents/{agent_id}/variables and replaced with PUT /v1/agents/{agent_id}/variables (see the API below).

{
  "variables": {
    "version": 1,
    "fields": {
      "first_name": { "type": "string", "max_length": 80 },
      "order": { "type": "string", "required": true },
      "balance": { "type": "number" },
      "is_vip": { "type": "boolean" },
      "items": {
        "type": "list",
        "max_items": 5,
        "item": { "desc": "string", "amount": "number" }
      }
    }
  }
}

An agent declares at most 32 variables. Names are letters, digits and _, not starting with a digit, up to 80 characters.

An agent takes effect automatically when its configuration is valid; until then its calls are refused with a reason. You can write the lines first and declare their variables after: an agent whose greeting names {{plan}} before plan is declared is saved, but stays unpublished, and its metadata.publication names the reason (publication_variables_invalid, UNDECLARED_VARIABLE, where it was found). The PUT that declares plan publishes it, and its next call uses it.

Built-in variables

Every call also carries these, without declaring them. They never collide with your names.

Write them into lines

Hello{{#first_name}} {{first_name}}{{/first_name}}, this is Acme about order {{order}}.
{{#items}}{{#desc}}{{desc}}{{/desc}}{{#amount}}: {{amount}}{{/amount}}. {{/items}}{{^items}}Nothing is due.{{/items}}

• Spaces or tabs inside the braces are fine: {{ order }}.
• Sections nest two deep: a condition inside a list, for example {{#items}}{{#paid}}(paid){{/paid}}{{/items}}. A list inside a list is not allowed.
• An optional variable may only be printed inside its own section, so a missing value can never leave a gap like "Hello , your order is ready": {{#first_name}} {{first_name}}{{/first_name}}. A required variable can be printed anywhere. A list item's own keys are always optional, so inside a list each is printed in its own section too: {{#items}}{{#desc}}{{desc}}{{/desc}}{{/items}}.
• Values are used exactly as given and are never read as markers: a value containing {{…}} is spoken as those characters.
• Numbers are written plainly: 45300.0 reads 45300, 0.5 reads 0.5. A number needs at most 6 decimals and an absolute value below 10¹⁵.
• Anything else that starts with {{ — a misspelled or unclosed marker, a close for the wrong name — is refused when the agent or workflow is published, never silently dropped.
• {{ is reserved. Every {{ in a line starts a marker, and there is no escape: a line cannot contain two literal opening braces. The same holds for the per-call first_message and instructions you send with POST /v1/calls: they are templates like the agent's own. In first_message a marker naming a built-in or a declared variable is filled in; in instructions, as in the agent's own instructions, it only names the variable ({{balance}} reads as balance) and the value reaches the model in the data block. An unresolved or malformed {{…}} in either is refused with call_variables_invalid, where naming runtime_config.first_message or runtime_config.instructions.

Supply the values

• An API call sends them in call_context on POST /v1/calls: {"call_context": {"order": "A-17", "first_name": "Mari"}}. Only declared names are used; any other key is ignored.
• A campaign takes them from the contact list's columns, and fills the contact.* and campaign.* built-ins itself. See Campaigns.
• A Talk or Chat test in the dashboard, or a browser session over the API, takes them as test_values. The test is admitted as a call is: the greeting and instructions render with the test values, and a required value that is missing, or one that does not match its declaration, refuses the test with 400 and the admission code in reason (call_variables_missing, call_variables_invalid or call_variables_over_budget). A Chat test sends the same values with every turn.

A value that does not match its declaration — the wrong type, too long, too many list items — refuses the call before it is placed, with the variable named and the value never echoed.

Names the agent listens for

On a call whose speech-to-text is Deepgram, the call's proper-noun values are also given to the recogniser as key terms, so it hears them as written: the contact's name and first name, the campaign's name, and the values you declared. A value counts when it is one to four words of letters (with ', ., - or &), each starting with a capital letter, 3 to 40 characters, with no digit. Numbers, dates with digits, emails and lower-case phrases never do, and neither do the other built-ins (the call's own facts, a time zone, a language or a reference). At most 20 per call. Protected values that are not yet released, and keypad values, are never sent. A workflow's listener does not receive key terms yet.

Protected variables

Some values must not be said until the person on the line has shown they are the right person: a balance, a date of birth. Mark those protected, with the check that releases them:

"balance": { "type": "number", "protected": true, "requires": "confirmation" }

• confirmation: released once the workflow's identity step is confirmed.
• knowledge_match: released once the caller correctly states a value you hold, such as a postcode or a date of birth (format sets how a date is compared: date:YYYY-MM-DD, date:DD/MM/YYYY or date:MM/DD/YYYY; identifier for an account or reference number).

Protected variables need a workflow agent on Standard or GPT-Live: the workflow decides when each line may be said, and a line before the confirming step that names a protected value is refused when the workflow is published.

On a GPT-Live workflow the live session is only the workflow's voice. It hears no one (the workflow's listener hears the caller), it is given each line as the workflow releases it, and before the confirming step no line it is given names a protected value. So a protected value reaches the model, and the caller, only after the caller is confirmed, exactly as on Standard.

Keypad variables

An automated phone menu can ask for a number: a card, a PIN, a government ID, a date of birth, a reference. Declare that value with keypad and a class, and send it with the call like any other value (as text: a number is refused, because it would lose leading zeros):

"card": { "type": "string", "keypad": { "class": "card" } }

The class is one of reference, card, pin, government_id, date_of_birth or other. A keypad variable is a string (a number would lose its leading zeros), cannot be protected, and is allowed on every conversation engine, GPT-Live and Gemini Live included.

The value comes only from the call's own data. The agent never invents one, and a menu that asks for something the call was not given gets nothing.

What a keypad variable is not:

• Never text. It is not in the agent's prompt, the <call_variables> block, a tool request or a webhook's context.variables, and the model never sees or says it. When a menu asks for it, the platform enters it on the agent's behalf: on the keypad, or, for an agent on the Standard engine and a prompt that accepts speech only, spoken by the platform's own controller voice while the model is muted. Either way the transcript records only Entered {field}. A greeting, instruction, workflow line or SMS template that names it ({{card}}) is refused when you save the config (KEYPAD_FIELD_IN_TEXT) and again when a call is placed.
• Never in another text. A call whose instructions, prompts, workflow lines, SMS templates, navigation_hint or other variables contain the value's digits is refused with keypad_value_in_text, naming the field and where, never the value. The check ignores spaces, punctuation and non-ASCII digits (4111 1111 and ４１１１ both match), counts * and #, and also reads each filled-in line as it will be said or sent and all your other variables together, so a value split between a greeting and a variable, or between two variables, is found. A value of three characters or fewer is only refused where it stands alone as a whole number, so ordinary text with a stray digit does not refuse the call. It cannot catch a value you deliberately cut into pieces and spread across unrelated texts, or digits written out as words.
• Not in your reads. GET /v1/calls/{call_id}, the MCP call tools and the Calls drawer withhold it from call_context and the variables list while the call runs, and a call refused by policy never stores it. The drawer lists the field with its class and the state keypad, not whether it has a value.

The value has to be dialable. Spaces, -, /, . and parentheses are dropped (4111 1111 1111 1111 is 4111111111111111, 01/02/1990 is 01021990, in the order you wrote it), and what remains must be 1 to 32 characters of 0-9, * and #. If it is not, a required variable refuses the call with keypad_value_not_dialable and an optional one is dropped: the call is placed without it, and a menu that asks for it ends the call.

Two limits worth knowing. A keypad value is entered on the call's own line for whatever menu asks, at any prompt: the platform does not check that the menu is the one you meant, and it cannot see a company phone system that forwards the line elsewhere. And once a person answers, anything that person says is an ordinary conversation, even if they read a number back.

What is kept after a keypad value is entered

The platform holds a keypad value only so the call can key it. When the call ends it deletes the value from the call record: call_context (as stored and as GET /v1/calls/{call_id} returns it) no longer lists the field, and neither does the copy of your request the call was checked against. The Calls drawer and the timeline show the entry as Entered {field}, with no digits and no count.

The transcript is masked at the source, in three stages:

• From the first key until a person answers, every number the other side says (digits in any script, and number words in the languages the platform has a table for) is stored as █, whether or not it matches your value. The agent is not given what the menu says in that time; it is told which keys the menu offers and what each is for, without numbers. A menu in a language the platform has no number words for is stored as "far end spoke, content withheld".
• Once a person answers, the agent hears the call again, and any stretch of two or more digits that is part of your value is stored as █, however the digits are spaced or split across consecutive turns, and for the digits 0 to 9 spoken as words ("four one one one", "double four") in those languages. A pair of digits that happens to occur in your value (such as 11) is masked too. Numbers such as "twenty four" are not read as digits.
• When the call ends the whole transcript is masked once more, across adjacent turns, before it is uploaded.

The platform keeps no copy to retry with. A campaign retry reads the contact's own variables again. For a call you place through the API, send the value again with every retry: a retry without an optional keypad variable is placed, and a menu that asks for it ends the call; without a required one it is refused, as for any missing required variable.

Caller lookup

For inbound calls an agent can look the caller's number up in one of its contact lists ("caller_lookup": {"contact_list_id": "cl_..."}), which fills the contact.* built-ins. A number match is not proof of who is calling: on an inbound call every other looked-up field is treated as protected, and only contact.first_name and contact.name may be said before confirmation — unless you mark a field "before_confirmation": true. On an agent without a workflow nothing can confirm the caller, so a looked-up field without before_confirmation never reaches the call at all; if it is also required, every call from a matched number is refused as call_variables_missing.

Limits

Every line the call speaks is rendered with the call's values before the call is placed, and the call is refused rather than cut short when something does not fit:

An SMS is checked when it is sent, with the text it really renders: at most 6 segments. A message over that is refused, never truncated, and the call goes on. When the agent sends a template during a call, the tool's result records OUTPUT_BUDGET_EXCEEDED; a workflow's Send SMS step records SMS failed with that reason; POST /v1/agents/{agent_id}/messages answers 400.

A refused call is answered 400 {"error": "BadRequestError", "message", "reason", "field", "where"}: field names the variable and where the destination when they apply, and reason is one of call_variables_missing (a required value is absent), call_variables_invalid (a value does not match its declaration), call_variables_over_budget (a filled-in line is empty or over its limit), workflow_binding_failed, schema_pair_mismatch, per_call_text_on_workflow (per-call first_message or instructions sent to a workflow agent, which speaks only its authored lines), keypad_value_not_dialable (a required keypad variable has characters a phone keypad cannot press) or keypad_value_in_text (a text names a keypad variable or carries its digits).

What changes for existing integrations

Call variables change what some existing requests and payloads carry. If your integration relies on any of these, update it:

1. Tool and connection webhooks receive context.variables — the call's declared variables and built-ins, never a protected value before confirmation — instead of the raw context.call_context.
2. Lists in call_context hold at most 16 items (previously 32), on POST /v1/calls, gateway outbound calls and test values. A call_context outside its bounds -- a string over 512 characters, a list over 16 items, an object over 32 keys, or more than 4,096 bytes in all -- is refused by the request check before the call's variables are read: a plain 400 that names the bound, with no reason code and no variable.
3. Campaign calls' call_context no longer carries campaign_id, campaign_run_id, attempt_no or contact_name. They are the built-ins campaign.id, campaign.run_id, campaign.attempt and contact.name.
4. Per-call first_message and instructions are templates: an unresolved or malformed {{…}} in them is refused on POST /v1/calls (400, reason call_variables_invalid), and a workflow agent refuses per-call text altogether (per_call_text_on_workflow).
5. Every agent's greeting and instructions are checked when it is published, whether or not it declares variables. A line naming an undeclared variable keeps an unpublished agent unpublished, with the reason (see Declare the variables), and refuses the edit of a published one with 400 variables_config_invalid. This applies to every hosted agent, whether or not it has a language set: each one is published by its first valid save, and its metadata.publication records why while it is not.
6. On a workflow call, only the workflow's own steps run tools. A Read tool step runs the AI agent's knowledge base search, calendar tools and Integration actions when the workflow declares them with source: "agent"; the AI agent's model is offered none. A call that carries protected values runs no tool at all (see Agent workflows).
7. Built-in variables reach the model on every engine, GPT-Live and Gemini Live included, in the call's data block.
8. An agent's edits apply through its publication. A hosted agent that is not published — because its configuration is not valid yet — refuses real calls with the reason (agent_not_published), rather than running whatever its settings say. In the dashboard the agents list shows it as Not ready for calls, linked to the part of its setup to fix, and the setup names each reason ("Not ready for calls — …"). A call placed to it is refused with "The AI agent is not ready for calls: its configuration has not been published yet." Fix the named part and save: a valid save publishes it.
9. Call reads (GET /v1/calls/{call_id} and the MCP call tools) no longer include the call's variables snapshot, and a call's call_context is returned without its protected values.
10. Workflow versions published before call variables no longer run: see Agent workflows.

When your workspace moves to call variables

Skysay moves existing agents to call variables for you, in a short scheduled maintenance window. What your callers hear does not change: every workflow's lines were checked to produce the same words before and after. Greetings, instructions, language versions and per-call text are not rewritten.

Workflow agents. Each workflow draft changes in three ways you will see in the editor:

• It gains a variables block declaring every name its lines and reads use. The values its disclosing lines speak, and the facts read for those lines, are declared protected, so they are disclosed only after the caller is confirmed; any other value is declared as an ordinary variable.
• A line that disclosed a value is rewritten to the template language: each value and the spacing before it become a section, {{#amount}} {{amount}}{{/amount}}, so a missing value is dropped exactly as it was before. The discloses_debt setting is removed; the protected declaration replaces it.
• On an agent that takes campaign calls, the campaign names it used become built-ins: contact_name is contact.name, campaign_id is campaign.id, campaign_run_id is campaign.run_id and attempt_no is campaign.attempt. On any other agent those names stay your own variables. An agent whose campaign calls and direct calls both send one of those names waits for you to say which one its lines mean.

Its published versions change as described in Versions from before call variables.

If a draft's lines cannot be moved with the same words guaranteed, the move waits until that draft is fixed, and nothing in your workspace changes in the meantime. A saved draft that does not yet pass validation is moved as far as it goes and does not hold up the move -- unless it contains {{ markup the template language would now read differently, which holds the move until it is fixed, wherever it sits. A draft that cannot be read at all does not hold it up either: it gets an empty variables block, and once you repair it, it publishes under the call-variables rules.

Agents on GPT-Live or Gemini Live without a workflow get a Variables config declaring the per-call keys the platform used to pass to their model -- name, contact_name, amount, amount_owed, overdue_amount, currency, due, due_date, reference, reference_id and invoice -- typed from their calls, so the same data keeps reaching the model, now in the call's data block. Other keys in call_context never reached the model and are not declared; declare them yourself if you want the model to see them.

Hosted agents that never published a language set get their current language published as their language set -- on GPT-Live and Gemini Live, the single language their calls already run, unchanged. They then show as published with that language, and later edits apply through publishing, like every other agent. An active agent's language set is published only when its calls run exactly as before; if that cannot be done as it stands, the move waits until it is fixed, as it does for a draft. Inactive agents take no calls, so the move does not wait for them: if an inactive agent's configuration cannot be published as it stands -- an incomplete voice stack, for example -- the move records the reason on the agent exactly as a refused save would. The dashboard shows it Not ready for calls with that reason (such as tts.en), and metadata.publication carries it. Reactivating such an agent takes a save that makes its configuration valid, which publishes it.

SMS templates

An agent can hold SMS templates, sent by its send_sms tool during a call or through the API with no call behind it.

{
  "sms_mode": "free_text",
  "sms_templates": {
    "shipped": {
      "text": {
        "en": "Hi{{#first_name}} {{first_name}}{{/first_name}}, order {{order}} ships {{when}}.",
        "de": "Hallo{{#first_name}} {{first_name}}{{/first_name}}, Bestellung {{order}} wird {{when}} verschickt."
      },
      "slots": { "when": { "source": "model", "max_length": 40 } }
    }
  }
}

• slots are filled by the model at send time (at most 8 per template, each up to max_length characters, 120 at most). The model fills only slots — never your variables.
• sms_mode: "templates_only" refuses any free-text SMS from the agent: it can send only its templates.
• An agent holds at most 20 templates; ids are lowercase letters, digits and _.

Which language is sent. A template's text is chosen in this order:

1. the call's language (for an API send, the language you name);
2. that language's base (et-EE → et);
3. the agent's primary language — its opening language;
4. as a last resort, the template's texts in language-code order.

So a template never fails to send for want of a translation — but a caller may get the primary language instead of their own. Translate every template into every language the agent speaks.

The API

PUT replaces the whole config and republishes the agent in the same step, so the next call uses it; calls already under way keep what they started with. The body is {"config": {…}, "base_revision": n} -- config is the object shown in Declare the variables, and any other top-level key is refused. If the agent cannot be published for any other reason -- an incomplete voice stack, or a language its workflow cannot speak -- the whole PUT is refused and nothing is stored. Send back the revision you read as base_revision: if the agent was changed and republished since — by another edit of this config, or of its voice, prompt or languages — the write is refused with 409 {"error": "revision_conflict", "revision": <current>} and nothing changes. A config the checks refuse is 400 {"error": "variables_config_invalid", "message", "issues": [...]}: every problem at once, each issue naming its code and, where it applies, the field it is about and where it was found; a misspelled or unbalanced marker also names the marker text. Nothing is stored or published.

{"error": "variables_config_invalid", "message": "call variables cannot be published: OPTIONAL_OUTSIDE_SECTION",
 "issues": [{"code": "OPTIONAL_OUTSIDE_SECTION", "field": "first_name", "where": "first_message.en"}]}

where is one of:

A config that is valid in itself but would let the agent's active workflow say a protected value before the caller is confirmed -- turning on caller lookup protects the looked-up fields that are not before_confirmation -- is refused with 409 {"error": "workflow_revalidation_failed", "message", "issues": [...]}, each issue a PROTECTED_BEFORE_CONFIRMATION at steps.<step_id>. The same 409 with ACTIVE_WORKFLOW_UNREADABLE means the active workflow could not be read to check it. Nothing is stored.

Issue codes

POST …/messages is project-scoped, unlike POST /v1/messages: the send uses the agent's own project and a sending number from it. Send the template_id, the variables the template uses, the model slots, an optional language, and the usual to, purpose and recipient_type of a message. An agent in another workspace or project and an unknown template are the same 404. A protected variable cannot be sent this way — there is no call to confirm who you are writing to — and a template whose text names one cannot be sent through this route at all, even with no values. A key in variables the agent does not declare is refused with 400.

curl -X POST "$SKYSAY_BASE_URL/v1/agents/$AGENT_ID/messages" \
  -H "Authorization: Bearer $SKYSAY_API_KEY" -H "Content-Type: application/json" \
  -d '{"template_id": "shipped", "variables": {"first_name": "Mari", "order": "A-17"},
       "slots": {"when": "tomorrow"}, "from_number_id": "pn_...",
       "to": "+12025550111", "purpose": "support", "recipient_type": "business"}'

During a scheduled maintenance window the two writes, PUT /v1/agents/{agent_id}/variables and POST /v1/agents/{agent_id}/messages, answer 503 with "error": "platform_maintenance" and a Retry-After header; nothing changes and nothing is sent. A message request is checked first (the agent, template, values and sending number), so a malformed one is still answered with its own 400 or 404 during the window. Reading the config keeps working.

From an MCP client

The same three operations are MCP tools, with the same scopes and answers: get_agent_variables, set_agent_variables and send_agent_template_message. A refused call returns isError with the route's refusal under error.body, so an assistant can read the issues of a refused config, or the current revision after a conflict, and correct itself.