Team Chat API

Team Chat is internal, employee-to-employee messaging inside your Orbit workspace — channels, threaded replies, huddles (ad-hoc voice/video rooms), and direct messages between operators. It is entirely separate from customer-facing conversations: nothing here reaches a customer, and no outbound customer voice or SMS is touched by any endpoint on this page. Base path: /api/v1/team-chat Authentication: API key (X-API-Key) or session JWT. Posting or reading a channel requires channel membership; managing membership requires an owner or admin role on that channel. DM endpoints require the caller to be one of the two participants.

Channels

Method	Path	Purpose
`GET`	`/api/v1/team-chat/channels`	Channels the caller is a member of
`POST`	`/api/v1/team-chat/channels`	Create a channel (caller becomes owner)
`DELETE`	`/api/v1/team-chat/channels/{channelId}`	Delete a channel and its messages (owner only)
`GET`	`/api/v1/team-chat/channels/{channelId}/members`	List members
`POST`	`/api/v1/team-chat/channels/{channelId}/members`	Add a member (owner/admin only)
`DELETE`	`/api/v1/team-chat/channels/{channelId}/members/{userId}`	Remove a member (owner/admin only)

Channel messages

Method	Path	Purpose
`GET`	`/api/v1/team-chat/channels/{channelId}/messages`	Message history, newest-first
`POST`	`/api/v1/team-chat/channels/{channelId}/messages`	Post a message
`PATCH`	`/api/v1/team-chat/channels/{channelId}/messages/{id}`	Edit your own message
`DELETE`	`/api/v1/team-chat/channels/{channelId}/messages/{id}`	Soft-delete your own message
`GET`	`/api/v1/team-chat/channels/{channelId}/messages/{id}/thread`	Load a message thread (root + replies)
`POST`	`/api/v1/team-chat/channels/{channelId}/messages/{id}/thread`	Reply in-thread to a message

Search

Method	Path	Purpose
`GET`	`/api/v1/team-chat/search`	Full-text search messages across the channels you belong to

GET /api/v1/team-chat/search ranks message bodies by relevance and paginates with an opaque cursor. It only ever searches channels you’re a member of — membership is the authorization boundary, so a channel you were removed from drops out of results with no separate check.

Query param	Required	Description
`q`	yes	Search term, 1–200 characters. Matches are partial-word (`ship` finds `shipping`)
`channel_id`	no	Restrict results to a single channel
`from` / `to`	no	ISO timestamp bounds on `created_at`
`cursor`	no	Opaque cursor from a previous page’s response
`limit`	no	Page size, 1–200 (default 25)

curl "https://api.orbit.devotel.io/api/v1/team-chat/search?q=deploy&channel_id=tch_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "6d21f4a0-8b2c-45e1-9c77-0a1b2c3d4e5f",
      "channel_id": "tch_abc123",
      "channel_name": "on-call-platform",
      "sender_user_id": "usr_9k2hf7",
      "sender_name": "Riley Chen",
      "sender_avatar_url": "https://<your-cdn>/avatars/usr_9k2hf7/avatar.png",
      "body": "Deploy is out, watching error rates.",
      "mentions": [],
      "created_at": "2026-08-26T09:41:12.000Z",
      "edited_at": null,
      "rank": 0.8113
    }
  ],
  "meta": {
    "request_id": "req_m01ab2c3d4",
    "timestamp": "2026-08-26T09:41:15Z",
    "pagination": {
      "cursor": "eyJyIjowLjgxMTMsImMiOiIyMDI2LTA4LTI2VDA5OjQxOjEyLjAwMDAwMFoiLCJpIjoiNmQyMWY0YTAtOGIyYy00NWUxLTljNzctMGExYjJjM2Q0ZTVmIn0=",
      "has_more": true
    }
  }
}

The cursor is opaque — pass meta.pagination.cursor back verbatim as the cursor query param to fetch the next page, and do not parse or rebuild it. has_more: false (or a null cursor) means you have seen the full result set. Results are ordered by rank, then recency.

Huddles

A huddle is an ad-hoc, low-friction voice/video room scoped to a channel — anyone in the channel can start one or drop into the live one.

Method	Path	Purpose
`GET`	`/api/v1/team-chat/channels/{channelId}/huddle`	Get the active huddle for a channel, if any
`POST`	`/api/v1/team-chat/channels/{channelId}/huddle`	Start a huddle, or join the one already running
`POST`	`/api/v1/team-chat/channels/{channelId}/huddle/leave`	Leave the huddle (ends it when the room empties)

