> ## Documentation Index > Fetch the complete documentation index at: https://docs.protodesk.io/llms.txt > Use this file to discover all available pages before exploring further. # Assign a conversation ## OpenAPI ````yaml POST /conversations/{conversationId}/assign openapi: 3.1.0 info: title: Protodesk API version: 0.1.0 description: > The Protodesk Platform API: sync your customers in, attach your own business objects (orders, bookings, listings) to conversations, post and read messages across channels, and receive every workspace event via signed webhooks or a resumable SSE stream. Authenticate every request with a workspace-scoped API key: `Authorization: Bearer pk_live_...`. Create endpoints accept an `Idempotency-Key` header so retries are always safe. Lists use opaque cursor pagination (`data` / `hasMore` / `nextCursor`). Task-oriented guides: [docs.protodesk.io](https://docs.protodesk.io). servers: - url: https://api.protodesk.io/v1 description: Production - url: http://localhost:8080/v1 description: Local development security: [] tags: - name: Customers description: People or companies contacting a workspace across channels. - name: Conversations description: Customer conversations attached to channels and external business objects. - name: Messages description: Customer, agent, AI, system, and internal messages inside conversations. - name: Channel identities description: >- The same customer across WhatsApp, email, chat, and more — linked identities per channel. - name: Statuses & priorities description: The workspace's conversation statuses and priority levels. - name: Assignments description: >- Who a conversation has been assigned to, over time. Assign via POST /conversations/{conversationId}/assign. - name: Webhooks description: Webhook subscriptions for receiving workspace events. - name: Realtime description: Server-sent event stream of workspace events. - name: API Keys description: Create, list, and revoke workspace API keys. - name: Account description: The workspace and scopes behind your API key. - name: System description: Service metadata and health endpoints. paths: /conversations/{conversationId}/assign: post: tags: - Conversations summary: Assign a conversation operationId: assignConversation parameters: - name: conversationId in: path required: true schema: type: string example: conv_x6q5vl75f5d53m7oet2k4r5w6a - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssignConversationRequest' responses: '200': description: Assigned conversation. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Idempotency-Replayed: $ref: '#/components/headers/IdempotencyReplayed' content: application/json: schema: $ref: '#/components/schemas/Conversation' default: $ref: '#/components/responses/Error' security: - ApiKeyAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: > Optional retry key for safely replaying create requests. Reusing the same key with a different request body returns 409. schema: type: string minLength: 8 maxLength: 255 example: 8db8e596-7c1a-4fd5-a728-4d6c99f4e66b schemas: AssignConversationRequest: type: object description: > Requires assignee or team. Send an assignee with an empty id, or an empty team string, to clear that field. minProperties: 1 properties: assignee: $ref: '#/components/schemas/Assignee' team: type: string description: External team or routing hint. example: canggu-rentals Conversation: type: object description: | Every key is always present; optional fields are null when unset. required: - id - externalId - subject - status - priority - channel - customerId - assignee - team - tags - externalObject - metadata - channelIdentityId - createdAt - updatedAt properties: id: type: string example: conv_x6q5vl75f5d53m7oet2k4r5w6a externalId: type: - string - 'null' example: inquiry_123 subject: type: string example: Inquiry for 2BR Villa in Canggu status: $ref: '#/components/schemas/ConversationStatus' priority: $ref: '#/components/schemas/ConversationPriority' channel: type: string example: whatsapp customerId: type: string example: cus_x6q5vl75f5d53m7oet2k4r5w6a assignee: oneOf: - $ref: '#/components/schemas/Assignee' - type: 'null' description: Null when the conversation is unassigned. team: type: - string - 'null' example: canggu-rentals tags: type: array items: type: string externalObject: oneOf: - $ref: '#/components/schemas/ExternalObject' - type: 'null' description: Null when no external object is attached. metadata: type: object additionalProperties: true channelIdentityId: type: - string - 'null' description: The channel identity that opened this conversation, if any. example: cid_x6q5vl75f5d53m7oet2k4r5w6a routingNotes: type: object additionalProperties: true nullable: true description: >- Routing hints and resolution reasons recorded at create time (debugging). createdAt: type: string format: date-time updatedAt: type: string format: date-time Assignee: type: object description: > Who the conversation is assigned to. Set `id` to an empty string to clear the assignment. required: - id properties: type: type: string enum: - user - ai-agent default: user id: type: string description: External assignee id, such as an owner, agent, or AI agent id. example: owner_456 ConversationStatus: type: string description: > Workspace-defined status key. Every workspace is seeded with `open`, `pending`, `resolved`, and `closed`; workspaces can define their own. Use `GET /v1/statuses` to list the keys valid for your workspace. Unknown keys are rejected with `conversations.unknown_status`. pattern: ^[a-z0-9][a-z0-9_-]{0,62}$ example: open ConversationPriority: type: string description: > Workspace-defined priority key. Every workspace is seeded with `low`, `normal`, `high`, and `urgent`; workspaces can define their own. Use `GET /v1/priorities` to list the keys valid for your workspace. Unknown keys are rejected with `conversations.unknown_priority`. pattern: ^[a-z0-9][a-z0-9_-]{0,62}$ example: normal ExternalObject: type: object description: Snapshot of your business object attached to the conversation. required: - type - id - title - url - metadata properties: type: type: string example: villa_listing id: type: string example: listing_123 title: type: - string - 'null' example: 2BR Villa in Canggu url: type: - string - 'null' format: uri example: https://example.com/listings/listing_123 metadata: type: object additionalProperties: true example: ownerId: owner_456 agencyId: agency_789 ErrorEnvelope: type: object required: - error properties: error: $ref: '#/components/schemas/Error' Error: type: object required: - code - message - requestId properties: code: type: string example: route.not_found message: type: string example: Not found requestId: type: string example: req_x6q5vl75f5d53m7oet2k4r5w6a headers: RequestId: description: Request id for tracing this request in logs and support. schema: type: string example: req_x6q5vl75f5d53m7oet2k4r5w6a IdempotencyReplayed: description: Present with true when a response was replayed from an idempotency key. schema: type: string enum: - 'true' RateLimitLimit: description: >- Request budget for the route class (read or write) applied to this request. schema: type: integer example: 40 RateLimitRemaining: description: Requests remaining in the current budget after this request. schema: type: integer example: 39 RateLimitReset: description: Seconds until the budget refills to its full limit. schema: type: integer example: 1 RetryAfter: description: Seconds to wait before retrying, sent with 429 responses. schema: type: integer example: 1 responses: Error: description: >- Error response. All /v1 responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. A 429 (rate_limit.exceeded) additionally carries Retry-After. Request bodies exceeding the route-class limit (1KB reads, 64KB writes) return 413 (request.body_too_large). headers: X-Request-Id: $ref: '#/components/headers/RequestId' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: Protodesk API key description: > Use a workspace API key in the Authorization header. Keys use pk_live__ for production and pk_test__ for test mode. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.