Set a conversation disposition

POST

/api/v1/conversations/{conversation_id}/disposition

curl --request POST \
  --url https://api.inside.chat/api/v1/conversations/example/disposition \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "disposition": "example" }'

• Hosted Gateway
• Local development

Required scopes: conversation_read, conversation_update
Data access: –
MCP tool: conversation_disposition_set
Note: Write
Note: Idempotency-Key required
Note: mapped native author

Set a configured disposition on an ordinary persisted conversation by its string value with an enabled native author mapped to this exact website. Native execution is denied on Salesforce-integrated websites; disposition IDs are unsupported. Results are retained for 24 hours. A permanent content-free tombstone prevents the same key from creating a new effect after result expiry. Reuse the same key and identical input when retrying. Changed input or policy/revisions conflict. Current policy is checked before result reuse. An unknown outcome returns 409 outcome_unknown; never retry with a new key automatically.

Authorizations

• installation_token
• oauth_client_credentials
  conversation_read conversation_update

Parameters

Path Parameters

conversation_id

required

string

/^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

Query Parameters

website_id

string

/^web_[0-9]{1,20}_[1-9][0-9]{0,18}$/

Optional; if present must match the resource owner.

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters /^[!-~]+$/

A stable key for this intended effect. Reuse the same key and input for retries; never automatically replace it after an unknown outcome.

Request Body^required

Media typeapplication/json

object

disposition

required

A configured disposition string, nonempty after trimming; maximum length is 200 UTF-16 code units.

string

>= 1 characters <= 200 characters

Example ^generated

{
  "disposition": "example"
}

Responses

200

Authorized result. Projection depends on current scopes and data policy.

Media typeapplication/json

The disposition now set on the conversation.

object

data

required

object

success

required

conversation_id

required

string

/^con_/

dispositions

required

Array<string>

Example

{
  "data": {
    "success": true
  }
}

Headers

X-Gateway-Operation-Id

string

/^op_[a-f0-9]{64}$/

Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.

400

Invalid, duplicate or unsupported request parameters.

401

Missing, expired or revoked installation credential.

404

Resource not found or not permitted by current authority.

409

Idempotency_conflict: the key has different input or authority revisions; operation_in_progress: the same command is pending; operation_conflict: native business state rejects the change; outcome_unknown: the native result is uncertain or no longer retained. Keep the same key and input for retries; never automatically create a new key or resubmit the effect.

Media typeapplication/problem+json

object

type

required

string

title

required

string

status

required

integer

Allowed value: 409

code

required

string

Allowed values: idempotency_conflict operation_in_progress operation_conflict outcome_unknown

request_id

required

string

Example

{
  "status": 409,
  "code": "idempotency_conflict"
}

Headers

X-Gateway-Operation-Id

string

/^op_[a-f0-9]{64}$/

Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.

422

The requested capability is not available for application installations.

429

Per-app quota exceeded.

Headers

Retry-After

integer

>= 1

503

Enrollment, native service or required authority is unavailable.