Direct messages

Method	Path	Purpose
`GET`	`/api/v1/team-chat/dms`	DM threads the caller participates in
`POST`	`/api/v1/team-chat/dms`	Open (get-or-create) a 1:1 thread with another user
`DELETE`	`/api/v1/team-chat/dms/{threadId}`	Delete a thread and its messages (participant only)
`GET`	`/api/v1/team-chat/dms/{threadId}/messages`	DM history
`POST`	`/api/v1/team-chat/dms/{threadId}/messages`	Send a DM
`POST`	`/api/v1/team-chat/dms/{threadId}/read`	Mark inbound messages in a thread as read

Members, threads, DMs, and huddles

Samples below state the response envelope for one call in each declared group. data is the payload shown under each example; every response also carries meta.request_id (echo it back to support — it is the fastest cross-reference) and meta.timestamp.

Add a member

POST /api/v1/team-chat/channels/{channelId}/members with { "user_id": "<workspace user id>" } adds one member. Only the channel’s owner or an admin can add or remove members; a caller without that role gets 403 NOT_A_MEMBER. Response 201:

201

{
  "data": {
    "channel_id": "tch_abc123",
    "user_id": "usr_9k2hf7",
    "role": "member",
    "joined_at": "2026-08-26T09:42:31.000Z"
  },
  "meta": { "request_id": "req_m01ab2c3d7", "timestamp": "2026-08-26T09:42:32Z" }
}

Re-adding an existing member is idempotent and returns the same shape with the refreshed role and joined timestamp.

Reply in a thread

POST /api/v1/team-chat/channels/{channelId}/messages/{messageId}/thread posts into the thread rooted at {messageId}. Threads are one level deep: if {messageId} is itself a reply, the new reply still points at that reply’s root, so parent_message_id always names the root message. Response 201:

201

{
  "data": {
    "id": "7e33b921-1c4d-46f2-88aa-1b2c3d4e5f6a",
    "channel_id": "tch_abc123",
    "parent_message_id": "6d21f4a0-8b2c-45e1-9c77-0a1b2c3d4e5f",
    "sender_user_id": "usr_9k2hf7",
    "body": "Error rate steady. Root cause was a stale pod.",
    "mentions": [],
    "attachments": [],
    "created_at": "2026-08-26T09:44:07.000Z",
    "edited_at": null
  },
  "meta": { "request_id": "req_m01ab2c3d8", "timestamp": "2026-08-26T09:44:08Z" }
}

GET on the same path returns the thread in reading order as { "root": <message>, "replies": [<message>...] }; a soft-deleted root renders root: null with the surviving replies.

List DM threads

GET /api/v1/team-chat/dms returns the threads you participate in, most-recent-message first. Response 200:

200

{
  "data": [
    {
      "id": "dm_8f4b2a",
      "counterparty": "usr_3m9qz1",
      "counterparty_name": "Sam Ortiz",
      "counterparty_avatar_url": "https://<your-cdn>/avatars/usr_3m9qz1/avatar.png",
      "created_at": "2026-08-20T15:02:44.000Z",
      "last_body": "Can you pick up the changelog review?",
      "last_message_at": "2026-08-26T08:56:10.000Z",
      "unread_count": 2
    }
  ],
  "meta": { "request_id": "req_m01ab2c3d9", "timestamp": "2026-08-26T09:45:01Z" }
}

Each row is a thread id plus the counterparty’s hydrated identity (name and avatar fall back to null — render the id tail then), their last inbound message preview (last_body, capped at 140 characters), and your capped unread_count. DM endpoints reject callers who are not one of the two participants.

Start or join a huddle

POST /api/v1/team-chat/channels/{channelId}/huddle starts the huddle (or rejoins the one already running) and returns a join hint to pass to your WebRTC client — this is an internal operator voice/video plane; nothing on this page exercises outbound customer voice or SMS. Response 201 (first start) or 200 (joining a live huddle):

201

