> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agnost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentPhone

> Send completed AgentPhone calls to Agnost AI

Agnost AI accepts AgentPhone's `agent.call_ended` webhook and turns each completed call into a conversation with an event for every caller and agent exchange. AgentPhone already provides the transcript, so Agnost AI does not run speech-to-text again. No SDK or code change is needed.

This integration is for agents that use AgentPhone's **built-in voice** (`voiceMode: "hosted"`), where AgentPhone's own LLM answers calls from the agent's instructions. A webhook-mode agent needs its webhook to answer every caller turn, so Agnost AI cannot take that webhook's place.

Setup takes about five minutes.

## 1. Get your organization ID

Sign in to [app.agnost.ai](https://app.agnost.ai), open **Settings**, and copy the **Organization ID** under **General**. It is a UUID.

![Agnost Settings page with the Organization ID under General](https://mintcdn.com/agnostai/heJpwewM3t2BJDIr/images/agentphone/agnost-org-id.png?fit=max\&auto=format\&n=heJpwewM3t2BJDIr\&q=85\&s=1990d479016c0d79d24b16fc552bffd3)

Settings → General → Organization ID

## 2. Check that the agent uses built-in voice

In the [AgentPhone dashboard](https://agentphone.ai/agents), open the agent. **Built-in voice** appears under its name. Through the API, `GET /v1/agents/<agent-id>` returns `"voiceMode": "hosted"`.

If the agent does not use built-in voice, stop here: its webhook answers your callers and must stay pointed at your server.

![AgentPhone agent page showing Built-in voice under the agent name](https://mintcdn.com/agnostai/heJpwewM3t2BJDIr/images/agentphone/agentphone-built-in-voice.jpg?fit=max\&auto=format\&n=heJpwewM3t2BJDIr\&q=85\&s=047483e89fd0b7f669baff5dc2067fa4)

Built-in voice appears under the agent's name

## 3. Connect the agent's webhook to Agnost AI

Build your webhook URL:

```text theme={null}
https://api.agnost.ai/api/voice/v1/webhooks/agentphone?org_id=<your-agnost-org-id>&agent_name=<display-name>
```

`agent_name` is optional and must be URL-encoded, for example `Front%20Desk`. Without it, the AgentPhone agent ID becomes the agent name in Agnost AI.

Then set it as the agent's own webhook, in either place:

* **Dashboard:** open the agent, select **Connections**, and under **Agent Webhook** select **Configure**. Paste the URL into **Webhook URL** and select **Save**.

  ![AgentPhone Connections tab with the Agnost URL in the Agent Webhook URL field](https://mintcdn.com/agnostai/heJpwewM3t2BJDIr/images/agentphone/agentphone-agent-webhook.jpg?fit=max\&auto=format\&n=heJpwewM3t2BJDIr\&q=85\&s=357ea0aad6dbd7d73e761c0deb036c89)

  Connections → Agent Webhook → Webhook URL

* **API:**

  ```bash theme={null}
  curl -X POST "https://api.agentphone.ai/v1/agents/<agent-id>/webhook" \
    -H "Authorization: Bearer $AGENTPHONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "<your-webhook-url>"}'
  ```

An agent webhook overrides the project webhook for that agent only, so your other agents keep their current webhook. If every agent in the project uses built-in voice, you can set the project webhook on the **Webhooks** page, or with `POST /v1/webhooks`, using the same URL without `agent_name`.

AgentPhone also sends SMS and other messages for this agent to the same webhook. Agnost AI acknowledges them but does not reply, so connect only voice numbers to this agent.

## 4. Send a test event

```bash theme={null}
curl -X POST "https://api.agentphone.ai/v1/agents/<agent-id>/webhook/test" \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

A working connection returns `{"success":true,"httpStatus":204,...}`. Agnost AI acknowledges test events without creating a conversation.

## 5. Place a call and find it in Agnost AI

Call one of the agent's numbers, or start a browser web call. Agnost AI receives the call when it ends, so the conversation appears a few seconds after hang-up.

In [app.agnost.ai](https://app.agnost.ai), open **Users**. Each call is a session for the caller's number, with the full transcript in the conversation panel.

![An AgentPhone call in Agnost with intents tagged on caller messages and one rule violation](https://mintcdn.com/agnostai/heJpwewM3t2BJDIr/images/agentphone/agnost-conversation.png?fit=max\&auto=format\&n=heJpwewM3t2BJDIr\&q=85\&s=cb9845df618cb46446158f1583befbee)

A completed AgentPhone call, with intents and a violation

The conversation's **Metadata** tab shows AgentPhone's call details, such as the agent, call ID, status, direction, disconnection reason, and duration.

![Metadata tab showing AgentPhone call details](https://mintcdn.com/agnostai/heJpwewM3t2BJDIr/images/agentphone/agnost-conversation-metadata.png?fit=max\&auto=format\&n=heJpwewM3t2BJDIr\&q=85\&s=f51957cb52018d9c385f65a21e9e7c6f)

AgentPhone call details in the Metadata tab

## 6. Add intents and rules

Agnost AI tags caller messages with your intents and checks agent turns against your rules. Create them on the **Intents** and **Violations** pages, for example a "Reschedule appointment" intent or a rule that the agent must confirm a callback number before ending a call. Agnost AI classifies each call automatically about 15 minutes after it ends.

![Intents page counting AgentPhone caller messages per intent](https://mintcdn.com/agnostai/heJpwewM3t2BJDIr/images/agentphone/agnost-intents.png?fit=max\&auto=format\&n=heJpwewM3t2BJDIr\&q=85\&s=6beb70d270bd979ccd202b3358ac8237)

Intent matches from AgentPhone calls

## Troubleshooting

* **The test event fails:** check that the URL starts with `https://api.agnost.ai` and that `org_id` is a valid UUID.
* **AgentPhone shows `422` for the agent's deliveries:** the agent is in webhook mode, and Agnost AI cannot answer its live voice turns. Point that webhook back at your server.
* **The test passes but calls do not appear:** check that `org_id` matches the organization selected in Agnost AI, and that the call reached at least one transcript turn. Calls with no transcript are not captured.

## Data mapping

* `data.callId` becomes the Agnost AI conversation ID.
* The caller number (`from` on inbound calls, `to` on outbound calls) becomes the user ID. Browser web calls have no phone number and fall back to the call ID.
* `transcript` turns with the `user` or `agent` role become caller and agent exchanges.
* `startedAt` anchors the conversation start time.
* `summary`, `userSentiment`, and `callSuccessful` (when AgentPhone provides them), plus `status`, `disconnectionReason`, direction, number, agent ID, and timing, become conversation metadata.
* A `recordingUrl` with an `http` or `https` scheme, when present, becomes the conversation recording.

AgentPhone does not send per-turn timestamps. Agnost AI spreads the turns across the call duration in proportion to their length and marks the conversation with `transcript_timing: estimated`, so per-exchange durations for AgentPhone calls are approximate.

The `agent.call_ended` payload does not include tool calls or call cost, so AgentPhone conversations have no tool events or cost data.

## Delivery behavior

Captured calls return `200`. Agnost AI returns `204` for messages, reactions, number releases, test events, and calls without a transcript. A live voice turn (`agent.message` on the `voice` channel) returns `422`, because it means a webhook-mode agent is pointed at Agnost AI and its callers hear silence. Invalid payloads return `400`, and downstream ingestion failures return `502`.

AgentPhone sends `agent.call_ended` once and does not retry it. A call whose delivery fails is not captured.

AgentPhone signs each delivery with `X-Webhook-Signature`. Verifying it requires storing each organization's AgentPhone webhook secret, so this initial integration follows the same organization-routing trust model as the other voice webhook adapters and does not verify the signature. Treat the webhook URL as sensitive until per-organization signature verification is available.

## Next steps

* [Conversations](https://docs.agnost.ai/using-conversations.md): review complete AgentPhone calls.
* [Events](https://docs.agnost.ai/using-events.md): inspect each caller and agent exchange.
* [Intents](https://docs.agnost.ai/using-intents.md): understand why callers contacted the agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.