ShipMsgDocs
Contents

API reference

Inboxes

API reference descriptions are provided in English to preserve the exact published contract.

List authorized inboxes

GET /v1/accounts/{AC}/inboxes

getV1AccountsByAcInboxesPaginated200

Account-scoped credential: Required scope: `inboxes:read`. Alternatively, a normal tenant USER session may use `inboxes:read` through actual readable inbox membership in this workspace. Collection results include only accessible inboxes or their conversations; this grants no account-wide scopes, API-key permission, staff-delegation authority or platform access.

Parameters

Parameters
NameTypeRequiredDescription
limitquery · integer (1–100)
cursorquery · string (max 2048 chars)
includeSupervisionquery · boolean
ACpath · string (AC… SID)yesAccount SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create a shared inbox

POST /v1/accounts/{AC}/inboxes

postV1AccountsByAcInboxesIdempotency-Key required201

Required scope: `inboxes:write`.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
Request body (19 fields)
Request body
NameTypeRequiredDescription
assignmentStrategy"ROUND_ROBIN" | "LEAST_LOADED" | "BALANCED"
autoAssignbooleanHand new and queued conversations to available members by the assignment strategy when no routing rule decides. On by default.
bindingsobject[]
businessHoursobject
businessHours.holidaysstring (date)[]
businessHours.timezonestring (max 64 chars)yes
businessHours.weeklyobject[]yes
defaultAgentCapacityinteger (1–1000)
isDefaultboolean
leadPrincipalRefstring (max 128 chars) | nullThe team lead told about every missed target in this inbox.
namestring (max 128 chars)yes
reopenAfterSecondsinteger (0–31536000)A customer writing to a closed conversation after this quiet period starts a fresh conversation with fresh deadlines. Default 86400 (24 hours).
senderSidsstring (WA… SID)[]yes
slaPoliciesobject[]
slaPolicyobject
slaPolicy.firstResponseSecondsinteger (1–2592000)yes
slaPolicy.nextResponseSecondsinteger (1–2592000)yes
slaPolicy.resolutionSecondsinteger (1–2592000)yes
slaWarningPercentinteger (10–99)Warn the assignee when this share of a response target has elapsed. Default 80.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Get an inbox

GET /v1/accounts/{AC}/inboxes/{IB}

getV1AccountsByAcInboxesByIb200

Required scope: `inboxes:read`.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update an inbox

PATCH /v1/accounts/{AC}/inboxes/{IB}

patchV1AccountsByAcInboxesByIbIdempotency-Key required200

Required scope: `inboxes:write`.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes
Request body (19 fields)
Request body
NameTypeRequiredDescription
assignmentStrategy"ROUND_ROBIN" | "LEAST_LOADED" | "BALANCED"
autoAssignbooleanHand new and queued conversations to available members by the assignment strategy when no routing rule decides. On by default.
bindingsobject[]
businessHoursobject
businessHours.holidaysstring (date)[]
businessHours.timezonestring (max 64 chars)yes
businessHours.weeklyobject[]yes
defaultAgentCapacityinteger (1–1000)
isDefaultboolean
leadPrincipalRefstring (max 128 chars) | nullThe team lead told about every missed target in this inbox.
namestring (max 128 chars)
reopenAfterSecondsinteger (0–31536000)A customer writing to a closed conversation after this quiet period starts a fresh conversation with fresh deadlines. Default 86400 (24 hours).
senderSidsstring (WA… SID)[]
slaPoliciesobject[]
slaPolicyobject
slaPolicy.firstResponseSecondsinteger (1–2592000)yes
slaPolicy.nextResponseSecondsinteger (1–2592000)yes
slaPolicy.resolutionSecondsinteger (1–2592000)yes
slaWarningPercentinteger (10–99)Warn the assignee when this share of a response target has elapsed. Default 80.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Delete an empty non-default inbox

DELETE /v1/accounts/{AC}/inboxes/{IB}

deleteV1AccountsByAcInboxesByIb200

Required scope: `inboxes:write`.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List the people who can be assigned this inbox's conversations

GET /v1/accounts/{AC}/inboxes/{IB}/members

getV1AccountsByAcInboxesByIbMembers200

Inbox members and the business's owners and admins, with their name, whether they are available now, and how many open conversations they hold. Manual assignment accepts any of them; automatic assignment uses only those available with free capacity. Account-scoped credential: Required scope: `inboxes:read`. Alternatively, a normal tenant USER session may use `inboxes:read` on the exact inbox resolved from this resource. Actual inbox membership, tenant/subaccount visibility and per-operation checks still apply. This does not grant account-wide scopes, API-key permission, staff-delegation authority or platform access.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List live agent presence

GET /v1/accounts/{AC}/inboxes/{IB}/presence

