Apps API · Conversation Sync
Conversation Sync: 3 endpoints
POST /api/v1/sync
Sync conversations
Scope: messages:sync:read · Called with: appToken · operationId: sync-conversations
Required app scope: messages:sync:read.
Returns sync events. next_cursor is decimal-encoded as a string inside DataResponse, not a CursorListResponse. next_cursor is a monotonically increasing positive integer: send it back unchanged as since_seq, use it only for ordering comparisons, and never compute it from event seq values; it can be greater than the seq of the last event on the page. Response wrapped in standard envelope.
Request body
application/json · SyncCommRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
device_id |
string | yes | Device ID |
limit |
integer (int32) | Maximum events to return | |
since_seq |
integer (int64) | yes | Last seen sync sequence |
Responses
200OK —application/json·DataResponseSyncResultBodydefaultError —application/problem+json·D8Error
POST /api/v1/sync/ack
Acknowledge conversation sync
Scope: messages:read_state:write · Called with: appToken · operationId: ack-sync-conversations
Required app scope: messages:read_state:write.
Advances the per-device sync cursor after the client has processed a sync batch.
Request body
application/json · AckSyncCommRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
app_version |
string | Client app version | |
device_id |
string | yes | Device ID |
platform |
string | Client platform | |
seq |
integer (int64) | yes | Highest processed sync sequence |
Responses
200OK —application/json·DataResponseMapStringInterface {}BodydefaultError —application/problem+json·D8Error
GET /api/v1/sync/status
Get sync inbox status
Scope: messages:read_state:read · Called with: appToken · operationId: get-sync-inbox-status
Required app scope: messages:read_state:read.
Returns the caller's inbox watermark: the highest available sync sequence and the highest sequence already delivered. Org/user identity is derived from the propagated principal, not request fields.
Responses
200OK —application/json·DataResponseInboxStatusResultBodydefaultError —application/problem+json·D8Error
