Messages

Send a message

Sends a visitor message to an agent and returns the agent's reply, the sources it used and any actions it triggered. Use this to put your agent inside your own app, Slack bot or support tool.

POSThttps://api.sitewise.ai/v1/agents/{agent_id}/messages

Authentication

Pass your secret key as a Bearer token. Keys are scoped to a workspace and can be created in Settings → API keys.

Keep secret keys on the server

Never expose sk_live keys in browser code. For client-side chat, use the public embed script instead.

Path parameters

agent_id stringrequiredThe ID of the agent, e.g. agt_7Hq2k. Find it in Settings → General.

Body parameters

message stringrequiredThe visitor's message. Maximum 4,000 characters.

conversation_id stringoptionalContinue an existing conversation. Omit to start a new one.

visitor objectoptionalOptional visitor details — email, name and custom metadata — used for lead capture and personalization.

stream booleanoptionalIf true, the reply is streamed as server-sent events. Defaults to false.

mode enumoptionalControls whether the agent may take actions during this reply. One of: answer_only, allow_actions.

Response

id stringUnique ID of the reply message.

reply stringThe agent's answer in Markdown.

sources arrayPages and files the answer was grounded in, with URLs and titles.

actions arrayActions triggered, such as lead.captured or meeting.booked.

Rate limits

Each workspace can send 60 requests per minute per agent. When you exceed it you'll get a 429 with a retry_after value in seconds.