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):

1
{
2
  "configuration_endpoint": {
3
    "url": "https://your-server.com/webhooks/agent-config",
4
    "headers": { "Authorization": "Bearer your-secret" },
5
    "timeout_ms": 3000
6
  }
7
}

Request payload

Phonic sends a JSON body with the following fields:

1
{
2
  "project": { "name": "main" },
3
  "agent": {
4
    "name": "support-agent",
5
    "welcome_message": "Hi, how can I help you today?",
6
    "system_prompt": "You are a helpful support assistant.",
7
    "tools": ["check_order_status", "create_ticket"],
8
    "boosted_keywords": ["order ID", "tracking number"]
9
  },
10
  "conversation_id": "conv_abc123",
11
  "from_phone_number": "+15551234567",
12
  "to_phone_number": "+15559876543"
13
}

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.

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

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:

Example usage

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

1
import { Hono } from "hono";
2
import type { Phonic } from "phonic";
3
4
const app = new Hono();
5
6
app.post("/webhooks/agent-config", async (c) => {
7
  const body = (await c.req.json()) as Phonic.PhonicConfigurationEndpointRequestPayload;
8
  const fromPhoneNumber = body.from_phone_number;
9
  const fromCustomerName = lookUpCustomerName(fromPhoneNumber); // look up customer in your CRM
10
  const response: Phonic.PhonicConfigurationEndpointResponsePayload = {
11
    welcome_message: `Hey ${fromCustomerName}, how can I help you today?`,
12
  };
13
  return c.json(response);
14
});
15
16
export default app;