Inbox API

Sits on top of Conversations and powers the human-agent surface — who is currently viewing what, internal notes, saved filtered views, conversation routing, and quick-reply macros. Base path: /api/v1/inbox Authentication: API key (X-API-Key) or session JWT. The dashboard uses a Clerk session, and server-to-server callers can use an API key against the same endpoints.

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.inbox.list();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/inbox")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Live presence

Used by the inbox UI to show “X is viewing” + typing indicators. Heartbeat the viewing endpoint roughly every 20 seconds while the conversation is open. The server holds presence for a 30-second TTL, so a 20-second cadence keeps it alive with margin — heartbeating at the full 30 seconds races the TTL and intermittently drops your own presence.

Method	Path	Purpose
`POST`	`/api/v1/inbox/{conversationId}/viewing`	Heartbeat — register caller as viewing
`DELETE`	`/api/v1/inbox/{conversationId}/viewing`	Unregister (tab close / route away)
`GET`	`/api/v1/inbox/{conversationId}/viewers`	Who is currently viewing
`POST`	`/api/v1/inbox/{conversationId}/typing`	Toggle the caller’s typing state

Example — heartbeat a conversation every 20 seconds

1. Register as viewing (send on open, then repeat every ~20 s):

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/conv_9f3a2b/viewing \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "tab_a1B2c3D4" }'

{
  "data": {
    "viewing": true,
    "ttl_seconds": 30,
    "beacon_token": "eyJhbGciOi…",
    "beacon_ctx": "eyJvcmdJZCI6…",
    "beacon_ttl_seconds": 3600
  },
  "meta": { "request_id": "req_01J8XA…", "timestamp": "2026-08-24T09:42:11Z" }
}

ttl_seconds: 30 is the caveat from above, verbatim: refresh well inside 30 seconds — the dashboard heartbeats at 20 seconds so a slow call still lands before the TTL expires. session_id is optional; pass it when a user can have several tabs open so each tab registers its own presence row. 2. Read the current viewers:

curl https://api.orbit.devotel.io/api/v1/inbox/conv_9f3a2b/viewers \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "viewers": ["user_2hF9kLmWq3vX8yZ0aBcD1eF2g", "user_4jK8nPxRs5wB1cZ2bDdE3fG4h"]
  },
  "meta": { "request_id": "req_01J8XB…", "timestamp": "2026-08-24T09:42:12Z" }
}

3. Signal typing (send when the composer has focus; the server also auto-stops typing 5 seconds after your last call):

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/conv_9f3a2b/typing \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "typing": true, "session_id": "tab_a1B2c3D4" }'

{
  "data": { "typing": true },
  "meta": { "request_id": "req_01J8XD…", "timestamp": "2026-08-24T09:42:14Z" }
}

When the agent navigates away, DELETE /{conversationId}/viewing unregisters immediately rather than waiting out the 30-second TTL.

Internal notes

Team-only notes attached to a conversation. Never visible to the contact; surfaced inline with messages in the inbox UI.

Method	Path	Purpose
`POST`	`/api/v1/inbox/{conversationId}/internal-notes`	Post an internal note
`GET`	`/api/v1/inbox/{conversationId}/internal-notes`	List internal notes (newest first)

Example — post a note with a mention

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/conv_9f3a2b/internal-notes \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customer says the refund never arrived — @Priya, can you re-issue it? Their order number is #4120.",
    "mentions": ["user_4jK8nPxRs5wB1cZ2bDdE3fG4h"]
  }'

mentions carries the user ids your typeahead resolved while composing; each mentioned user gets a Notification Center entry. Response (201):

{
  "data": {
    "id": "note_71c0d4e2",
    "conversation_id": "conv_9f3a2b",
    "author_user_id": "user_2hF9kLmWq3vX8yZ0aBcD1eF2g",
    "content": "Customer says the refund never arrived — @Priya, can you re-issue it? Their order number is #4120.",
    "mentions": ["user_4jK8nPxRs5wB1cZ2bDdE3fG4h"],
    "created_at": "2026-08-24T09:45:02Z",
    "updated_at": null
  },
  "meta": { "request_id": "req_01J8Y2…", "timestamp": "2026-08-24T09:45:02Z" }
}