{
  "data": {
    "started": true,
    "huddle": {
      "room_name": "tnt-1a2b3c4d:chan-tch_abc123",
      "channel_id": "tch_abc123",
      "started_by": "usr_4t7qn2",
      "started_at": "2026-08-26T09:46:00.000Z",
      "media": "audio"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature",
    "room_name": "tnt-1a2b3c4d:chan-tch_abc123",
    "media_url": "wss://media.orbit.devotel.io"
  },
  "meta": { "request_id": "req_m01ab2d0f0", "timestamp": "2026-08-26T09:46:01Z" }
}

started: true means you opened the room; started: false means you joined it. Present token around media_url as the client join hint — the server pre-creates the room with an empty-timeout so an abandoned huddle reclaims itself, and POST /huddle/leave ends it when the room empties.

Example — create a channel and post a message

# Create a channel
curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "on-call-platform", "description": "Platform team on-call chatter" }'

# Post a message
curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels/tch_abc123/messages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Deploy is out, watching error rates." }'

{
  "data": {
    "id": "tch_abc123",
    "name": "on-call-platform",
    "description": "Platform team on-call chatter",
    "created_by_user_id": "usr_4t7qn2",
    "created_at": "2026-08-26T09:40:01.000Z",
    "updated_at": "2026-08-26T09:40:01.000Z",
    "my_role": "owner"
  },
  "meta": { "request_id": "req_m01ab2c3d5", "timestamp": "2026-08-26T09:40:02Z" }
}

{
  "data": {
    "id": "6d21f4a0-8b2c-45e1-9c77-0a1b2c3d4e5f",
    "channel_id": "tch_abc123",
    "sender_user_id": "usr_4t7qn2",
    "body": "Deploy is out, watching error rates.",
    "mentions": [],
    "attachments": [],
    "created_at": "2026-08-26T09:41:12.000Z",
    "edited_at": null
  },
  "meta": { "request_id": "req_m01ab2c3d6", "timestamp": "2026-08-26T09:41:15Z" }
}

Channel objects carry id, name, description, created_by_user_id, created_at, updated_at, plus my_role — your role on the channel, owner for its creator. Message objects carry id, channel_id, sender_user_id, body, mentions, attachments, created_at, and edited_at; a top-level message has parent_message_id: null (replies point at their thread root). The workspace user id you see as created_by_user_id / sender_user_id qualifies as an owner_id / author_id wherever a client types that field — only members yield ids on this surface (403 NOT_A_MEMBER otherwise).

Walked mini-recipe — create, post, edit, and search

The four-step miniature below recreates a create channel → post → edit own message → search it flow end to end; drop the drafts into the Task index in API recipes. Shape it as copyable steps and keep every request id so a page hop across the four calls stays traceable. Create the channel — capture data.id (tch_…) for the two follows:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "incident-alpha", "description": "Spillover incident channel" }'

Post the original message — capture data.id (the message id):

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels/tch_abc123/messages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Root-cause meeting in 10" }'

Edit own message — only the author can PATCH; the sender-scoped WHERE clause is the authorization boundary, so another member gets 404 NOT_FOUND:

cURL

curl -X PATCH https://api.orbit.devotel.io/api/v1/team-chat/channels/tch_abc123/messages/6d21f4a0-8b2c-45e1-9c77-0a1b2c3d4e5f \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Root-cause meeting in 15" }'

Search it — your membership on that channel is the only gate:

cURL

curl "https://api.orbit.devotel.io/api/v1/team-chat/search?q=root-cause&channel_id=tch_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Each hit sits directly in data (a flat array, data.results if your client normalizes it) in rank-descending order, and meta.pagination.cursor carries forward the next-page token. Reuse the cursor verbatim — parsing or rebuilding it voids the page; an unparsed/null cursor always starts at rank 1.

API Reference

All Endpoints

Team Chat API: internal channels, threads, and huddles

Team Chat API

Channels

Channel messages

Search

Huddles

Direct messages

Members, threads, DMs, and huddles

Add a member

Reply in a thread

List DM threads

Start or join a huddle

Example — create a channel and post a message

Walked mini-recipe — create, post, edit, and search

See also

​Team Chat API

​Channels

​Channel messages

​Search

​Huddles

​Direct messages

​Members, threads, DMs, and huddles

​Add a member

​Reply in a thread

​List DM threads

​Start or join a huddle

​Example — create a channel and post a message

​Walked mini-recipe — create, post, edit, and search

​See also

Team Chat API

Channels

Channel messages

Search

Huddles

Direct messages

Members, threads, DMs, and huddles

Add a member

Reply in a thread

List DM threads

Start or join a huddle

Example — create a channel and post a message

Walked mini-recipe — create, post, edit, and search

See also