Agent Chats Integration Guide

This guide walks through using the Agent Chat API to list, create, and segment conversations between user-driven chats and AI App runs.

Use cases

• Build a custom UI that mirrors the console's "Main" / "Apps" tabs.
• Sync conversation history into your own analytics or CRM.
• Trigger and read the result of an AI App run programmatically.

Authentication

All requests require a Bearer JWT obtained through /v1/auth/login or /v1/auth/api-key. See the Authentication guide.

Routing chats by origin

A chat's mini_app_id field decides which tab it belongs to in the console UI.

The same approach works for any external client that wants to keep AI App runs separate from user-initiated conversations.

End-to-end example

1. Create a chat tied to an AI App.

   curl -X POST https://api.console.solucao42.com.br/v1/agent-chats \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"mini_app_id":"65f0a1c8e1c4d23a8f5a7c00"}'

2. List only AI App chats.

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

3. List only user-driven chats and exclude special "builder" modes.

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

4. Read a single chat's messages.

   curl "https://api.console.solucao42.com.br/v1/agent-chats/$CHAT_ID" \
     -H "Authorization: Bearer $TOKEN"

Best practices

• Always send exclude_mode=mini_app_creator,monitor_builder together with kind to avoid surfacing internal builder conversations to end users.
• Treat kind=main and kind=app as separate paginated streams in your UI.
• A chat's origin is immutable; you cannot move a chat between tabs once it has been created.
• Omitting kind is back-compat for existing integrations and returns both kinds in the same payload.

Error handling

Scenario	HTTP	Response
Missing/expired JWT	401	{ "error": "Unauthorized" }
Listing failure	500	{ "error_code": "AGENT_CHAT_LIST_ERROR" }
Reading another user's chat	403	{ "error_code": "CHAT_ACCESS_DENIED" }
Chat not found	404	{ "error_code": "CHAT_NOT_FOUND" }

For schema details, see the Agent Chats API reference.