Teambox — Overview

Teambox is the Sendiee shared inbox: agents, teams, conversation assignment and inbox statuses across WhatsApp, Instagram and Messenger. These endpoints expose the same operations the teambox web, desktop and mobile apps use, so you can route and resolve conversations from your own helpdesk, CRM, or an AI agent.

Agent

A person who answers conversations. Agents join by accepting an email invite, so the API lists them read-only.

Team

A named group of agents with managers, a colour and an emoji — the unit conversations get routed to.

Assignment

A conversation points at one agent and one team. Assign by agent, by team (round-robin), or both.

Status

Where a conversation sits in the inbox — pending, open, resolved, or a custom status your workspace defines.

Every write is live

Teambox endpoints proxy to the realtime inbox backend rather than writing the database directly. An assignment or status change made over the API appears instantly in every open teambox app, lands in the conversation audit trail, and fires the same automation events as the same action taken by a human agent.

Endpoints

GET/v2.0/teams
List teams + plan usage
POST/v2.0/teams
Create a team
PATCH/v2.0/teams/{teamId}
Update name, members, managers
GET/v2.0/agents
List the agent roster + seat usage
POST/v2.0/conversations/assign
Assign to an agent and/or team
POST/v2.0/conversations/unassign
Return to the unassigned pool
GET/v2.0/conversations/assignment-history
Audit trail
GET/v2.0/conversations/statuses
The workspace status catalogue
POST/v2.0/conversations/status
Move a conversation to a status

Targeting a conversation

Assign, unassign, status and history all identify a conversation the same way. Pass either:

conversationId — the id returned by GET /v2.0/chats/conversations, or
phone — the customer identifier. For WhatsApp this is their number in full international format without + (e.g. 919876543210); for Instagram and Messenger it is the platform sender id.

With phone, the channel defaults to WhatsApp and the business number defaults to your organisation’s only active WhatsApp sender. Pass channel (whatsapp | instagram | messenger) and businessNumber when that default cannot apply:

Code	When
`NO_WHATSAPP_CHANNEL`	A phone was given but the org has no active WhatsApp number.
`CHANNEL_AMBIGUOUS`	The org has more than one WhatsApp number — pass `businessNumber`.
`CHANNEL_ID_REQUIRED`	Instagram / Messenger always need an explicit `businessNumber`.
`LOCATOR_REQUIRED`	Neither `conversationId` nor `phone` was supplied.
`NOT_FOUND`	No conversation exists yet for that customer on that channel.

A conversation must already exist

Teambox rows are created by the first inbound message. You cannot assign or resolve a customer who has never written in — send them a template first, or wait for their reply.

Scopes

Scoped API keys (prefix sk_) need the matching scope for each call. See API Key Scopes.

Scope	Grants
`teams:read`	List teams and plan usage
`teams:write`	Create and update teams
`agents:read`	List the agent roster
`assignments:read`	Read assignment history
`assignments:write`	Assign and unassign conversations
`conversations:read`	List the workspace inbox statuses
`conversations:write`	Change a conversation status

How API actions are attributed

Teambox records who did what. An action taken with an API key is stored with source: "manual" and an actor name of API key sk_Ab12Cd34 (your key prefix — legacy keys without a prefix show as Public API), so the conversation timeline distinguishes it from an agent click, an AI auto-assign (source: "ai") or a flow (source: "flow").

Plan limits

Teams and agent seats are plan-gated exactly as they are in the app. Creating a team past your max_teams cap returns 403 LIMIT_EXCEEDED; both list endpoints return a usage block so you can check headroom before writing. Read the caps and current consumption from GET /v2.0/billing/plan.

503 TEAMBOX_NOT_CONFIGURED

Every teambox endpoint except GET /v2.0/conversations/statuses requires the inbox backend to be reachable. A 503 with this code means teambox is not enabled for the environment you are calling — it is never caused by your request payload.