> ## Documentation Index > Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt > Use this file to discover all available pages before exploring further. # Pass, release or take a conversation > Move a conversation between apps on a [shared number](/docs/whatsapp/conversation-routing). **Proxy endpoint**: The body is forwarded to Meta unchanged and Meta's response is returned unchanged. Kapso records the call and updates the conversation's routing state. Only your escalation app can `take`. Kapso never retries: a `502` means the result is unknown and the action may have gone through. ## OpenAPI ````yaml /api/meta/whatsapp/openapi-whatsapp.yaml post /{phone_number_id}/thread_control openapi: 3.1.0 info: title: Kapso Meta Proxy API version: 1.0.0 description: > Kapso's Meta Proxy API provides a unified interface to WhatsApp Business Platform with enhanced features and Kapso-specific extensions. This API acts as a proxy layer between your application and WhatsApp, adding: - Simplified authentication with project-level API keys - Enhanced message metadata and tracking - Conversation management capabilities - Voice call integration - Extended contact and template management ## Base URL All API requests are made to: `https://api.kapso.ai/meta/whatsapp/v24.0` ## Authentication The API supports authentication via **X-API-Key header** (recommended): ``` X-API-Key: your_project_api_key ``` Alternative: Bearer token authentication is also supported for backward compatibility: ``` Authorization: Bearer your_access_token ``` Note: X-API-Key is the recommended authentication method for the Meta Proxy API. contact: name: Kapso Support url: https://kapso.ai email: dev@kap.so servers: - url: https://api.kapso.ai/meta/whatsapp/v24.0 description: Production server security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Messages description: Send and retrieve WhatsApp messages - name: Conversations description: Manage WhatsApp conversations - name: Contacts description: Manage WhatsApp contacts - name: Templates description: Manage message templates - name: Media description: Upload and retrieve media files - name: Calls description: Manage voice calls - name: Settings description: Account settings and configuration - name: Business Profile description: Business profile management - name: Phone Numbers description: Phone number management - name: Flows description: WhatsApp Flow management (Beta) - name: Block Users description: Block and unblock WhatsApp users - name: Usernames description: Reserve and manage WhatsApp business usernames paths: /{phone_number_id}/thread_control: parameters: - name: phone_number_id in: path required: true description: WhatsApp Business Phone Number ID schema: type: string example: '110987654321' post: tags: - Conversations summary: Pass, release or take a conversation description: > Move a conversation between apps on a [shared number](/docs/whatsapp/conversation-routing). **Proxy endpoint**: The body is forwarded to Meta unchanged and Meta's response is returned unchanged. Kapso records the call and updates the conversation's routing state. Only your escalation app can `take`. Kapso never retries: a `502` means the result is unknown and the action may have gone through. operationId: threadControl requestBody: required: true content: application/json: schema: type: object required: - messaging_product - action anyOf: - required: - to - required: - recipient properties: messaging_product: type: string enum: - whatsapp action: type: string enum: - take - release - pass to: type: string description: Customer phone number. Use `to` or `recipient`. example: '15551234567' recipient: type: string description: Customer business-scoped user ID. Use `to` or `recipient`. example: US.13491208655302741918 control_pass: type: object description: >- Pass only. Without it, the conversation goes to the escalation app. properties: target_role: type: string enum: - escalation - ai_agent - customer_service - marketing - utility - ctwa metadata: type: string maxLength: 2000 description: Passed to the app that receives the conversation. examples: pass: summary: Pass to the escalation app value: messaging_product: whatsapp to: '15551234567' action: pass control_pass: target_role: escalation metadata: Customer asked for a human take: summary: Take the conversation value: messaging_product: whatsapp recipient: US.13491208655302741918 action: take release: summary: Release the conversation value: messaging_product: whatsapp to: '15551234567' action: release responses: '200': description: Meta accepted the action content: application/json: schema: type: object properties: messaging_product: type: string example: whatsapp request_id: type: string description: Present when Meta returns it '403': description: >- Meta refused the action, for example error code `2494191` when Kapso may not take the conversation content: application/json: schema: type: object example: error: code: 2494191 message: >- You are not permitted to take thread control for this phone number. '409': description: Another action for this conversation is still in progress content: application/json: schema: type: object example: error: thread_control_in_progress detail: >- Another control action for this conversation is still in progress. '502': description: >- Meta did not answer; the result is unknown. Do not retry automatically. content: application/json: schema: type: object example: error: Meta API request failed detail: >- The thread control result is unknown. Do not retry automatically. components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: > Project API key for authentication. This is the recommended authentication method. Get your API key from the Kapso dashboard under Integrations > API keys. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | Bearer token authentication (alternative method). Note: X-API-Key authentication is recommended for the Meta Proxy API. ````