Inbox

GET/api/v1/inbox/channels

List_channels

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

q?string

Full-text query applied to channel name and description

page?integer

1-indexed page number

Formatint64

Range0 <= value

page_size?integer

Page size

Formatint64

Range0 <= value

sort_by?string

Sort field

sort_order?string

Sort order (asc or desc)

Value in

"asc"
"desc"

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"    }  ],  "pagination": {    "has_more": true,    "page": 0,    "page_size": 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

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

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

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

unread?boolean

Only return unread messages

channel_id?string

Filter by channel id

priority?string

Filter by priority

thread_id?string

Filter by thread id

include_archived?boolean

Include archived messages

include_dismissed?boolean

Include dismissed messages

page?integer

1-indexed page number

Formatint64

Range0 <= value

page_size?integer

Page size

Formatint64

Range0 <= value

filter?array<string>

Additional filter expressions in the form field:operator:value

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"    }  ],  "pagination": {    "has_more": true,    "page": 0,    "page_size": 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

Path Parameters

message_id*string

Query Parameters

mark_read?boolean

Mark the message read while fetching

Response Body

`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

Response Body

`application/json`

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

{  "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

503

201application/json

400

403

503

200application/json

404

503

200application/json

503

200application/json

403

503

200application/json

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

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`