Start Integration Operation

Creates a durable operation record and queues an integration action. Support is action- and adapter-specific. The generic fallback invokes one ordinary action, remains limited by its maxExecutionTime (at most 119 seconds), and has no provider Start/Poll/Cancel adapter. The endpoint rejects fields named contentBase64. When input has a top-level fileRef, the server accepts its id, resolves it in the authenticated bot scope, and persists the complete immutable generation metadata; other input remains opaque JSON. File bytes are not part of this request.

Header Parameters

x-bot-id*string

Bot id

Idempotency-Key*string

Stable business-operation key. Reusing it with the same request returns the original operation; reusing it with a different request returns 409.

Length1 <= length <= 255

Request Body

application/json

Bounded control-plane request. The complete JSON body is limited to 68 KiB and input to 64 KiB. Fields named contentBase64 are rejected. A top-level input.fileRef is resolved from its id to authoritative immutable generation metadata in the authenticated bot scope; other input stays opaque action JSON. This endpoint does not upload file bytes. resourceKey is optional and reserves one provider resource without reducing parallelism for different or omitted keys.

TypeScript Definitions

Use the request body type in TypeScript.

type*string

Namespaced action type in : form

Length3 <= length <= 255

input*

Action input. A field named contentBase64 is rejected at any depth. If the top-level fileRef field is present, it must contain a non-empty id; client-supplied generation metadata is replaced with the authoritative scoped FileRef before persistence. Other fields are opaque.

resourceKey?string

Optional stable identity for the provider destination or path. Operations with the same key and pinned installation do not execute concurrently. It is part of the idempotent start request; callers must canonicalize it consistently.

Length1 <= length <= 255

timeoutSeconds?integer

Deadline for queued and adapter-managed operation work. It does not extend an ordinary action invocation beyond maxExecutionTime (at most 119 seconds). Automatic reconciliation stops at this deadline without changing outcome_unknown to failed.

Range1 <= value <= 86400

Default3600

Response Body

`application/json`

curl -X POST "https://example.com/v1/chat/integration-operations" \  -H "x-bot-id: string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "type": "string",    "input": {}  }'

{  "operationId": "3051932a-fdd2-48fa-b330-7e7d41535969",  "status": "queued",  "actionType": "string",  "resourceKey": "string",  "attempt": 0,  "progress": 0,  "progressMessage": "string",  "deadline": "2019-08-24T14:15:22Z",  "result": {},  "error": {    "code": "string",    "message": "string"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "startedAt": "2019-08-24T14:15:22Z",  "finishedAt": "2019-08-24T14:15:22Z"}

Empty

Start Integration Operation

Header Parameters

Request Body

Response Body

202application/json

default

`application/json`