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

# Agent API

> Run Sagepilot AI agents and human support agents inside any channel or app you own.

The Agent API turns a surface you control — such as a mobile app, support portal, kiosk, or IVR deflection flow — into a Sagepilot support channel. Your backend sends customer-message events to Sagepilot, and Sagepilot delivers AI or human-agent replies to an HTTPS callback you configure.

<Note>
  **Agent API** is the product name. The API uses `custom_channel` as its backend channel type and endpoint identifier.
</Note>

Agent API V1 is asynchronous. The inbound request is acknowledged after Sagepilot authenticates, validates, and accepts the customer message. Replies arrive later as signed `support.message.created` webhook events.

## How it works

1. Create an **Agent API** channel in the Sagepilot dashboard, select the default AI agent, and enter your HTTPS response URL.
2. Save the one-time signing key shown during channel creation. Sagepilot cannot show it again.
3. Send each customer message to the shared `POST /webhooks/custom_channel` endpoint. Include the channel ID in the signed JSON body.
4. Sagepilot resolves the customer from `customer.external_id`, manages the internal chat, and processes the message through its normal inbox and AI-assignment flow.
5. Sagepilot sends eligible AI and human-agent replies to your response URL as signed webhook events.

The same signing key serves two purposes:

* Your backend signs inbound requests to Sagepilot.
* Your backend verifies reply callbacks sent by Sagepilot.

## Identity and conversations

`customer.external_id` is your stable customer identifier and must be unique within the Sagepilot workspace. Optional customer details such as name, email, phone, and Instagram identifiers belong in `customer.properties`; Sagepilot never uses those mutable properties as identity keys.

Do not send a conversation ID, thread ID, or chat ID. Sagepilot manages chats internally using the customer, workspace, channel, and the normal reopen policy. Reply callbacks include Sagepilot's resolved `payload.chat_id` so your system can correlate delivered replies, but that value is output-only and must not be sent back in inbound events.

## Attachments

Inbound messages can contain text, attachments, or both. Each attachment must be available at a directly downloadable HTTPS URL that requires no authentication. Sagepilot validates and copies the file into Sagepilot-owned storage before processing the message.

Reply callbacks contain safe attachment metadata and a short-lived Sagepilot download URL. They never expose internal storage keys or the original client URL.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" href="/api-reference/agent-api/quickstart">
    Create a channel, sign a customer-message event, and send it to Sagepilot.
  </Card>

  <Card title="Receiving replies" href="/api-reference/agent-api/receiving-replies">
    Verify signed reply callbacks and process the public event payload.
  </Card>
</CardGroup>