Team

Owner	Lead
Serget	Artom

Status

Doc Status	Feature Status	Last Update	Version	Release	Phase
In Progress	In Progress	-	0.00	Internal	Alpha

Description

Because Colibri is an AI product, the entire platform boils down to chat, while there are hundres of features baked into the platform, the way the user will access it all is through Chat or the Flows Sheet. By default the user always starts on the Start State within the Chat view and starting a new thread within the Colibri Conversation, this means, while the screen is empty and loogs like a new conversation, it is in reality simply a new thread, only one conversation can exsist per entity or connection.

Should the user want to start a conversation with another entity (e.g. person, Flow, persona, etc.) they can use the @ Symbole.

Should they want to take action, they can use / Symbole (e.g. /Agenda set a meeting with @Mendy today at 9:00), while the user can use @GoogleCalender to access thier calender Flow the / inplied intent, both would get the same result but / allows Flows to build spesifict actions and @ leave it to AI to determin intent.

See the Features section to get a full idea of everything Chat is capable of.

Reminders

Links & Resources

**Design

Web
Mobile

**Branches

Alpha (Coming soon)
Beta (Coming soon)
Production (Coming soon)

Research

note

the research listed here is spesifict to the Chat feature, for research related to the general Colibri development see the Research document.

Technical

Question - How does Chat know all the Flows and people it has access to using @? Answer - Each Saved Flow type will have a uniqe username just like users do, however to not overwhlm the user and for securaty each user will have a list of username references to ensure they only find contacts they uploaded, had communication with alredy and Flows they have "installed" or used before.

Question - Answer -

Conclusion - How do we get data from arenas to form the arena layout and map the devices?

Sources

[test]

Business

User Stories

Persona One

Update Coming Soon

Flows

Personas

Features

Below is a list of features that will be utilized in order to deliver the best Chat features and functionalities. The details bellow are not comprehensive feature details but rather, describe how the features will be utilized within the account, for further details, please see the individual feature documentation.

Conversations

A list of all conversations
Conversation

A conversation is everything related to one "entity", e.g. with AI, Flows, Persons or anything else.
- Message
  
  An individual message within a conversation. (e.g. text, audio, image, etc)
  - Direct
    
    Direct is a type of conversation, it involes two "entities" communicating, even if tools or Flows and used, the communication purpose is meant for the two people or person to Flow to communicate. Send direct messages using device contacts, usernames, email, numbers, or other unique identifiers.
  - Symbols
  Use symbols liek @, /, :, + and other to access advances features within Chat.
- Actions
  
  Create an api to allow Flows to add thier own actions in the place of the voice and live actions
Modes

Allow the user to chnage to diferent modes or create thier own modes
Flows
Live
Groups
Threads
Suggestions
Auto Complete Compelete or elaborate on the users' prompe/message to improve the promt for AI or to make it more clear for other users depending on what is types and who is part of the conversation.
Post When writing in a group allow the user to create a post or use the /post action, this will chnage the message UI.
Access

If the account type is not "indiviual" the account will not have an auth method and thefore will reqesre access. This will be a sub-collection within the account document that will hold the account, group, etc IDs of anyone who has access to this account.
@

In any chat the user can use the @ symbole to mention a user by name, username, number or email, they can mention an Flow, mode and more
/

Messages

- Content
- - Content 1
- - - type (Text, thread, Audio, Post, Immage, Attchment, emoji, etc) (offer a few default options that the client can configure as well as custome options or offer numbered types and allow te client to give each type a title, this will enable the client to offer difrent feature or access levels based on account types)
- - - encryption 
  - - - status (true, false)
  - - - code
  - - - type
- - - created (date)
- - - modified
  - - - status (true, false)
  - - - timestampe
  - - - userId
  - - - previusViersion
- - - timezone
- - - langages
- - - transcription
- - - assetLink
- - - threadId
- - - replyToId

{
  "reply": "Alice and Bob, here are the top dishes to try in Paris...",
  "message": {
    "id": "1740000000000",
    "role": "assistant",
    "content": "Alice and Bob, here are the top dishes to try in Paris...",
    "timestamp": "2026-03-03T12:00:00.000Z"
  }
}

Intelegence

    - names
    - - name 1
    - - - type (legal, nicname, madename, etc)
    - - - name
    - - - laguadge
    - - - created (date)
    - - - varified (true, false)
    - - - varified source (api id)