getV1AccountsByAcInboxesByIbPresencePaginated200

Account-scoped credential: Required scope: `inboxes:read`. Alternatively, a normal tenant USER session may use `inboxes:read` on the exact inbox resolved from this resource. Actual inbox membership, tenant/subaccount visibility and per-operation checks still apply. This does not grant account-wide scopes, API-key permission, staff-delegation authority or platform access.

Parameters

Parameters
NameTypeRequiredDescription
limitquery · integer (1–100)
cursorquery · string (max 2048 chars)
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Heartbeat agent presence

POST /v1/accounts/{AC}/inboxes/{IB}/presence

postV1AccountsByAcInboxesByIbPresenceIdempotency-Key required200

Account-scoped credential: Required scope: `inboxes:write`. Alternatively, a normal tenant USER session may use `conversations:write` on the exact inbox resolved from this resource. Actual inbox membership, tenant/subaccount visibility and per-operation checks still apply. This does not grant account-wide scopes, API-key permission, staff-delegation authority or platform access.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes
Request body (3 fields)
Request body
NameTypeRequiredDescription
capacityinteger (1–1000)
leaseIdstring (uuid)yes
state"AVAILABLE" | "BUSY" | "AWAY" | "OFFLINE"yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Get supervisor queue state

GET /v1/accounts/{AC}/inboxes/{IB}/queue

getV1AccountsByAcInboxesByIbQueue200

Account-scoped credential: Required scope: `inboxes:read`. Alternatively, a normal tenant USER session may use `inboxes:read` on the exact inbox resolved from this resource. Actual inbox membership, tenant/subaccount visibility and per-operation checks still apply. This does not grant account-wide scopes, API-key permission, staff-delegation authority or platform access.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List ordered routing rules

GET /v1/accounts/{AC}/inboxes/{IB}/routing-rules

getV1AccountsByAcInboxesByIbRoutingRulesPaginated200

Required scope: `inboxes:read`.

Parameters

Parameters
NameTypeRequiredDescription
limitquery · integer (1–100)
cursorquery · string (max 2048 chars)
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create a routing rule

POST /v1/accounts/{AC}/inboxes/{IB}/routing-rules

postV1AccountsByAcInboxesByIbRoutingRulesIdempotency-Key required201

Required scope: `inboxes:write`.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes
Request body (5 fields)
Request body
NameTypeRequiredDescription
action"ASSIGN_ROUND_ROBIN" | "ASSIGN_LEAST_LOADED" | "ASSIGN_BALANCED" | "ASSIGN_PRINCIPAL" | "QUEUE" | "BOT_HANDOFF"yes
actionTargetstring (max 128 chars)
enabledboolean
matchobjectyes
priorityinteger (1–10000)yesEvaluation order. Enabled rules are tried from the highest number down and the first match wins; rules sharing a number are tried in creation order. Give specific rules a higher number than generic catch-all rules.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Evaluate routing rules without mutation

POST /v1/accounts/{AC}/inboxes/{IB}/routing-rules/dry-run

postV1AccountsByAcInboxesByIbRoutingRulesDryRunIdempotency-Key required200

Required scope: `inboxes:write`.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes
Request body (5 fields)
Request body
NameTypeRequiredDescription
contactSidstring (CT… SID)yes
keywordTextstring (max 4096 chars)
occurredAtstring (date-time)
senderSidstring (WA… SID)yes
trigger"INBOUND" | "OUTBOUND"yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update a routing rule

PATCH /v1/accounts/{AC}/inboxes/{IB}/routing-rules/{ruleId}

patchV1AccountsByAcInboxesByIbRoutingRulesByRuleidIdempotency-Key required200

Required scope: `inboxes:write`.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes
ruleIdpath · string (uuid)yes
Request body (5 fields)
Request body
NameTypeRequiredDescription
action"ASSIGN_ROUND_ROBIN" | "ASSIGN_LEAST_LOADED" | "ASSIGN_BALANCED" | "ASSIGN_PRINCIPAL" | "QUEUE" | "BOT_HANDOFF"
actionTargetstring (max 128 chars)
enabledboolean
matchobject
priorityinteger (1–10000)Evaluation order. Enabled rules are tried from the highest number down and the first match wins; rules sharing a number are tried in creation order. Give specific rules a higher number than generic catch-all rules.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Delete a routing rule

DELETE /v1/accounts/{AC}/inboxes/{IB}/routing-rules/{ruleId}

deleteV1AccountsByAcInboxesByIbRoutingRulesByRuleid200

Required scope: `inboxes:write`.

Parameters

Parameters
NameTypeRequiredDescription
ACpath · string (AC… SID)yesAccount SID
IBpath · string (IB… SID)yes
ruleIdpath · string (uuid)yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.