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.

Use this endpoint from a server when a text conversation should run against an AI agent's SWML and return each turn synchronously. It is separate from the channel-based Chat service: Chat Tokens authorize Chat clients but do not create or advance AI conversations.

Methods

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.

{
  "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
  }
}

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "status": "created",
    "id": "conv-123",
    "initial_message": "Hi! How can I help?"
  }
}