Skip to main content
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.
Agent API is the product name. The API uses custom_channel as its backend channel type and endpoint identifier.
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

Quickstart

Create a channel, sign a customer-message event, and send it to Sagepilot.

Receiving replies

Verify signed reply callbacks and process the public event payload.