> ## 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.

# Assumir, passar ou soltar uma conversa

> Troque o dono de uma conversa num número com Conversation Routing: take, pass ou release.

Troca o dono de **uma conversa** (um cliente). O `id` aceita o id da conexão ou
o id da sessão (`cloud-<uuid>`).

| `action` | Quem pode | O que faz |
| - | - | - |
| `take` | D-API como parceiro de escalonamento | Assume a conversa de quem for o dono. |
| `pass` | D-API como dona da conversa | Entrega a conversa. Sem `targetRole`, vai para o escalonamento. |
| `release` | D-API como dona da conversa | Deixa a conversa livre; a próxima mensagem do cliente decide o dono. |

Guia completo, com casos de uso e webhooks:
[Vários parceiros no mesmo número](https://docs.d-api.cloud/api-oficial/multiplos-parceiros.md#4-trocar-o-dono-de-uma-conversa).

## Exemplo

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

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

## Erros

| HTTP | `code` | Quando |
| - | - | - |
| 400 | `INVALID_INPUT` | `to` sem telefone, `targetRole` fora de `pass`, `metadata` acima de 2000 caracteres. |
| 403 | `NOT_ESCALATION_PARTNER` | `take` sem a D-API ser o parceiro de escalonamento. |
| 400 | `THREAD_CONTROL_NOT_ENABLED` | Número sem roteamento ou termos não aceitos pela empresa. |
| 400 | `ACTION_NOT_ENABLED` | Ação ou destino não habilitado na conta. |
| 400 | `META_GRAPH_ERROR` | Outra recusa da Meta; `data.metaCode` traz o código. |


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/connections/cloud-api/{id}/thread-control
openapi: 3.1.0
info:
  title: D-API - Infraestrutura WhatsApp Completa
  description: >-
    Solução escalável e robusta para gestores de automação, SaaS e usuários
    finais que precisam de uma integração WhatsApp confiável. Oferece múltiplas
    instâncias simultâneas, webhooks em tempo real, dashboard intuitivo e API
    REST documentada com 99.9% de uptime e latência inferior a 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: Produção
security:
  - ApiKeyAuth: []
tags:
  - name: Início
    description: Endpoints base
  - name: Sessões
    description: Endpoints para gerenciamento de sessões
  - name: Mensagens
    description: Endpoints para envio de mensagens
  - name: Cloud API
    description: >-
      WhatsApp API Oficial (Meta Cloud API): conexão manual, gestão de templates
      (listar/criar/excluir) e envio de templates.
  - name: Ligações URA
    description: >-
      Disparo de ligações de voz (URA): individual ou em massa, com áudio ou
      fluxo IVR.
  - name: SMS
    description: 'Envio de SMS: individual ou em massa.'
  - name: Comandos
    description: >-
      Consulta de comandos assíncronos (async: true) pelo commandId retornado no
      enfileiramento.
paths:
  /api/v1/connections/cloud-api/{id}/thread-control:
    post:
      tags:
        - Cloud API
      summary: Assumir, passar ou soltar uma conversa
      description: >-
        Troca o dono de UMA conversa (um cliente) num número com Conversation
        Routing. O `id` aceita o id da conexão ou o id da sessão
        (`cloud-<uuid>`). `to` é o telefone do cliente.


        `action`:

        - `take`: a D-API assume a conversa. Só funciona se a D-API for o
        parceiro de escalonamento (`isEscalation` em GET /routing). Enviar
        mensagem de atendimento tem o mesmo efeito.

        - `pass`: a D-API (dona atual) entrega a conversa. Sem `targetRole` vai
        para o parceiro de escalonamento; com `targetRole` (`customer_service`,
        `ctwa`, `marketing`, `utility`, `escalation`, `ai_agent`) vai para o
        dono daquela entrada.

        - `release`: a D-API (dona atual) solta a conversa; a próxima mensagem
        do cliente é roteada de novo pela configuração da empresa.


        `metadata` (até 2000 caracteres) chega ao app que recebe a conversa.


        Erros: `NOT_ESCALATION_PARTNER` (take sem ser parceiro de
        escalonamento), `THREAD_CONTROL_NOT_ENABLED` (número sem Conversation
        Routing ou termos não aceitos), `ACTION_NOT_ENABLED` (ação ou destino
        não habilitado na conta), `INVALID_INPUT`, `META_GRAPH_ERROR` (demais
        recusas da Meta, com `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: Resposta bem-sucedida
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key para autenticação. Formato: <API_KEY>'

````

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