Dynamic Variables

Dynamic variables let you configure a template for your agent's behavior. You can re-use the same general instructions while dynamically personalizing every conversation your agent has.

In this tutorial, you will learn how to:

• Template your AI assistant configuration with dynamic variables
• Supply the values via an outbound API request or the dynamic variable webhook

---

Dynamic variables are placeholders surrounded by double curly braces. For example:

Hello, this is ABC Ambulance. Am I speaking with {{full_name}} with {{facility_name}} - {{facility_department}}?"

You can template them in the following fields

• instructions
• greeting
• tools

Telnyx also provides these system variables, all prefixed with telnyx:

Variable	Description	Example
{{telnyx_current_time}}	The current date and time in UTC	Monday, February 24 2025 04:04:15 PM UTC
{{telnyx_conversation_channel}}	This can be phone_call , web_call, or sms_chat	phone_call
{{telnyx_agent_target}}	The phone number, SIP URI, or other identifier associated with the agent.	+13128675309
{{telnyx_end_user_target}}	The phone number, SIP URI, or other identifier associated with the end user	+13128675309

You can also define your own variables. There are three ways to resolve a customer-defined dynamic variable before a conversation. They follow this order of precedence.

1. Pass the variables via the outbound API call

curl --request POST \
  --url https://api.telnyx.com/v2/texml/calls/<texml_app_id> \
  --header "Authorization: Bearer $TELNYX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
      "From": "+1",
      "To": "+1",
      "AIAssistantDynamicVariables": {
        "full_name": "James Smith",
        "facility_name": "Cleveland Clinic Main Campus",
        "facility_department": "Emergency Department"
      }
  }'

2. Configure Dynamic Variables Webhook

If the dynamic_variables_webhook_url is set for the assistant, we will send the following payload at the start of the conversation

{
  "data" :{
   "record_type": "event",
   "id": "event_id",
   "event_type": "assistant.initialization",
   "occurred_at": "2025-04-07T10:00:00Z",
   "payload": {
    "telnyx_conversation_channel": "phone_call",
    "telnyx_agent_target": "+1234567890",
    "telnyx_end_user_target": "+1234567890",
    "telnyx_end_user_target_verified": false
   }
  }
}

Note

The telnyx_end_user_target_verified field will be set to true if Telnyx has verified the end user target (for instance, via STIR/SHAKEN attestation for a phone_call) and false otherwise.

We expect a JSON response with the following structure. If we do not receive this response within a 1-second timeout, the call will proceed "best effort" with the alternatives listed below.

All three fields (dynamic_variables, memory, and conversation) are optional. The dynamic_variables field sets the values for the specified dynamic variables.

You can read more about the memory and conversation fields in our tutorial on Memory.

{
  "dynamic_variables": {
    "full_name": "Rachel Thomas",
    "facility_name": "UCHealth",
    "facility_department": "Cardiology"
  },
  "memory": {
    "conversation_query": "metadata->telnyx_end_user_target=eq.+13128675309&limit=5&order=last_message_at.desc"
  },
  "conversation": {
    "metadata": {
      "your_custom_metadata": "your_custom_value"
    }
  }
}

3. Configure default dynamic variables in the Assistant builder

In the above view, you can also set default values for dynamic variables at the agent level. These will serve as a fallback if any of the above mechanisms do not properly resolve a variable.

4. Unset variables

Variables not set by any of the above methods will remain in their raw form ({{full_name}}).