> ## Documentation Index
> Fetch the complete documentation index at: https://docs.d-api.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Take, pass or release a conversation

> Change a conversation's owner on a number with Conversation Routing: take, pass or release.

Changes the owner of **one conversation** (one customer). The `id` accepts the
connection id or the session id (`cloud-<uuid>`).

| `action` | Who can | What it does |
| - | - | - |
| `take` | D-API as the escalation partner | Takes the conversation from whoever owns it. |
| `pass` | D-API as the conversation owner | Hands the conversation over. Without `targetRole`, it goes to escalation. |
| `release` | D-API as the conversation owner | Makes the conversation idle; the customer's next message picks the owner. |

Full guide, with use cases and webhooks:
[Multiple partners on the same number](https://docs.d-api.cloud/en/api-oficial/multiplos-parceiros.md#4-change-a-conversation’s-owner).

## Example

```bash theme={null}
curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/<CONNECTION_ID>/thread-control \
  -H "Authorization: <YOUR_SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "take", "to": "5551999999999" }'
```

```json theme={null}
{ "success": true, "data": { "action": "take", "requestId": "abc123" } }
```

## Errors

| HTTP | `code` | When |
| - | - | - |
| 400 | `INVALID_INPUT` | `to` without a phone, `targetRole` outside `pass`, `metadata` over 2000 characters. |
| 403 | `NOT_ESCALATION_PARTNER` | `take` while D-API is not the escalation partner. |
| 400 | `THREAD_CONTROL_NOT_ENABLED` | Number without routing or terms not accepted by the business. |
| 400 | `ACTION_NOT_ENABLED` | Action or target not enabled on the account. |
| 400 | `META_GRAPH_ERROR` | Any other Meta refusal; `data.metaCode` has the code. |


## OpenAPI

````yaml api-reference/openapi.en.json POST /api/v1/connections/cloud-api/{id}/thread-control
openapi: 3.1.0
info:
  title: D-API - Complete WhatsApp Infrastructure
  description: >-
    A scalable, robust solution for automation managers, SaaS products and end
    users who need a reliable WhatsApp integration. It offers multiple
    simultaneous instances, real-time webhooks, an intuitive dashboard and a
    documented REST API with 99.9% uptime and latency under 30ms.
  version: 1.2.1
  contact:
    name: Suporte D-API
    email: suporte@d-api.cloud
    url: https://d-api.cloud
servers:
  - url: https://api.d-api.cloud
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Home
    description: Base endpoints
  - name: Sessions
    description: Endpoints for managing sessions
  - name: Messages
    description: Endpoints for sending messages
  - name: Cloud API
    description: >-
      WhatsApp Official API (Meta Cloud API): manual connection, template
      management (list/create/delete) and template sending.
  - name: IVR Calls
    description: 'Voice call dispatch (IVR): single or bulk, with audio or an IVR flow.'
  - name: SMS
    description: 'SMS sending: single or bulk.'
  - name: Commands
    description: >-
      Look up asynchronous commands (async: true) by the commandId returned when
      enqueued.
paths:
  /api/v1/connections/cloud-api/{id}/thread-control:
    post:
      tags:
        - Cloud API
      summary: Take, pass or release a conversation
      description: >-
        Changes the owner of ONE conversation (one customer) on a number with
        Conversation Routing. The `id` accepts the connection id or the session
        id (`cloud-<uuid>`). `to` is the customer's phone number.


        `action`:

        - `take`: D-API takes the conversation. Only works if D-API is the
        escalation partner (`isEscalation` in GET /routing). Sending a service
        message has the same effect.

        - `pass`: D-API (current owner) hands the conversation over. Without
        `targetRole` it goes to the escalation partner; with `targetRole`
        (`customer_service`, `ctwa`, `marketing`, `utility`, `escalation`,
        `ai_agent`) it goes to that entry point's owner.

        - `release`: D-API (current owner) releases the conversation; the
        customer's next message is routed again by the business's configuration.


        `metadata` (up to 2000 characters) reaches the app that receives the
        conversation.


        Errors: `NOT_ESCALATION_PARTNER` (take without being the escalation
        partner), `THREAD_CONTROL_NOT_ENABLED` (number without Conversation
        Routing or terms not accepted), `ACTION_NOT_ENABLED` (action or target
        not enabled on the account), `INVALID_INPUT`, `META_GRAPH_ERROR` (other
        Meta refusals, with `metaCode`).
      operationId: postApiV1ConnectionsCloud-apiByIdThread-control
      parameters:
        - schema:
            minLength: 1
            type: string
          in: path
          name: id
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  anyOf:
                    - const: take
                      type: string
                    - const: pass
                      type: string
                    - const: release
                      type: string
                to:
                  minLength: 1
                  type: string
                targetRole:
                  anyOf:
                    - const: ai_agent
                      type: string
                    - const: ctwa
                      type: string
                    - const: customer_service
                      type: string
                    - const: escalation
                      type: string
                    - const: marketing
                      type: string
                    - const: utility
                      type: string
                metadata:
                  maxLength: 2000
                  type: string
              required:
                - action
                - to
          multipart/form-data:
            schema:
              type: object
              properties:
                action:
                  anyOf:
                    - const: take
                      type: string
                    - const: pass
                      type: string
                    - const: release
                      type: string
                to:
                  minLength: 1
                  type: string
                targetRole:
                  anyOf:
                    - const: ai_agent
                      type: string
                    - const: ctwa
                      type: string
                    - const: customer_service
                      type: string
                    - const: escalation
                      type: string
                    - const: marketing
                      type: string
                    - const: utility
                      type: string
                metadata:
                  maxLength: 2000
                  type: string
              required:
                - action
                - to
          text/plain:
            schema:
              type: object
              properties:
                action:
                  anyOf:
                    - const: take
                      type: string
                    - const: pass
                      type: string
                    - const: release
                      type: string
                to:
                  minLength: 1
                  type: string
                targetRole:
                  anyOf:
                    - const: ai_agent
                      type: string
                    - const: ctwa
                      type: string
                    - const: customer_service
                      type: string
                    - const: escalation
                      type: string
                    - const: marketing
                      type: string
                    - const: utility
                      type: string
                metadata:
                  maxLength: 2000
                  type: string
              required:
                - action
                - to
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data: {}
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - success
            multipart/form-data:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data: {}
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - success
            text/plain:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data: {}
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - success
          description: Successful response
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key for authentication. Format: <API_KEY>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.