---
title: "Send AI chat methods"
method: POST
path: "/api/ai/chat"
tags: ["AI Chat"]
---

# Send AI chat methods

`POST /api/ai/chat`

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](/docs/platform/your-signalwire-api-space).

## Request body

- union — A JSON-RPC request. The `method` field selects which of the six methods runs, and `params` carries that method's arguments. Authenticate with HTTP Basic authentication. `params` contains only the arguments for the selected method; do not put project IDs, API tokens, or Space IDs in the JSON-RPC body.
  - object
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — Your identifier for this request, echoed back on the response so you can match the two.
    - `method` 'create_conversation', required — Creates a conversation, or resets an existing one when `reinit` is set.
    - `params` object, required — The parameters for `create_conversation`.
      - `id` string, required — The conversation this method acts on. You choose the value when you create the conversation, and it is scoped to your project.
      - `config_url` string, uri, required — The publicly reachable URL serving your agent's SWML. `localhost` and private network addresses cannot be reached by SignalWire.
      - `user_message` string — An opening message from the user, sent as part of creating the conversation.
      - `conversation_timeout` integer — Seconds a conversation may sit idle before it ends.
      - `user_meta_data` object — Arbitrary data about the user, included in webhooks generated for this conversation.
      - `reinit` boolean — Reset an existing conversation instead of returning it as-is. Clears the message history.
  - object
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — Your identifier for this request, echoed back on the response so you can match the two.
    - `method` 'chat', required — Sends a message and returns the agent's reply. One request is one full turn, including any tool calls the agent makes along the way, so expect this to take seconds rather than milliseconds.
    - `params` object, required — The parameters for `chat`.
      - `id` string, required — The conversation this method acts on. You choose the value when you create the conversation, and it is scoped to your project.
      - `message` string, required — The message to send.
      - `role` 'user' | 'system' — Who the message is from. A `system` message steers the agent without appearing as something the user said.
      - `config_url` string, uri — Creates the conversation if it does not exist yet, using this SWML. Sending it here means one call instead of two, at the cost of never receiving `initial_message`, so the agent does not speak first.
      - `conversation_timeout` integer — Applies only when this call creates the conversation.
      - `user_meta_data` object — Arbitrary data about the user, included in webhooks generated for this conversation.
      - `reinit` boolean — Applies only when this call creates the conversation.
  - object
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — Your identifier for this request, echoed back on the response so you can match the two.
    - `method` 'end_conversation', required — Ends the conversation and starts post-processing: the summary, and a request to your `post_prompt_url` when your SWML sets one.
    - `params` object, required — The parameters for `end_conversation`.
      - `id` string, required — The conversation this method acts on. You choose the value when you create the conversation, and it is scoped to your project.
  - object
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — Your identifier for this request, echoed back on the response so you can match the two.
    - `method` 'delete', required — Removes the conversation and its messages. Nothing is post-processed and no webhook fires.
    - `params` object, required — The parameters for `delete`.
      - `id` string, required — The conversation this method acts on. You choose the value when you create the conversation, and it is scoped to your project.
  - object
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — Your identifier for this request, echoed back on the response so you can match the two.
    - `method` 'chat_log', required — Reads the conversation back. Changes nothing.
    - `params` object, required — The parameters for `chat_log`.
      - `id` string, required — The conversation this method acts on. You choose the value when you create the conversation, and it is scoped to your project.
  - object
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — Your identifier for this request, echoed back on the response so you can match the two.
    - `method` 'summarize', required — Generates a summary of the conversation on demand. Limited to one call per minute per conversation; over that returns `-32005`.
    - `params` object, required — The parameters for `summarize`.
      - `id` string, required — The conversation this method acts on. You choose the value when you create the conversation, and it is scoped to your project.
      - `summary_prompt` string — How to summarize. Overrides the `post_prompt` text in your SWML for this call only.
      - `temperature` number, float — Sampling temperature for the summary.
      - `top_p` number, float — Nucleus sampling cutoff for the summary.
      - `frequency_penalty` number, float — Penalty applied to tokens by how often they have already appeared.
      - `presence_penalty` number, float — Penalty applied to tokens that have appeared at all.
      - `max_tokens` integer — Longest summary to generate, in tokens.

