> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.phonic.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.phonic.ai/_mcp/server.

# 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](/api-reference/agents/update) endpoint):

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

```json
{
  "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`** `object` — required

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

---

**`agent`** `object` — required

A subset of the [Agent](/api-reference/agents/get) for this conversation. Contains `name`,
`welcome_message`, `system_prompt`, `tools` (tool names as strings), and `boosted_keywords`.

---

**`conversation_id`** `string` — required

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.

```json
{
  "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](/api-reference/agents/create)
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](/docs/build/agents/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.

---

> **Note**
>
> 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:

```typescript
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;
```

```python
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/webhooks/agent-config")
async def agent_config(request: Request) -> JSONResponse:
    body = await request.json()
    from_phone_number = body["from_phone_number"]
    from_customer_name = look_up_customer_name(from_phone_number)  # look up customer in your CRM
    response = {
        "welcome_message": f"Hey {from_customer_name}, how can I help you today?",
    }
    return JSONResponse(content=response)
```