Team

Owner	Lead
Mendy	Tamar

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. By default the user always starts on 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, app, persona, etc.) they can use the @ symbole.

Should they want to take action, they can use / (e.g. /Agenda set a meeting with @Mendy today at 9:00), while the user can use @GoogleCalender to access thier calender app the / inplied intent, both would get the same result but / allows apps to buld 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

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 apps and people it has access to using @? Answer - Each app 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 apps 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

As a busy user I don’t want to watch but rather listen to a podcast, however, when I hear a voice I don’t recognize, I want to take a glance at my phone to see a name and/or photo of who is talking or maybe ask the built-in “AI/assistant”.

Flows

Personas

Features

Below is a list of features that will be utilized in order to deliver the best account 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.

Conversation

A conversation is everything related to one "entity", e.g. with AI, apps, persons or anything else.
- Message
  An individual message within a conversation. (e.g. text, audio, image, etc)
Conversations

A list of all conversations
Direct

Direct is a type of conversation, it involes two "entities" communicating, even if tools or apps and used, the communication purpose is meant for the two people or person to app 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 apps 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
Apps
Actions
Live
Groups
Threads
Chat Suggestions
Post
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 app, mode and more
/

On the document we want to keep all the important data, the first fetch and fast to access, all secondary data should be stored on a subcollection and fetch sepratly (if this is cost sfective)

User Accounts should be a top level collection, each account will generate a new document within the "Accounts" collection.

Messages

- Message
- - Message 1
- - - type (offer a fea 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)
- - - email
- - - number
- - - legal name (if connected wit a / our identity API this will allow for name/identity varification, useful for saftly and fintech and fraud protection)
- - - age (also opcinaly connect with identity api for varification)
- - - dob (also opcinaly connect with identity api for varification)
- - - varified (true, false)
- - - created (date)
- - - timezone
- - - langages
- - - contact detail

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, Apple, 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)

Chat API

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

All chat endpoints require a valid Firebase ID token:

Authorization: Bearer <Firebase ID Token>

`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.app/chat \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Content-Type: application/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 appears 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.app/chat/stream \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Tell me a fun fact about Paris.", "author": "Alice" }
    ]
  }'

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.

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>

Team​

Status​

Description​

Reminders​

Links & Resources​

Research​

Technical​

Business​

User Stories​

Flows​

Personas​

Features​

Conversation​

Message​

Conversations​

Direct​

Symbols​

Actions​

Modes​

Apps​

Actions​

Access​

Messages​

Intelegence​

Identification​

Condissions​

Knowladge​

Envierment​

Preferences​

Chat API

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​

Team

Status

Description

Reminders

Links & Resources

Research

Technical

Business

User Stories

Flows

Personas

Features

Conversation

Message

Conversations

Direct

Symbols

Actions

Modes

Apps

Actions

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