The most important part of building a great agent is giving it the right context. Our agents use context is used for:
  • Customer identification: Associating the session with a specific user, allowing the agent to personalize responses.
  • Variable substitution: Supplying values for variables defined in your agent’s prompt.
  • Context injection: Any other free-form context that needs to be included in the system prompt.

​
Schema

Context is a JSON object. There are two reserved keys: $customer and $variables.

​
$customer

Provides details about the user the agent is speaking with. This enables personalization, historical lookup, and integration with CRMs like Salesforce or Zendesk. It’s schema is:
  • name: Name of the customer
  • phone_no: Phone numer of the customer
  • email: Email of the customer
  • external_id: External unique ID (e.g. the identifier in your internal systems) for the customer
  • salesforce_lead_id: Salesforce Lead ID of the customer
  • salesforce_contact_id: Salesforce Contact ID of the customer
  • zendesk_user_id: Zendesk User ID of the customer
  • extra: A free-form object for any additional metadata about the customer
You don’t need to include every field, just what’s available or relevant. The agent will use whatever context you provide to improve responses and behavior.

​
$variables

Used to substitute variables in your agent’s prompt. All variables without default values must be supplied. You can define them in the Configuration tab and reference them in your prompt as $variable_name.

​
Preloading

In practice, we’ve found that preloading context—before a conversation begins—is the single highest-leverage way to improve agent performance. You can preload context in a few different ways:
  1. API trigger: If you’re starting a conversation via POST /conversations, include a context field in your request.
    • This does not work for inbound calls, since they are initiated by the customer and not by you.
  2. CRM integration: If you’re using a supported CRM, your agent will automatically look up the customer based on identifiers like phone number or email. The agent will pull basic personalization context such as:
    • Name
    • Location
    • Company
  3. Webhook: Configure a webhook to dynamically preload context.
    • Before every conversation, the agent sends a conversation.setup event to your webhook endpoint.
    • Your server responds with the configuration, including the context field you want to inject into the agent.

​
In-conversation

You can update or inject new context into an on-going conversation. This is useful for passing external signals (e.g. “user just verified their identity”) mid-conversation. See the Update context endpoint documentation for more details.

​
Examples

Here are a few examples of how you might shape your context depending on your use-case:

​
Trucking / logistics

{
  "$customer": {
    "name": "Alice Johnson",
    "phone_no": "+15555550123",
    "external_id": "driver-42",
    "extra": {
      "fleet_id": "FLEET-88"
    }
  },
  "$variables": {
    "current_load": "TX-981",
    "vehicle_status": "In transit",
    "upcoming_jobs": ["CA-112", "NV-778"]
  }
}

​
Healthcare

{
  "$customer": {
    "name": "David Kim",
    "email": "david.kim@example.com",
    "external_id": "patient-88",
    "extra": {
      "insurance": { "provider": "BlueCross", "policy_no": "BC-44592" },
      "appointment_history": [
        { "date": "2025-05-01", "type": "Annual checkup" },
        { "date": "2025-07-12", "type": "Follow-up" }
      ]
    }
  },
  "$variables": {
    "appointment_date": "2025-09-01T10:30:00Z",
    "doctor_name": "Ben Bitdiddle"
  }
}
  • Dynamic configuration: learn how to dynamically change the agent behavior for a particular conversation
  • Webhooks: learn the schema of the conversation.setup event webhook used to fetch the initial conversation context