​

Team Chat

​

Workflow 1 — On-call handoff: a channel the responders live in

1. Resolve who is on call with the On-Call API — POST /api/v1/oncall/resolve returns the current member and the next handoff instant (see the on-call alerting guide for the full rotation setup).
2. Post the handoff note in the rotation’s channel so both the outgoing and incoming responder see it, with a thread for anything that needs follow-up.
3. Start a huddle in the same channel the moment a text thread gets too slow and someone just needs to talk it through.

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" }'

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels/tch_abc123/members \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "usr_2", "role": "member" }'

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": "Handoff 09:00 UTC — incident inc_123 still open, watching error rates. Ticket is in the Inbox." }'

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels/tch_abc123/messages/tmsg_9f8e7d/replies \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Error rates flattened after the rollback — resolving the ticket now." }'

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels/tch_abc123/huddle \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

Workflow 2 — Support escalation: a channel paired with an Inbox ticket

1. The agent keeps the customer thread open in the Inbox.
2. They post the escalation in an internal channel — #support-escalations, or a specialist channel like #billing-specialists — linking or pasting the conversation id.
3. A specialist answers in a thread on the escalation post, or opens a huddle for anything that needs a live conversation.
4. The agent takes the answer back into the Inbox conversation and replies to the customer there.

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels/tch_esc456/messages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Escalation from Inbox conversation cnv_7891 — customer reports double charge on invoice inv_2210. Need a billing specialist to confirm before I reply." }'

​

Workflow 3 — Direct messages: etiquette and edge cases

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/dms \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "usr_4" }'

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/dms/tdm_1122/messages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Can you cover my on-call window tomorrow 09:00–12:00 UTC?" }'

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/dms/tdm_1122/read \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

Permissions model

• Per-channel role (owner / admin / member) — set on the channel’s membership. The creator of a channel becomes its owner; everyone else is added as member unless the owner promotes them.
• Workspace role (the org-level Admin or Owner set in Settings > Team) — moderates every team channel, independent of channel membership role.

​

Notifications and read state

• Header notification — when someone posts a channel message, every other member of that channel gets a notification in the app header (the bell and its counter). The same goes for a new DM. This is how a handoff post reaches the incoming responder even while they are looking at the Inbox.
• Unread counts — GET /team-chat/channels returns each channel with unread_count and last_message_at, so a list call alone is enough to render a badge. The unread count is measured against the caller’s per-channel read cursor.
• Mark a channel read — POST /team-chat/channels/{channelId}/read advances the read cursor to now; the channel’s unread count drops to zero until the next message arrives. DMs have their own equivalent, POST /team-chat/dms/{threadId}/read.
• Presence and typing — POST /team-chat/presence/heartbeat keeps the caller visible as online (and accepts a status such as away); GET /team-chat/presence returns the online snapshot plus last-seen timestamps; POST /team-chat/presence (delete-style) marks the caller offline on a graceful disconnect. POST /team-chat/typing broadcasts a typing indicator to a channel. These power the “online” dots and typing row in the UI — they carry no message content.

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/presence/heartbeat \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "online" }'

​

Events and webhooks

• To drive an external system (for example, pushing on-call chatter into your own status page), poll GET /team-chat/channels for unread counts and fetch message history per channel — search and history are keyset-paginated, so a poll loop with a cursor is cheap.
• Never point a customer-facing webhook consumer at Team Chat expecting events; the webhook catalog in Webhooks covers customer-facing surfaces (messages, calls, inbox), not internal chat.

​

Searching back through an incident

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

​

Endpoints

​

See also

• Team Chat API reference — full endpoint and field reference
• On-Call alerting guide — build the rotation that pages the responders you coordinate with here
• On-Call API — resolve who is responding before starting a huddle
• Inbox API — the customer-facing conversation surface Team Chat is deliberately separate from