Agent Chats API

Endpoints for listing, creating, reading, updating, and deleting agent chat conversations. The list endpoint supports a kind query parameter to split conversations between user-driven chats and AI App runs.

List Agent Chats

Returns a paginated list of the current user's agent chats.

GET/v1/agent-chats

Required Permission: authenticated user (no extra IAM action required to read own chats).

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number, starting at 1.
per_page	integer	20	Items per page (max 100).
exclude_mode	string	—	Comma-separated list of agent-chat modes to exclude (e.g. mini_app_creator,monitor_builder).
kind	string	—	Filter by chat origin. main returns chats started by the user (web or WhatsApp); app returns chats created by AI App executions. Omit for the default behavior (returns both).

When kind is omitted or invalid, the endpoint behaves exactly like in previous releases (back-compat).

Example Request — main chats only:

curl "https://api.console.solucao42.com.br/v1/agent-chats?kind=main&exclude_mode=mini_app_creator,monitor_builder" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Request — AI App runs only:

curl "https://api.console.solucao42.com.br/v1/agent-chats?kind=app" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 200 OK

{
  "total": 42,
  "quantity": 20,
  "records": [
    {
      "id": "65f0a1c8e1c4d23a8f5a7b30",
      "user_id": "65f0a1c8e1c4d23a8f5a7b00",
      "title": "Vendas por região",
      "channel": "web",
      "is_special": false,
      "message_count": 6,
      "created_at": "2026-05-01T13:42:00.000Z",
      "updated_at": "2026-05-02T08:10:00.000Z",
      "mode": "default",
      "mini_app_id": null
    }
  ]
}

The list response is sorted by updated_at descending. WhatsApp chats appear in the same payload as web chats; clients can split them in the UI by checking the channel field.

Errors:

Status	Error Code	Description
401	UNAUTHORIZED	Missing or invalid JWT.
500	AGENT_CHAT_LIST_ERROR	Internal failure listing chats.

Get Agent Chat

Returns a single chat with its visible messages.

GET/v1/agent-chats/{chatId}

Required Permission: authenticated user, and the chat must belong to the requester.

Query Parameters:

Parameter	Type	Description
messages_after	ISO date	When provided, returns only messages newer than this timestamp (incremental sync).

Errors:

Status	Error Code	Description
403	CHAT_ACCESS_DENIED	Chat belongs to another user.
404	CHAT_NOT_FOUND	Chat ID does not exist.

Create Agent Chat

Creates a new agent chat.

POST/v1/agent-chats

Required Permission: visualizations:execute.

Body:

{
  "title": "Optional title",
  "mini_app_id": "65f0a1c8e1c4d23a8f5a7c00"
}

Field	Type	Description
title	string (optional)	Custom title for the conversation.
mini_app_id	string (optional)	When provided, ties the chat to an AI App run. The chat then surfaces in kind=app listings.

Response: 201 Created with the created chat object.

Errors:

Status	Error Code	Description
403	—	Permission visualizations:execute denied.
422	—	Schema validation failed.
500	AGENT_CHAT_CREATE_ERROR	Internal failure creating chat.

Update Title

PUT/v1/agent-chats/{chatId}

Body: { "title": "New title" }. Returns the updated chat.

Delete Chat

DELETE/v1/agent-chats/{chatId}

Soft-deletes the chat. Subsequent list calls will not include it.

Notes on kind

• kind=main: only chats whose mini_app_id is null (web chats and WhatsApp chats).
• kind=app: only chats with mini_app_id set (chats created by AI App executions).
• Omitted: returns both kinds, preserving previous behavior.
• kind and exclude_mode combine: ?kind=main&exclude_mode=mini_app_creator,monitor_builder is the typical query the web console uses to populate the "Principais" tab.