Chat API

Chat Threads, Messages and Participants

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

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.
• The free_text search parameter is required when searching threads.
• Access to threads and messages is restricted based on the user’s eligible client accounts.
• The serialize decorator is used with different serializers (ThreadSerializer, MessageSerializer, ParticipantSerializer) to format the response data.
• Error responses:
  • 403 Forbidden: When trying to access a thread not associated with the user’s eligible client accounts.
  • 404 Not Found: When a specified thread or message doesn’t exist.