Sign in
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.

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

MethodDescription
create_conversationCreate a conversation, or reset an existing one
chatSend a message and receive the agent's reply
end_conversationEnd the conversation and trigger post-processing
deleteRemove the conversation, with no post-processing
chat_logRead the conversation back
summarizeGenerate 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

OR
OR
OR
OR
OR

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.

OR
OR
OR
OR
OR
OR

Example response

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

Changes

Changed in 6 of the 137 revisions of this API.49

  • 7a9eb5f678551See the full diff
    • ○

      endpoint added

      endpoint-added

  • 51e63ae4cf551See the full diff
    • ▲

      api path removed without deprecation

      api-path-removed-without-deprecation

    This revision's changelog hit the recording limit, so it may not list every change to this endpoint.

    This revision also has 26 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9bdd0e2bdf223See the full diff
    • ○

      removed the -32008.00 enum value from the anyOf[subschema #7: Error]/error/allOf[AI.ChatError]/code/allOf[AI.ChatErrorCode]/ response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the -32009.00 enum value from the anyOf[subschema #7: Error]/error/allOf[AI.ChatError]/code/allOf[AI.ChatErrorCode]/ response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the -32700.00 enum value from the anyOf[subschema #7: Error]/error/allOf[AI.ChatError]/code/allOf[AI.ChatErrorCode]/ response property for the response status 200

      response-property-enum-value-removed

  • e5d4dae4f5a023See the full diff
    • ▲

      response property anyOf[subschema #1: create_conversation result]/result/initial_message list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      removed the required property error from the response with the 401 status

      response-required-property-removed

    • ○

      added the media type text/plain for the response with the status 401

      response-media-type-added

    • ○

      added the non-success response with the status 400

      response-non-success-status-added

    • ○

      added the required property message to the response with the 401 status

      response-required-property-added

  • 01d732c5786c11See the full diff
    • ▲

      the anyOf[subschema #7: Error]/error/allOf[AI.ChatError]/code response's property type/format changed from integer/int32 to / for status 200

      response-property-type-changed

    • ○

      added AI.ChatErrorCode to the anyOf[subschema #7: Error]/error/allOf[AI.ChatError]/code response property allOf list for the response status 200

      response-property-all-of-added

  • 007d2d29c6b21See the full diff
    • ○

      endpoint added

      endpoint-added

Of the 137 revisions, 3 have a changelog that could not be searched.