Chat API

Chat threads represent conversations between users, while messages are individual communications within those threads.

Endpoints

Thread Attributes

Message Attributes

Code Blocks in Messages

Messages can contain special code blocks that are processed by the system:

Code Block Processing

1. codeaction blocks:
   • First run in preview mode
   • If no errors and no objects need approval, automatically run in write mode
   • A coderesult block is added after the codeaction block
   • Results are posted as a new message
2. approvecodeaction blocks:
   • Finds the last codeaction block in the thread
   • Runs that block in write mode (is_approved=true)
   • Posts the result as a new message containing only the coderesult block

API Response Format

When retrieving messages, code blocks are handled securely:

• Code content in codeaction and coderesult blocks is hidden with “[code hidden]”
• Preview objects from coderesult blocks are extracted into structured data
• The execution mode is included when available

Example response for a message with processed code blocks:

{
    "id": 123,
    "message": "Let's process this:\n```codeaction\n[code hidden]\n```\n```coderesult\n[code hidden]\n```",
    "action_items": [
        {
            "type": "preview",
            "needs_approval": true,
            "id": 1
        }
    ],
    "action_mode": "preview"
}

Example of an approval message:

{
    "id": 124,
    "message": "```approvecodeaction\n```",
    "action_items": [],
    "action_mode": null
}

Example of the result message after approval:

{
    "id": 125,
    "message": "```coderesult\n[code hidden]\n```",
    "action_items": [
        {
            "type": "preview",
            "needs_approval": false,
            "id": 1
        }
    ],
    "action_mode": "write"
}

Participant Attributes

Query Parameters

The GET /chat/threads endpoint accepts the following query parameters. All filters are optional. When client_account_id is omitted, threads are returned across all of the user’s eligible client accounts.

Search Examples

Search threads by text content:

GET /api/v2/chat/threads?free_text=invoice

This will return threads where either:

• The thread subject contains “invoice”
• Any message in the thread contains “invoice”

The search is case-insensitive and matches partial words. You can combine search with other filters:

GET /api/v2/chat/threads?free_text=invoice&client_account_id=123&relation_type=document

Relationships

Notes

• All endpoints require authentication.
• All filter parameters on GET /chat/threads are optional. Use free_text only when you need full-text search across thread subjects and messages.
• Access to threads and messages is restricted based on the user’s eligible client accounts. Access is granted if the user can access either the thread’s client_account_id or its provider_client_account_id.
• Error responses:
  • 403 Forbidden: When trying to access a thread the user is not associated with.
  • 404 Not Found: When a specified thread or message doesn’t exist.