AI Chat
Send AI chat methods
Hold a text conversation with an AI agent. All six methods travel over this endpoint in a JSON-RPC 2.0 body. Put the method name in method and its arguments in params.
Your agent is an SWML document you serve, and config_url is where you serve it. A conversation is a series of turns addressed by an id you choose. A turn is one user message and the agent's reply, including any tool calls made along the way. One request runs one turn.
Methods
| Method | Description |
|---|---|
| create_conversation | Create a conversation, or reset an existing one |
| chat | Send a message and receive the agent's reply |
| end_conversation | End the conversation and trigger post-processing |
| delete | Remove the conversation, with no post-processing |
| chat_log | Read the conversation back |
| summarize | Generate a summary on demand |
Permissions
The API token used to authenticate must have the following scope(s) enabled to make a successful request: Chat.
Learn more about API scopes.
post/api/ai/chat
Request body
Example request
{
"jsonrpc": "2.0",
"id": "req-1",
"method": "create_conversation",
"params": {
"id": "conv-123",
"config_url": "https://your-agent.example.com/swml",
"user_message": "I need help with an order",
"conversation_timeout": 1800,
"user_meta_data": {
"customer_tier": "premium"
},
"reinit": true
}
}Response
The request has succeeded.
Example response
{
"jsonrpc": "2.0",
"id": "req-1",
"result": {
"status": "created",
"id": "conv-123",
"initial_message": "Hi! How can I help?"
}
}