Saved views

Personal or team-wide filtered views over the conversation list — “My open WhatsApp conversations”, “VIP escalations”, “Stale > 4h”, etc.

Method	Path	Purpose
`GET`	`/api/v1/inbox/views`	List personal + team views
`POST`	`/api/v1/inbox/views`	Create a view
`PATCH`	`/api/v1/inbox/views/{id}`	Rename, reorder, or re-filter
`DELETE`	`/api/v1/inbox/views/{id}`	Delete

Example — create a team view with filters

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/views \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support team — open WhatsApp",
    "scope": "team",
    "filters": {
      "channels": ["whatsapp"],
      "statuses": ["open", "pending"],
      "assignee": "team_support"
    },
    "sort_key": "-last_message_at",
    "is_pinned": true,
    "color": "#25D366"
  }'

The filters object is the shared inbox filter AST — channels, statuses, assignee, tags, unread, search, date ranges, and more; every field is optional and combines conjunctively. scope: "team" requires owner/admin; "personal" (default) is visible only to you. Response (201):

{
  "data": {
    "id": "d1b2f3a4-8c1d-4e2f-9b0a-5d6e7f8a9b0c",
    "name": "Support team — open WhatsApp",
    "scope": "team",
    "filters": {
      "channels": ["whatsapp"],
      "statuses": ["open", "pending"],
      "assignee": "team_support"
    },
    "sort_key": "-last_message_at",
    "is_default": false,
    "is_pinned": true,
    "color": "#25D366",
    "created_at": "2026-08-24T09:47:20Z",
    "updated_at": "2026-08-24T09:47:20Z"
  },
  "meta": { "request_id": "req_01J902…", "timestamp": "2026-08-24T09:47:20Z" }
}

Routing rules

Auto-assign incoming conversations to agents or teams based on channel, contact, content, or time. Rules are evaluated in priority order; first match wins.

Method	Path	Purpose
`GET`	`/api/v1/inbox/routing-rules`	List rules
`POST`	`/api/v1/inbox/routing-rules`	Create a rule
`PATCH`	`/api/v1/inbox/routing-rules/{id}`	Update name, priority, condition, action
`DELETE`	`/api/v1/inbox/routing-rules/{id}`	Delete a rule
`POST`	`/api/v1/inbox/routing-rules/test`	Dry-run a rule against a sample conversation

Example — create a rule, then dry-run it

Create (owner/admin only — routing writes are team-wide):

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/routing-rules \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund keywords → refunds team",
    "conditions": {
      "channel": ["whatsapp", "sms"],
      "keyword": ["refund", "charged twice", "money back"],
      "time_of_day": { "outside_hours": false, "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "18:00" }
    },
    "action": { "type": "assign_team", "target_id": "team_refunds" },
    "schedule": null
  }'

The conditions + action shape is strict (unknown fields are rejected with VALIDATION_ERROR). keyword entries are plain substrings, or /regex/ patterns — regexes that risk ReDoS are rejected at save time. time_of_day narrows the match to a weekly window (here: weekdays 09:00–18:00); omit it to match around the clock. Action types: assign_user, assign_team, assign_round_robin, assign_skill_based, set_tag, set_priority, trigger_agent. Response (201):

{
  "data": {
    "id": "9c8b7a6d-5e4f-3c2d-1b0a-9e8d7c6b5a4f",
    "name": "Refund keywords → refunds team",
    "priority": 1,
    "enabled": true,
    "conditions": {
      "channel": ["whatsapp", "sms"],
      "keyword": ["refund", "charged twice", "money back"],
      "time_of_day": { "outside_hours": false, "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "18:00" }
    },
    "action": { "type": "assign_team", "target_id": "team_refunds" },
    "schedule": null,
    "created_by": "user_2hF9kLmWq3vX8yZ0aBcD1eF2g",
    "created_at": "2026-08-24T09:50:04Z",
    "updated_at": "2026-08-24T09:50:04Z"
  },
  "meta": { "request_id": "req_01J93K…", "timestamp": "2026-08-24T09:50:04Z" }
}

Dry-run against a sample conversation — nothing is persisted or assigned:

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/routing-rules/test \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_id": "9c8b7a6d-5e4f-3c2d-1b0a-9e8d7c6b5a4f",
    "sample_conversation": {
      "channel": "whatsapp",
      "body": "Hi, I was charged twice — looking for a refund please.",
      "now": "2026-08-24T09:50:30Z"
    }
  }'

