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
  }
}

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?",
    "system_prompt": "You are a helpful support assistant.",
    "tools": ["check_order_status", "create_ticket"],
    "boosted_keywords": ["order ID", "tracking number"]
  },
  "conversation_id": "conv_abc123",
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543"
}

project

objectRequired

The project the conversation belongs to. Contains name (string).

agent

objectRequired

A subset of the Agent for this conversation. Contains name, welcome_message, system_prompt, tools (tool names as strings), and boosted_keywords.

conversation_id

stringRequired

Unique ID for the conversation.

from_phone_number

string

Caller’s phone number in E.164 format. Present for inbound phone calls.

to_phone_number

string

Phone number that was called in E.164 format. Present for inbound phone calls.

twilio_call_sid

string

Present when using SIP trunking with a custom phone number — the Twilio Call SID in your Twilio environment.

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.

{
  "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:

welcome_message

string | null

Message to play when the conversation starts. Can contain template variables. Ignored when generate_welcome_message is true.

system_prompt

string

Instructions for the conversation. Can contain template variables.

template_variables

object

Key-value pairs of template variables used in the welcome message and system prompt.

voice_id

string

The voice ID to use for the agent. See voices.

tools

string[]

Built-in or custom tool names to make available to the assistant.

default_language

string

ISO 639-1 language code that sets the agent’s default language.

additional_languages

string[]

Additional ISO 639-1 language codes the agent should recognize and speak.

metadata

object

Arbitrary key-value metadata to associate with the conversation.

The following fields are not accepted in the response, since they don’t apply once a conversation is starting: agent, project, outbound_number_pool, and configuration_endpoint.

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;