## Response `200`

The request has succeeded.

- union — A JSON-RPC response. Which result you get follows from the method you sent; a response echoes no `method` of its own. Check the HTTP status first. On HTTP 200, inspect the envelope for an `error` member. HTTP-level errors returned with another status are not JSON-RPC envelopes.
  - AIChatConversationCreatedResponse
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — The `id` from your request.
    - `result` object, required — The conversation that now exists.
      - `status` 'created' | 'reinitialized' | 'exists', required — What happened. `created` for a new conversation, `reinitialized` when `reinit` reset an existing one, and `exists` when one was already there and was left alone.
      - `id` string, required — The conversation id.
      - `initial_message` string, nullable — The agent's opening line, when the agent greets first.
  - AIChatReplyResponse
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — The `id` from your request.
    - `result` object, required — The agent's turn.
      - `response` string, required — The agent's reply. When this call created the conversation, this is the agent's opening message.
      - `user_event` object — An event one of your tools raised for your application to act on, present only when the turn produced one. The contents under `event` are whatever your tool sent, so the shape is yours; the convention is a `type` key your client can switch on.
  - AIChatConversationEndedResponse
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — The `id` from your request.
    - `result` object, required — The outcome of ending the conversation.
      - `status` 'ended' | 'not_found', required — `ended` when the conversation was ended, `not_found` when no conversation had that id.
      - `id` string, required — The conversation id.
  - AIChatConversationDeletedResponse
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — The `id` from your request.
    - `result` object, required — The outcome of deleting the conversation.
      - `status` 'deleted' | 'not_found', required — `deleted` when the conversation was removed, `not_found` when no conversation had that id.
      - `id` string, required — The conversation id.
  - AIChatTranscriptResponse
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — The `id` from your request.
    - `result` object, required — The entries recorded for the conversation.
      - `chat_log` WebhooksAIAICallLogEntry[], required — Every entry in the conversation, in order. Alongside the dialogue this can carry your own prompt and other non-dialogue entries, so filter to `user` and `assistant` before displaying a transcript.
        - `role` string, required — Who produced the entry. Common roles include `system`, `user`, `assistant`, and `tool`. Other roles may appear, so filter to the roles your application uses rather than assuming a fixed set.
        - `content` string, required — The text of the entry.
        - `timestamp` integer — When the entry was added, as a Unix timestamp in microseconds. Omitted on entries without one.
        - `tool_calls` object[] — The tool calls the agent made on this turn. Present only on a turn that made any.
      - `call_timeline` object[] — Structured timeline entries returned for the conversation. The entry shape depends on the events recorded for that conversation.
  - AIChatSummaryResponse — The result of requesting a summary. A generated summary is returned in `summary`. If summary generation fails after the request succeeds, the reason can be returned in `error`; this is not a JSON-RPC error and carries no code.
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — The `id` from your request.
    - `result` object, required — The outcome of summarizing.
      - `summary` string — The generated summary.
      - `error` string — Why no summary was produced.
  - AIChatErrorResponse — A JSON-RPC method failure returned under HTTP 200. After confirming the HTTP status, inspect the envelope for this `error` member.
    - `jsonrpc` '2.0', required — The JSON-RPC version. Always `2.0`.
    - `id` string, required — The `id` from your request.
    - `error` AIChatError, required — A JSON-RPC error returned for the requested method.
      - `code` -32001 | -32002 | -32003 | -32004 | -32005 | -32006 | -32007 | -32600 | -32601 | -32602 | -32603, required — Why a method failed. `-32600` and below are the standard JSON-RPC codes; the rest are specific to AI chat. See [API error codes](/docs/apis/error-codes) for the codes callers should handle and what they mean.
      - `message` string, required — A short description of the failure.

## Other responses

- `400` — The request body was not valid JSON. The response is not a JSON-RPC envelope.
- `401` — Credentials are missing or rejected, the request targets another Space, the token does not include the chat scope, or the account must be verified before using this endpoint.
- `502` — The AI chat service did not respond before the request timed out or could not be reached. This is not a JSON-RPC error and carries no code.

---

[API](https://skmtc.net/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.net/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/revisions/9bdd0e2bdf22/schema)