---
title: "Send a chat turn to an agent"
method: POST
path: "/agents/{agentId}/chat"
tags: ["Chat"]
---

# Send a chat turn to an agent

`POST /agents/{agentId}/chat`

## Request

- Base URL: `https://app.communicate.so/api/v1`
- URL: `https://app.communicate.so/api/v1/agents/{agentId}/chat`
- Auth: one of:
  - OAuth 2 (client credentials, token URL `https://app.communicate.so/api/v1/oauth/token`, scopes: `chat:write`)
  - HTTP bearer

Creates or continues an API-channel conversation and returns one complete response payload. This endpoint does not stream. `requestId` is optional idempotency; reusing it with different input yields `409 request_id_conflict`. Chat turns are additionally rate-limited to 60 requests per minute per key. Responses may include grounded citations and, when an action ran, `actionName`.

## Path parameters

- `agentId` string, required

## Request body

- ChatRequest
  - `message` string, required: End-user prompt sent to the agent.
  - `requestId` string, uuid: Optional idempotency key for safe retries of the same chat input.
  - `conversationId` string, nullable: Continue an existing API-channel conversation when present.

## Response `200`

Completed non-streaming chat response

- ChatResponse
  - `conversationId` string, required
  - `ticketNumber` integer, nullable
  - `messageId` string, required
  - `userMessageId` string, required
  - `answer` string, required
  - `citations` Citation[], required
    - `sourceId` string, required
    - `title` string, required
    - `snippet` string, required
    - `url` string, nullable, required
  - `mode` 'ai' | 'human', required
  - `actionName` string: Present when a workspace action produced the final answer.
  - `followUps` string[]: Optional suggested next questions returned with the answer.

## Other responses

- `400`: Malformed JSON or invalid request body
- `401`: Missing or invalid API key
- `402`: Chat generation is unavailable because billing is paused or credits are exhausted
- `403`: Credential does not grant `chat:write`
- `404`: Agent not found in the API key workspace
- `409`: Agent is inactive, or requestId was replayed with different input
- `429`: API key rate limit exceeded
- `500`: Unexpected server failure
- `503`: Agent is mid-transfer and temporarily unavailable

---

[API](https://skmtc.dev/communicate/apis/communicate-public-rest-api-2.md) · [All operations](https://skmtc.dev/communicate/apis/communicate-public-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/communicate/apis/communicate-public-rest-api-2/revisions/db6be3d36733?raw)