Copy page

Guides

Inbound Variable Injection

When a phone call comes in, the agent's prompt template renders against dynamic_variables. For outbound calls you supply those at dial time. For inbound calls, the caller is unknown until they connect — so the platform can call your webhook before the agent speaks, hand it the inbound metadata, and use the values you return as the call's dynamic_variables.

This lets the agent greet a caller by name, look up account context, route based on tier, etc. — without your application having to glue together two systems.

Configuration

Set the webhook URL on the agent (Agent Studio → Conversation → "Inbound webhook" or via API):

Code
client.agents.update(
    agent_id="ag_...",
    inbound_webhook_url="https://your-app.example.com/neuratel/inbound-context",
    inbound_webhook_secret="whsec_...",  # used to sign the request
)

Request shape (Neuratel → your webhook)

The platform POSTs JSON to your webhook before the agent's first message. Body:

Code
{
  "event": "inbound.context_request",
  "session_id": "vs_01HX...",
  "agent_id": "ag_01HX...",
  "channel": "phone",
  "from_number": "+12125551234",
  "to_number": "+13105551111",
  "conversation_id": "conv_01HX...",
  "existing_dynamic_variables": {},
  "system_variables": {
    "system__org_id": "org_...",
    "system__direction": "inbound",
    "system__channel": "phone",
    "system__time_utc": "2026-05-05T14:32:01Z",
    "system__caller_region": "US-NY"
  }
}

existing_dynamic_variables reflects whatever was already on the conversation (e.g. set by a prior call or by update_dynamic_variables). The platform merges your response into this dict — it does not wholesale replace.

Signature: the request includes an X-Neuratel-Signature header — the HMAC-SHA256 of the raw body using inbound_webhook_secret. Same scheme as outbound webhooks; see Webhooks.

Response shape (your webhook → Neuratel)

Return JSON with a dynamic_variables dict and an optional replace flag:

Code
{
  "dynamic_variables": {
    "customer_name": "Alice Chen",
    "tier": "scale",
    "open_tickets": "2",
    "last_interaction": "2026-04-30"
  },
  "replace": false
}

Field	Default	Effect
dynamic_variables	required	Map of {name: value}. Values are coerced to string. system__* keys are rejected.
replace	false	If false, merges into existing_dynamic_variables. If true, replaces wholesale.

Timing and timeouts

• Timeout: 1500ms. If your webhook does not respond in time, the call proceeds with existing_dynamic_variables only.
• Retries: none. The platform will not retry a failed inbound webhook within the same call — it would delay the greeting beyond the user's tolerance.
• Failures are silent: a 5xx response is logged but does not abort the call. Build for resilience.

For lookups slower than 1500ms (CRM full sync, complex DB joins), pre-warm a cache keyed on from_number rather than blocking the webhook.

Example handler

Code
from fastapi import FastAPI, Request, HTTPException
import hmac, hashlib

app = FastAPI()
SECRET = "whsec_..."

@app.post("/neuratel/inbound-context")
async def inbound_context(request: Request):
    body = await request.body()
    sig = request.headers.get("x-neuratel-signature", "")
    expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        raise HTTPException(401)

    payload = await request.json()
    customer = await crm_lookup(payload["from_number"])  # your function

    return {
        "dynamic_variables": {
            "customer_name": customer.full_name if customer else "there",
            "tier": customer.tier if customer else "unknown",
            "is_repeat_caller": "true" if customer else "false",
        },
    }

Outbound calls inheriting chat context

For inbound calls that arrive on an existing chat conversation (e.g. a customer was texting and clicked "Call us"), the platform injects the chat thread's dynamic_variables automatically — your webhook is the layer on top of that. This is also true in reverse: outbound voice calls placed against a contact you've been chatting with inherit the chat thread's dynamic_variables without you having to pass them.

Related

• Dynamic variables — outbound variable supply
• Tool variable writes — mid-call variable updates from tools
• Webhooks — signature verification reference