{
  "data": {
    "matched": true,
    "detected_language": "en",
    "org_timezone": "UTC",
    "action": { "type": "assign_team", "target_id": "team_refunds" }
  },
  "meta": { "request_id": "req_01J94R…", "timestamp": "2026-08-24T09:50:30Z" }
}

Send rule (an inline create-style body) instead of rule_id to preview a rule before saving it. When matched is false, action comes back null — so a false verdict reads as { "matched": false, "action": null }.

Macros

Saved quick replies with optional variables, attachments, and post-actions (close, tag, assign).

Method	Path	Purpose
`GET`	`/api/v1/inbox/macros`	List personal + shared macros
`POST`	`/api/v1/inbox/macros`	Create a macro
`GET`	`/api/v1/inbox/macros/popular`	Most-used macros for this user
`PATCH`	`/api/v1/inbox/macros/{id}`	Update a macro
`DELETE`	`/api/v1/inbox/macros/{id}`	Delete a macro
`POST`	`/api/v1/inbox/conversations/{convId}/run-macro`	Apply a macro to a conversation

Example — create a macro, then run it

Create with a mustache variable and a follow-up step:

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/macros \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund acknowledgement",
    "shortcut": "refund-ack",
    "is_shared": true,
    "steps": [
      {
        "type": "send_message",
        "config": { "body": "Hi {{contact.first_name}}, we received your refund request {{extra.order_id}} — the funds will reach your account within 5 business days." }
      },
      { "type": "add_tag", "config": { "tags": ["refund-in-progress"] } },
      { "type": "set_status", "config": { "status": "pending" } }
    ]
  }'

Response (201):

{
  "data": {
    "id": "4f3e2d1c-0b9a-6d5c-4e3f-2a1b0c9d8e7f",
    "name": "Refund acknowledgement",
    "shortcut": "refund-ack",
    "is_shared": true,
    "usage_count": 0,
    "created_at": "2026-08-24T09:52:11Z",
    "updated_at": "2026-08-24T09:52:11Z"
  },
  "meta": { "request_id": "req_01J96P…", "timestamp": "2026-08-24T09:52:11Z" }
}

Run it against a conversation, supplying the {{extra.*}} variables:

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/conversations/conv_9f3a2b/run-macro \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "macroId": "4f3e2d1c-0b9a-6d5c-4e3f-2a1b0c9d8e7f", "variables": { "order_id": "#4120" } }'

{
  "data": {
    "run_log_id": "macro_run_7c91ad",
    "completed_steps": 3,
    "total_steps": 3,
    "failed_step": null,
    "error": null,
    "rolled_back_steps": 0
  },
  "meta": { "request_id": "req_01J98W…", "timestamp": "2026-08-24T09:52:19Z" }
}

Built-in variables like {{contact.first_name}} resolve from the conversation’s contact; anything you pass in variables is exposed to the template as {{extra.<key>}}. On a partial failure the run returns HTTP 207 and failed_step reports the 1-based index of the step that threw.

API Reference

All Endpoints

Inbox API: presence, saved views, routing, notes, macros

Inbox API

Using the SDKs

Live presence

Example — heartbeat a conversation every 20 seconds

Internal notes

Example — post a note with a mention

Saved views

Example — create a team view with filters

Routing rules

Example — create a rule, then dry-run it

Macros

Example — create a macro, then run it

See also

​Inbox API

​Using the SDKs

​Live presence

​Example — heartbeat a conversation every 20 seconds

​Internal notes

​Example — post a note with a mention

​Saved views

​Example — create a team view with filters

​Routing rules

​Example — create a rule, then dry-run it

​Macros

​Example — create a macro, then run it

​See also

Inbox API

Using the SDKs

Live presence

Example — heartbeat a conversation every 20 seconds

Internal notes

Example — post a note with a mention

Saved views

Example — create a team view with filters

Routing rules

Example — create a rule, then dry-run it

Macros

Example — create a macro, then run it

See also