Pre-Call Init

Pre-call initialization lets you dynamically select and configure the agent before a call starts. Works on all transports.

Supported Transports

Transport	Trigger	`call.type` value
Twilio voice	`routing_target_type: "webhook"` on phone number	`inboundPhoneCall`
WhatsApp voice	`routing_target_type: "webhook"` on phone number	`inboundWhatsAppCall`
WebRTC	`server_url` in POST /v1/webrtc/connect body	`webrtc`

Setup

Phone numbers (Twilio / WhatsApp)

Bind with routing_target_type: "webhook":

curl -X POST http://localhost:8090/v1/phone-numbers \
  -H "Authorization: Bearer tc_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "e164_number": "+15551234567",
    "external_number_sid": "PNxxx",
    "routing_target_type": "webhook",
    "server_url": "https://your-server.com/turncall/init"
  }'

WebRTC

Pass server_url in requestData:

POST /v1/webrtc/connect
{
  "sdp": "v=0...",
  "type": "offer",
  "requestData": {
    "server_url": "https://your-server.com/turncall/init"
  }
}

Your Server Receives

{
  "message": {
    "type": "call-init",
    "call": {
      "id": "call-uuid",
      "provider_call_id": "CA...",
      "type": "inboundPhoneCall"
    },
    "phoneNumber": {"number": "+15551234567"},
    "customer": {"number": "+15559876543"},
    "timestamp": "2026-04-06T12:00:00Z"
  }
}

Verify the Signature

Each call-init request is HMAC-signed with the number’s server_url_secret (returned when you bind the number). Headers: X-TurnCall-Signature: v1=<hex> and X-TurnCall-Timestamp; the HMAC-SHA256 is computed over "{timestamp}.{raw_body}" — the same scheme as event webhooks.

import hashlib, hmac

def verify(raw_body: str, sig: str, ts: str, secret: str) -> bool:
    expected = "v1=" + hmac.new(
        secret.encode(), f"{ts}.{raw_body}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

Reject unverified requests — call-init decides which agent answers a real call.

Response Options

Agent ID
Agent ID + Variables
Inline Agent
Full Response

{
  "agent_id": "agent-uuid-here"
}

{
  "agent_id": "agent-uuid-here",
  "variables": {
    "customer_name": "John Smith",
    "account_id": "ACC-123"
  }
}

{
  "agent": {
    "system_prompt": "You are helping John Smith...",
    "first_message": "Hello John!"
  }
}

{
  "agent_id": "agent-uuid-here",
  "variables": {"customer_name": "Jane", "tier": "enterprise"},
  "metadata": {"crm_id": "C-789"},
  "dynamic_data": {
    "knowledge_context": "Customer has 2 open tickets: #101, #102."
  }
}

Response Fields

Field	Purpose
`agent_id`	Load existing agent by UUID
`agent`	Inline agent config (alternative to `agent_id`) — see below
`variables`	Template variables rendered into `{{placeholders}}` in prompts
`metadata`	Stored on call record for analytics
`dynamic_data.knowledge_context`	Prepended to system prompt as runtime context

What Happens

call.initializing webhook event fires (informational)

Template {{variables}} are rendered into the system prompt

knowledge_context is prepended to the system prompt

metadata is stored on the call record

call.started event fires

Pipeline starts with the resolved configuration

Returning an inline agent

agent and agent_id are alternatives, not a merge: an inline agent replaces the configuration for that call rather than overriding parts of a stored one. Send the whole config, not a patch. Because an inline agent is not a stored agent, it has no row to point at, and that is visible to you:

Every event for such a call carries agent_id: null, and the call does not appear in per-agent listings. This is the correct answer to “which stored agent ran this call” — null means none of them, not not resolved yet.

Everything else still works. The configuration the call ran with is recorded on the call itself, so post-call analysis, the transcript and the call.ended webhook are unaffected. Correlate such calls through call_id, or through metadata you returned in the call-init response — that is what it is for. Knowledge bases linked to a stored agent do not apply, since the call does not run that agent. An inline agent names its own in knowledge_bases, with the same fields as a link (knowledge_base_id, mode, priority, top_k, similarity_threshold, tool_description):

{
  "agent": {
    "system_prompt": "You are the receptionist at Luigi's.",
    "knowledge_bases": [{"knowledge_base_id": "KB_ID", "mode": "prompt"}]
  }
}

Each id must be a knowledge base in the phone number’s project. One that is not, or an entry TurnCall cannot read, is skipped with a warning and the call still connects. See Knowledge Base.

For persistent, searchable knowledge, use the Knowledge Base API instead of knowledge_context. Use knowledge_context for per-call dynamic data like CRM records or open tickets.

Getting Started

Guides

Supported Transports

Setup

Phone numbers (Twilio / WhatsApp)

WebRTC

Your Server Receives

Verify the Signature

Response Options

Response Fields

What Happens

Returning an inline agent

​Supported Transports

​Setup

​Phone numbers (Twilio / WhatsApp)

​WebRTC

​Your Server Receives

​Verify the Signature

​Response Options

​Response Fields

​What Happens

​Returning an inline agent

Supported Transports

Setup

Phone numbers (Twilio / WhatsApp)

WebRTC

Your Server Receives

Verify the Signature

Response Options

Response Fields

What Happens

Returning an inline agent