Identification

    - id
    - - id 1
    - - - type (licence, passport, health card, etc)
    - - - issuer (US gov)
    - - - id number
    - - - status: verified
    - - - issued (date)
    - - - experation (date)
    - - - Verify provider: (api id)
    - - - Verify date: log id
    - - - image
    - - - id_proof`

Condissions

    - Sessions
    - - Section #1
    - - - auth type (OTP, Google, Flowle, Normal)
    - - - device_type (Android, IOS, Web)
    - - - device_token
    - - - location
    - - - activated (date)
    - - - status (active, inactive)
    - - - inactive (date)

Knowladge

Envierment

location
mood
tone

Preferences

- prefrences
- - communication
    - - - method (push, email, text)
    - - - default (true, false)
    - - - allow (true, false)
    - - - block (true, false)
    - - - level (all, update, security, system)
    - - - channels (id, id, id)
    - - privacy
    - - - allow (true, false)
    - - - block (true, false)
    - - - allow user data collection (true, false)
    - - - allow user data share (true, false)
    - - - allow user data anonymize (true, false)
    - - - allow user data deletion (true, false)

Endpoint

//move to details doc

Base URL: https://colibri-api-643619291153.me-west1.run.Flow

All chat endpoints require a valid Firebase ID token:

Authorization: Bearer <Firebase ID Token>

// update name to conversation and move to the convo doc

`POST /chat`

Sends the full message history and returns the AI response as a single JSON object.

Request

{
  "messages": [
    { "role": "user",      "content": "Hello!",                    "author": "Alice" },
    { "role": "assistant", "content": "Hi! How can I help?" },
    { "role": "user",      "content": "What should we eat in Paris?", "author": "Bob" }
  ]
}

Field	Type	Required	Description
`role`	`string`	✅	`user`, `assistant`, or `system`
`content`	`string`	✅	Message text. Max 10 000 characters
`author`	`string`	❌	Display name of the sender. When multiple distinct authors are present the AI receives a group-chat context and addresses users by name

Limits: max 50 messages per request.

Response `200`

{
  "reply": "Alice and Bob, here are the top dishes to try in Paris...",
  "message": {
    "id": "1740000000000",
    "role": "assistant",
    "content": "Alice and Bob, here are the top dishes to try in Paris...",
    "timestamp": "2026-03-03T12:00:00.000Z"
  }
}

curl example

curl -X POST https://colibri-api-643619291153.me-west1.run.Flow/chat \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Content-Type: Flowlication/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Tell me a fun fact about Paris.", "author": "Alice" }
    ]
  }'

`POST /chat/stream`

Sends the full message history and streams the AI response chunk-by-chunk via Server-Sent Events (SSE).

Use this endpoint to show the "typing" effect in the UI — text Flowears word by word as Gemini generates it, instead of waiting for the full response.

Request

Same JSON body as POST /chat, including optional author field.

Response headers

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Response body — SSE event stream

data: Alice and Bob,

data:  here are the top dishes

data:  to try in Paris...

data: [DONE]

Each data: <chunk> line is a text fragment delivered as soon as Gemini produces it.
data: [DONE] signals the end of the stream — the connection closes after this.

curl example

# -N disables output buffering so chunks print as they arrive
curl -N -X POST https://colibri-api-643619291153.me-west1.run.Flow/chat/stream \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Content-Type: Flowlication/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Tell me a fun fact about Paris.", "author": "Alice" }
    ]
  }'

// rename to group and move to the group doc

Multi-user chat

When messages from multiple authors are included in a single request, the server automatically:

Tells the AI it is in a group chat with those users (systemInstruction).
Prefixes each message with the sender's name so the AI can track who said what.

{
  "messages": [
    { "role": "user", "content": "Hey Alice, have you been to France?",       "author": "Bob" },
    { "role": "user", "content": "Not yet! AI, what should we try there?",    "author": "Alice" }
  ]
}

The AI addresses both users by name in its response.

// what hFlowens when there are more than two?

Limits & timeouts

Parameter	Value
Max messages per request	50
Max message length	10 000 characters
Rate limit	10 requests / 60 seconds per user
Connect timeout	30 s
Response timeout	30 s

Error codes

Code	Meaning
`400`	Invalid JSON body
`401`	Missing or invalid Firebase token
`405`	Wrong HTTP method (only POST allowed)
`422`	Validation error — check `message` field in response body
`429`	Rate limit exceeded — see `Retry-After` header
`500`	Unexpected server error
`502`	Cloud Run / upstream error (retry)
`504`	Gemini API timeout

Error response body:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 10 requests per 60 seconds."
}

Rate-limit response headers:

Retry-After: 60
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: <unix ms>

Error codes

Code	Meaning
`400`	Invalid JSON body
`401`	Missing or invalid Firebase token
`405`	Wrong HTTP method (only POST allowed)
`422`	Validation error — check `message` field in response body
`429`	Rate limit exceeded — see `Retry-After` header
`500`	Unexpected server error
`502`	Cloud Run / upstream error (retry)
`504`	Gemini API timeout

Error response body:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 10 requests per 60 seconds."
}

Rate-limit response headers:

Retry-After: 60
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: <unix ms>

Team​

Status​

Description​

Reminders​

Links & Resources​

Research​

Technical​

Business​

User Stories​

Flows​

Personas​

Features​

Conversations​

Conversation​

Message​

Direct​

Symbols​

Actions​

Modes​

Flows​

Access​

Messages​

Intelegence​

Identification​

Condissions​

Knowladge​

Envierment​

Preferences​

Endpoint

POST /chat​

Request​

Response 200​

curl example​

POST /chat/stream​

Request​

Response headers​

Response body — SSE event stream​

curl example​

Multi-user chat​

Limits & timeouts​

Error codes​

Error codes​

Related​

Team

Status

Description

Reminders

Links & Resources

Research

Technical

Business

User Stories

Flows

Personas

Features

Conversations

Conversation

Message

Direct

Symbols

Actions

Modes

Flows

Access

Messages

Intelegence

Identification

Condissions

Knowladge

Envierment

Preferences

`POST /chat`

Request

Response `200`

curl example

`POST /chat/stream`

Request

Response headers

Response body — SSE event stream

curl example

Multi-user chat

Limits & timeouts

Error codes

Error codes

Related