Context & Variables

Talkr has a simple data model for passing information through a call. Understanding it is key to building agents that feel personalised and to extracting useful results after a call.

The three context objects

initial_context ──► Agent ──► gathered_context
                       │
                 [template variables](/docs/voice-agent/template-variables)
                 (used in prompts)

initial_context

Data available to the agent before the call starts — the contact's name, account details, appointment information, anything the agent should know upfront. It can be set from several places:

• API trigger — pass it in the request body when calling POST /public/agent/{uuid} or POST /telephony/initiate-call
• Campaign CSV — columns beyond phone_number automatically become initial_context fields for each contact's call
• Pre-call data fetch — enrich the context with data from your CRM or ERP via an HTTP call as the call starts, before the agent speaks
• Agent Settings — set template context variables on the agent for testing; they're included in test calls from the workflow editor and ignored on production calls

Template variables

Values from initial_context are available in your agent's prompt using {{double_brace}} syntax.

You are calling {{customer_name}} about their {{plan}} plan,
which renews on {{renewal_date}}. Be friendly and confirm
whether they'd like to continue.

When the call starts, Talkr substitutes the values before sending the prompt to the LLM — so the agent speaks naturally as if it already knows the contact.

Fallback values

If a variable might be missing or empty, use a pipe (|) to provide a default value:

Hello {{customer_name | there}}, we're calling about your {{plan | current}} plan.

When customer_name is not set, the agent will say "Hello there" instead of leaving a blank. The syntax is:

{{variable_name | fallback_value}}

If the variable is present and non-empty, the fallback is ignored and the actual value is used.

Default variables

Built-in variables for current time and weekday, available in any prompt without setting up initial_context.

Replace <TIMEZONE> with an IANA timezone name such as Asia/Kolkata, America/New_York, or Europe/London.

Today is {{current_weekday}} and the current time is {{current_time_America/New_York}}.

Telephony variables

For telephony calls (inbound and outbound), Talkr automatically adds these variables to initial_context:

For inbound calls, caller_number is the customer's number and called_number is your Talkr number. For outbound calls, it's the reverse — caller_number is your Talkr number and called_number is the customer's number.

You are speaking with the caller at {{caller_number}}.

gathered_context

Data the agent extracts during the call — the opposite direction of initial_context. Use it to turn a conversation into structured data: what the customer wants, whether they confirmed something, a value they gave you out loud.

How it gets populated

Turn on extraction on an Agent or End Call node and define one or more variables to extract. Each variable has:

When the conversation reaches that node, the LLM reads the transcript so far and fills in each variable based on its prompt. If a value can't be determined from the conversation, the variable is left empty rather than guessed — leave the prompt specific enough that the LLM knows exactly what counts as a match.

You can add extraction to more than one node. Each node's extracted variables are merged into the same gathered_context object as the call progresses, keyed by name — reuse a name at a later node if you want to overwrite an earlier value.

How to reference it downstream

gathered_context is not available in Agent prompts — a prompt can only reference initial_context fields, because extraction typically happens after the conversation that would use it. To act on extracted data, send it out via a node instead:

{
  "customer": "{{initial_context.customer_name}}",
  "resolution": "{{gathered_context.resolution}}",
  "callback_requested": "{{gathered_context.wants_callback}}"
}

See Webhook Payloads for the full list of variables available alongside gathered_context in a payload template.

Data flow example

sequenceDiagram
    participant App as Your System
    participant Dog as Talkr
    participant LLM as LLM

    App->>Dog: initial_context: {customer_name: "Jane", plan: "premium"}
    Dog->>LLM: Prompt with {{customer_name}} and {{plan}} substituted
    LLM-->>Dog: Conversation response
    Note over Dog,LLM: Call progresses...
    Dog->>LLM: Extract: did the customer confirm renewal?
    LLM-->>Dog: gathered_context: {renewal_confirmed: true}
    Dog-->>App: Run record with gathered_context

Where variables are available