Agent Configuration Endpoint

The agent configuration endpoint lets you dynamically configure a conversation at the moment it starts. When an agent has a configuration_endpoint set, Phonic sends a POST request to your URL at the start of every conversation, and your endpoint returns configuration overrides for that specific conversation.

This is primarily useful for inbound calls — for example, your endpoint can look up the inbound caller in your CRM and populate the welcome message with the caller’s information.

Setup

Add a configuration_endpoint to your agent (via the dashboard or the Update Agent endpoint):

{
  "configuration_endpoint": {
    "url": "https://your-server.com/webhooks/agent-config",
    "headers": { "Authorization": "Bearer your-secret" },
    "timeout_ms": 3000
  }
}

• url must be a publicly routable HTTPS URL without embedded credentials.
• timeout_ms must be between 1000 and 20000. Defaults to 3000.

You can also set a configuration_endpoint on an individual custom phone number (see Add Custom Phone Number and Update Phone Number). For inbound calls to that number, the phone number’s endpoint is used instead of the agent’s.

Request payload

Phonic sends a JSON body with the following fields:

{
  "project": { "name": "main" },
  "agent": {
    "name": "support-agent",
    "welcome_message": "Hi, how can I help you today?",
    "voice_id": "sabrina",
    "additional_voice_ids": [],
    "system_prompt": "You are a helpful support assistant.",
    "tools": ["check_order_status", "create_ticket"],
    "tasks": [{ "name": "verify_identity", "description": "Confirm the caller's date of birth." }],
    "boosted_keywords": ["order ID", "tracking number"]
  },
  "template_variables": { "system_conversation_timezone": "America/Los_Angeles" },
  "conversation_id": "conv_abc123",
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543"
}

Response payload

Your endpoint returns a JSON object. Every field is optional — any field you return overrides the agent’s configured value for that conversation, and any field you omit falls back to the agent’s default. Return {} to make no changes. Fields set directly on the conversation (in the WebSocket config or the outbound call request) take precedence over your endpoint’s response.

{
  "welcome_message": "Hey David, how can I help you today?",
  "system_prompt": "You are helping David, a premium customer.",
  "template_variables": { "customer_name": "David" },
  "voice_id": "sabrina",
  "default_language": "en",
  "metadata": { "crm_id": "cus_123" }
}

The response accepts the same configuration fields as the Create Agent endpoint — see it for descriptions of each field. The most commonly used fields are:

Errors

If the endpoint call fails, the conversation ends instead of falling back to the agent’s configuration. The WebSocket is closed with one of these codes:

A voice_id or additional_voice_ids your organization can’t access also ends the conversation.

Example usage

Here’s an example of how to implement the endpoint:

import { Hono } from "hono";
import type { Phonic } from "phonic";
const app = new Hono();
app.post("/webhooks/agent-config", async (c) => {
  const body = (await c.req.json()) as Phonic.PhonicConfigurationEndpointRequestPayload;
  const fromPhoneNumber = body.from_phone_number;
  const fromCustomerName = lookUpCustomerName(fromPhoneNumber); // look up customer in your CRM
  const response: Phonic.PhonicConfigurationEndpointResponsePayload = {
    welcome_message: `Hey ${fromCustomerName}, how can I help you today?`,
  };
  return c.json(response);
});
export default app;