Teams

Share your TelegramOS workspace with teammates using four ranked roles, per-member permission overrides and an append-only audit log.

A team is a shared workspace. Members work on the team owner's accounts, inbox, automation, bots and analytics with whatever their role allows, without sharing the owner's login. Teams are managed at Settings > Team.

Creating a team and inviting members require a plan with the team capability (Growth and Agency; the 7-day trial includes it). Members can be on any plan, including Free. Listing members, changing roles and leaving a team are never plan-gated.

Roles

Roles are ranked: viewer < operator < admin < owner. Each role has a fixed default permission set.

Rank rules

• A non-owner can only assign roles strictly below their own, and can only change or remove members below their own rank. Admins therefore manage operators and viewers, not other admins.
• The owner can assign any role, including owner. Ownership transfer is exactly that: promote a member to owner. The previous owner keeps the owner role until someone changes it, so a team can have more than one owner.
• The last remaining owner cannot be demoted.
• An owner cannot be removed and cannot leave the team. Every other member can leave from Settings > Team.
• A team can be renamed from Settings > Team > Manage (the pencil next to the name). Renaming needs team:settings:write and the owner or admin role: owners hold the key by default, an admin needs it granted as an override. Names are 1 to 100 characters. A team cannot be deleted and its description cannot be edited.
• Team mutations are rate-limited to 30 per minute per user.

Per-member overrides

Every member carries a map of permission key to true/false. An override takes precedence over the role default, so you can grant a viewer inbox:reply or take accounts:delete away from an admin. Open Settings > Team > Manage, expand a member and use the toggles.

You can only grant permissions you hold yourself. The full key set:

Inviting members

1. Settings > Team > Manage > Invite member.
2. Enter the teammate's email and pick a role (viewer, operator or admin).
3. The email must belong to an existing TelegramOS user. If it does not, the request fails with "No user with that email. They must sign up first."
4. The member is added immediately and gets an in-app notification. There is no invitation email, no pending state, nothing to accept and nothing that expires.

Inviting yourself or someone who is already a member fails.

What members see

Team membership widens the resources a member can act on. Accounts, conversations, auto-reply rules, bots, analytics and billing views of every team you belong to appear alongside your own, filtered by the permission each endpoint requires. There is no workspace switcher; you always see one merged list.

• Analytics for a team is visible only while that team's owner has message analytics enabled (see Analytics).
• Billing views require billing:read; only the owner has billing:manage by default.
• Your own accounts and wallet are never visible to teams you are a member of.

Audit log

Team-service writes an append-only audit_logs row for team.create, team.rename (with old and new name), team.member.invite, team.member.update (with old and new role), team.member.remove and team.member.leave. Each row stores the actor's user id and email, the team, the resource, structured metadata, the client IP, the user agent and a UTC timestamp.

• Read it with GET /audit/logs?team_id=… (needs audit:logs:read, held by owners and admins by default). Without team_id you get your own actions. Filters: action, resource_type, limit (max 200), offset.
• There is no audit page in the dashboard and no CSV export.
• Rows are never deleted or updated: a database trigger rejects UPDATE, DELETE and TRUNCATE. There are no retention tiers.
• Other services (accounts, proxies, campaigns) keep their own logs and do not write to this table.