Chat API

Chat Threads, Messages and Participants

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

Endpoints

Method	Endpoint	Description
GET	/chat/threads	List chat threads
POST	/chat/threads	Create a new chat thread
GET	/chat/threads/{thread_id}	Get a specific chat thread
POST	/chat/threads/{thread_id}/messages	Add a message to a chat thread
PATCH	/chat/threads/{thread_id}/messages/{message_id}	Update a message in a chat thread
GET	/chat/threads/{thread_id}/participants	Get participants of a chat thread
POST	/chat/threads/{thread_id}/participants	Add a participant to a chat thread

Thread Attributes

Attribute	Type	Description
id	integer	The ID of the chat thread or message
client_account_id	integer	The client account ID associated with the thread
provider_client_account_id	integer	The provider client account ID associated with the thread
relation_type	string	The type of relation associated with the thread
relation_id	integer	The ID of the relation associated with the thread
created_by_id	integer	The ID of the user who created the thread or message

Message Attributes

Attribute	Type	Description
id	integer	The ID of the message
thread_id	integer	The ID of the chat thread associated with the message
message	string	The content of the message
created_at	string	The date and time when the message was created
created_by_id	integer	The ID of the user who created the message
action_items	array	List of preview objects from coderesult blocks
action_mode	string	The execution mode from coderesult blocks (preview/write)

Code Blocks in Messages

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

Block Type	Description
codeaction	Executable code blocks that perform actions. Initially run in preview mode. If no approval is needed, automatically run in write mode.
approvecodeaction	Approval blocks that trigger write-mode execution of the previous codeaction block. The result is posted as a new message.
coderesult	Result blocks containing execution output and preview objects. Generated automatically after processing codeaction blocks.

Code Block Processing

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
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

Attribute	Type	Description
id	integer	The ID of the participant
thread_id	integer	The ID of the chat thread associated with the participant
user_id	integer	The ID of the user associated with the participant

Query Parameters

Parameter	Type	Description
client_account_id	integer	Filter threads by client account ID
provider_client_account_id	integer	Filter threads by provider client account ID
relation_type	string	Filter threads by relation type
relation_id	integer	Filter threads by relation ID
free_text	string	Search threads by subject or message content
order_by	string	Specify the order of returned threads
page	integer	The page number for paginated results (default: 1)
per_page	integer	The number of items per page (default: 100)

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

Relationship	Type	Description
messages	[Message]	The messages in a chat thread
participants	[Participant]	The participants in a chat thread

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.