Inbox

GET/api/v1/inbox/channels

List_channels

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: name, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/inbox/channels"

{  "channels": [    {      "actions_allowed": true,      "allowed_producers": [        "string"      ],      "channel_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "default_priority": "low",      "delivery_policy": {        "pubsub_topic": "string",        "scheduled_delivery_allowed": true,        "websocket_fanout": true      },      "description": "string",      "name": "string",      "retention_days": 0,      "technical_notes_required": true,      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  }}

POST/api/v1/inbox/channels

Create_channel

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

actions_allowed?boolean

Whether interactive actions are permitted

allowed_producers?array<string>

Producer principals or service names allowed to send to this channel

default_priority?null|

delivery_policy?null|

description?|

Human-facing description

name*string

Channel name (e.g. agent.handoff)

retention_days?|

Retention period in days

Formatint32

Range0 <= value

technical_notes_required?boolean

Whether technical notes are required on every message

workspace_id?|

Optional named workspace; defaults to the account root.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/channels" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "actions_allowed": true,  "allowed_producers": [    "string"  ],  "channel_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "default_priority": "low",  "delivery_policy": {    "pubsub_topic": "string",    "scheduled_delivery_allowed": true,    "websocket_fanout": true  },  "description": "string",  "name": "string",  "retention_days": 0,  "technical_notes_required": true,  "updated_at": "2019-08-24T14:15:22Z",  "workspace_id": "string"}

GET/api/v1/inbox/channels/{channel_id}

Get_channel

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

channel_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/inbox/channels/string"

{  "actions_allowed": true,  "allowed_producers": [    "string"  ],  "channel_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "default_priority": "low",  "delivery_policy": {    "pubsub_topic": "string",    "scheduled_delivery_allowed": true,    "websocket_fanout": true  },  "description": "string",  "name": "string",  "retention_days": 0,  "technical_notes_required": true,  "updated_at": "2019-08-24T14:15:22Z",  "workspace_id": "string"}

GET/api/v1/inbox/counts

Get_counts

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/inbox/counts"

{  "counts": {    "by_channel": {      "property1": 0,      "property2": 0    },    "by_priority": {      "property1": 0,      "property2": 0    },    "by_thread": {      "property1": 0,      "property2": 0    },    "total": 0  }}

POST/api/v1/inbox/maintenance/run

Run_maintenance

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/maintenance/run"

{  "expired": 0,  "promoted": 0,  "self_destructed": 0}

GET/api/v1/inbox/messages

List_messages

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

filter?

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 50).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

unread?boolean

Only return unread messages

include_archived?boolean

Include archived messages when no archived filter is given

include_dismissed?boolean

Include dismissed messages when no dismissed filter is given

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/inbox/messages"

{  "messages": [    {      "actions": [        {          "id": "string",          "kind": "link",          "label": "string",          "target": "string"        }      ],      "body": "string",      "channel_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "delivery": {        "deliver_at": "2019-08-24T14:15:22Z",        "expires_at": "2019-08-24T14:15:22Z",        "self_destruct_after_read_seconds": 0      },      "message_id": "string",      "priority": "low",      "recipient_user_id": "string",      "sender": {        "id": "string",        "kind": "string"      },      "state": {        "archived": true,        "dismissed": true,        "read": true,        "read_at": "2019-08-24T14:15:22Z"      },      "technical_notes": null,      "thread_id": "string",      "title": "string"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  }}

POST/api/v1/inbox/messages

Send_message

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

actions?array<>

Interactive actions

body*string

Message body

channel_id*string

Channel to send the message on

deliver_at?|

Deliver at a future time (scheduled delivery)

Formatdate-time

expires_at?|

Expiry timestamp

Formatdate-time

idempotency_key?|

Idempotency key to make re-sends safe

priority?null|

recipient_user_ids*array<string>

Recipient user ids

self_destruct_after_read_seconds?|

Self-destruct delay after read in seconds

Formatint64

Range0 <= value

technical_notes?null|

thread_id?|

Optional thread grouping id

title*string

Message title

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/messages" \  -H "Content-Type: application/json" \  -d '{    "body": "string",    "channel_id": "string",    "recipient_user_ids": [      "string"    ],    "title": "string"  }'

{  "message_ids": [    "string"  ],  "scheduled": true,  "status": "string"}

POST/api/v1/inbox/messages/batch

Send many distinct messages in one request

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A batch of distinct messages to send in one request. Each is sent independently and fail-fast; the server enforces a per-batch cap.

messages*array<>

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/messages/batch" \  -H "Content-Type: application/json" \  -d '{    "messages": [      {        "body": "string",        "channel_id": "string",        "recipient_user_ids": [          "string"        ],        "title": "string"      }    ]  }'

{  "count": 0,  "results": [    {      "message_ids": [        "string"      ],      "scheduled": true,      "status": "string"    }  ]}

POST/api/v1/inbox/messages/bulk

Bulk_messages

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

channel_id?|

Restrict the filter-based selection to a channel

message_ids?array<string>

Explicit message ids to act on

operation*BulkOperation

Operation to apply

Value in

"mark_read"
"mark_unread"
"dismiss"
"archive"
"delete"

unread_only?boolean

Restrict the filter-based selection to unread messages

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/messages/bulk" \  -H "Content-Type: application/json" \  -d '{    "operation": "mark_read"  }'

{  "affected": 0,  "unread_total": 0}

GET/api/v1/inbox/messages/{message_id}

Get_message

Authorization

bearer_token

AuthorizationBearer <token>

In: header

`application/json`

curl -X GET "https://example.com/api/v1/inbox/messages/string"

{  "actions": [    {      "id": "string",      "kind": "link",      "label": "string",      "target": "string"    }  ],  "body": "string",  "channel_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "delivery": {    "deliver_at": "2019-08-24T14:15:22Z",    "expires_at": "2019-08-24T14:15:22Z",    "self_destruct_after_read_seconds": 0  },  "message_id": "string",  "priority": "low",  "recipient_user_id": "string",  "sender": {    "id": "string",    "kind": "string"  },  "state": {    "archived": true,    "dismissed": true,    "read": true,    "read_at": "2019-08-24T14:15:22Z"  },  "technical_notes": null,  "thread_id": "string",  "title": "string"}

POST/api/v1/inbox/messages/{message_id}/actions/{action_id}

Execute_action

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

message_id*string

action_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

idempotency_key?|

Idempotency key to dedupe repeated executions

payload?unknown

Optional structured payload for the action execution

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/messages/string/actions/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "action_id": "string",  "actor_user_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "message_id": "string",  "result": null,  "result_id": "string",  "status": "string"}

POST/api/v1/inbox/messages/{message_id}/dismiss

Dismiss_message

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

message_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

archive?boolean

Archive instead of dismiss

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/messages/string/dismiss" \  -H "Content-Type: application/json" \  -d '{}'

{  "archived": true,  "dismissed": true,  "message_id": "string"}

POST/api/v1/inbox/messages/{message_id}/read

Mark_read

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

message_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/messages/string/read"

{  "message_id": "string",  "read": true,  "unread_total": 0}

POST/api/v1/inbox/messages/{message_id}/receipts

Record_receipt

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

message_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

device?|

Optional device metadata

kind*string

Receipt kind (read or delivered)

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/messages/string/receipts" \  -H "Content-Type: application/json" \  -d '{    "kind": "string"  }'

{  "kind": "string",  "message_id": "string",  "recorded_at": "2019-08-24T14:15:22Z"}

POST/api/v1/inbox/messages/{message_id}/unread

Mark_unread

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

message_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/inbox/messages/string/unread"

{  "message_id": "string",  "read": true,  "unread_total": 0}

GET/api/v1/inbox/threads

List_threads

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

filter?

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: unread_count, message_count, latest_at. Default: -latest_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/inbox/threads"

{  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "threads": [    {      "channel_id": "string",      "highest_priority": "low",      "latest_at": "2019-08-24T14:15:22Z",      "latest_message_id": "string",      "latest_title": "string",      "message_count": 0,      "thread_id": "string",      "unread_count": 0    }  ]}

Inbox

200application/json

400

503

201application/json

400

403

503

200application/json

404

503

200application/json

503

200application/json

403

503

200application/json

400

503

202application/json

400

403

404

503

202application/json

400

403

200application/json

400

503

200application/json

403

404

503

200application/json

403

404

503

200application/json

403

404

503

200application/json

403

404

503

201application/json

403

404

503

200application/json

403

404

503

200application/json

400

503

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`