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

# Transferir fila e/ou atendente

> Transfere o atendimento para outra fila, outro atendente ou ambos. O atendimento passa para `pending`. Informe pelo menos um dos dois campos.



## OpenAPI

````yaml /api-reference/openapi.yaml post /tickets/{id}/transfer
openapi: 3.0.3
info:
  title: Connecta DESK API pública
  version: 1.0.0
  description: >
    API pública do Connecta DESK, disponível em `/api/v1`. O acesso é feito com
    um token gerado no módulo de tokens. Cada token tem permissões por **módulo
    × método**, e toda leitura de lista é paginada.


    ## Autenticação


    ```

    Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

    ```


    O token pertence a uma **empresa**, e não a um usuário. A empresa usada é
    sempre a do token, então enviar `companyId` no corpo não tem efeito. Token
    ausente, inválido, revogado ou expirado recebe a mesma resposta `401`.


    ## Ordem de verificação


    1. **token** → `401`

    2. **empresa ativa** → `403`

    3. **API habilitada no plano** → `403 ERR_API_NOT_ENABLED` (não se aplica a
    on-premise)

    4. **rate limit da empresa** → `429`

    5. **permissão do token** → `403 ERR_API_FORBIDDEN_SCOPE`


    ## Ids de usuário


    Todo id de usuário na API é o id do usuário **nesta empresa**, o mesmo que
    `GET /users` devolve. Vale para o que a API responde (`user.id`,
    `assignedTo.id`, `userCreated.id`) e para o que ela aceita (`userId`,
    `userIds`, `assignedToUserId` e o `{id}` das rotas de usuário).


    A mesma pessoa pode trabalhar em várias empresas, com nome e perfil
    diferentes em cada uma, e tem um id diferente em cada empresa.


    Um id que não pertence a esta empresa responde `404`, com a mesma mensagem
    de um id inexistente.


    ## Paginação


    Todo `GET` de lista é paginado. O `meta` traz apenas `page`, `perPage` e
    `hasMore`, sem o total de registros. Para percorrer tudo, avance `page`
    enquanto `hasMore` for `true`.


    ## Idempotência


    Opcional em `POST`/`PUT`, pelo header `Idempotency-Key`. Se você repetir a
    chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada (com
    `Idempotent-Replay: true`). Com a mesma chave e um corpo diferente, a
    resposta é `409`.
servers:
  - url: https://api.connectadesk.com/api/v1
    description: Produção
security:
  - apiToken: []
tags:
  - name: contacts
    description: Cadastro de contatos, campos extras e origem de marketing.
  - name: tickets
    x-displayName: Conversas
    description: Abertura, transferência, encerramento e qualificação de conversas.
  - name: messages
    description: Envio assíncrono e leitura de mensagens.
  - name: tags
    description: Tags e vínculo com atendimentos.
  - name: queues
    description: Filas de atendimento e seus atendentes.
  - name: wrapups
    description: Tipos de qualificação.
  - name: users
    description: Atendentes e administradores.
  - name: schedules
    description: Mensagens programadas.
  - name: quick-messages
    description: Respostas rápidas.
  - name: campaigns
    description: Disparos em massa.
  - name: crm
    description: Painéis, etapas, cards e indicadores.
  - name: channels
    description: Canais (somente leitura).
  - name: reports
    description: Relatórios e dashboards.
  - name: products
    description: Catálogo de produtos, categorias e desempenho nas vendas.
  - name: custom-fields
    description: >-
      Campos personalizados de contato e de card, e variáveis globais da
      empresa.
  - name: profiles
    description: Perfis de permissões da empresa (somente leitura).
  - name: webchat
    description: >-
      Webchat nativo pelo seu sistema: abrir sessão de um visitante, enviar e
      ler mensagens. O token precisa do escopo `webchat` (GET e POST).
paths:
  /tickets/{id}/transfer:
    parameters:
      - $ref: '#/components/parameters/idParam'
    post:
      tags:
        - tickets
      summary: Transferir fila e/ou atendente
      description: >-
        Transfere o atendimento para outra fila, outro atendente ou ambos. O
        atendimento passa para `pending`. Informe pelo menos um dos dois campos.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queueId:
                  type: integer
                  nullable: true
                  description: Fila de destino. Com `null`, o atendimento fica sem fila.
                  example: 7
                userId:
                  type: integer
                  nullable: true
                  description: >-
                    Atendente de destino. Com `null`, o atendimento fica sem
                    atendente responsável.
                  example: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Ticket'
        '400':
          description: '`ERR_API_TRANSFER_TARGET_REQUIRED`: nenhum destino foi informado.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    idParam:
      name: id
      in: path
      required: true
      schema:
        type: integer
      example: 1042
  schemas:
    Ticket:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
          enum:
            - open
            - pending
            - closed
          description: |
            Situação do atendimento:

            | valor | significado |
            | --- | --- |
            | `open` | Em andamento, com um atendente. |
            | `pending` | Aguardando na fila, sem atendente. |
            | `closed` | Encerrado. |
        unreadMessages:
          type: integer
          description: Mensagens ainda não lidas pelo atendente.
        lastMessage:
          type: string
          nullable: true
        isGroup:
          type: boolean
          description: O contato é um grupo, e não uma pessoa.
        automation:
          type: boolean
          description: >-
            A conversa está com a automação (Flow), e não com uma pessoa. Fica
            em `pending`, sem atendente.
        metaWindowOpenTimestamp:
          type: string
          format: date-time
          nullable: true
          description: >-
            Quando abriu a janela de atendimento da Meta (canais oficiais do
            WhatsApp): a última mensagem do cliente. Dentro da janela dá para
            mandar mensagem livre; fora dela, só modelo aprovado. `null` quando
            o canal não tem janela ou ela ainda não abriu.
          example: '2026-08-18T14:20:03.000Z'
        metaWindowType:
          type: integer
          nullable: true
          description: >-
            Duração da janela da Meta, em horas: `24` (padrão) ou `72` (conversa
            iniciada por anúncio de clique para o WhatsApp). A janela fecha em
            `metaWindowOpenTimestamp` + estas horas.
          example: 24
        protocol:
          type: object
          nullable: true
          description: >-
            Protocolo atual do atendimento (o registro do atendimento corrente:
            quem atende, quando entrou na fila, quando foi respondido, quando
            encerrou). Vem em `GET /tickets` e `GET /tickets/{id}`; `null`
            quando o atendimento ainda não tem protocolo. Os demais endpoints de
            atendimento não trazem este campo.
          allOf:
            - $ref: '#/components/schemas/TicketProtocol'
        contact:
          type: object
          nullable: true
          description: >-
            Dados completos do contato, com tags, campos personalizados e campos
            de marketing. Você não precisa chamar `GET /contacts/{id}` para
            completar a listagem.
          allOf:
            - $ref: '#/components/schemas/Contact'
        queue:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Nome exibido.
            color:
              type: string
              description: Cor em hexadecimal, com `#`.
              example: '#6941C6'
        user:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Nome exibido.
        channel:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Nome exibido.
            type:
              type: string
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
                description: Nome exibido.
              color:
                type: string
                description: Cor em hexadecimal, com `#`.
                example: '#6941C6'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      example:
        id: 5120
        status: open
        unreadMessages: 2
        lastMessage: Perfeito, vou querer o tamanho M
        isGroup: false
        automation: false
        contact:
          id: 842
          name: Maria Silva
          number: '5511987654321'
          numberCountry: BR
          email: maria.silva@exemplo.com.br
          code: CLI-00842
          cpfCnpj: '12345678909'
          origin: site
          profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg
          isGroup: false
          instagramUsername: maria.silva
          lid: null
          sourceUrl: https://loja.exemplo.com.br/promo
          sourceId: '23851234567890123'
          headline: Coleção de inverno
          mediaType: image
          mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg
          utmSource: instagram
          utmMedium: cpc
          utmCampaign: inverno-2026
          utmId: '6543210987'
          fbclid: IwAR0xYzAbC123
          gclid: null
          ctwaClid: null
          tags:
            - id: 3
              name: Cliente VIP
              color: '#6941C6'
          customFields:
            - key: plano
              value: Ouro
              customFieldId: 91
              name: Plano
              type: select
          lastChannel:
            id: 11
            name: Instagram Loja
            type: instagram
          createdAt: '2026-07-14T13:22:05.412Z'
          updatedAt: '2026-08-18T09:41:17.883Z'
        queue:
          id: 13
          name: Comercial
          color: '#0E7490'
        user:
          id: 3
          name: Gabriel Goulart
        channel:
          id: 11
          name: Instagram Loja
          type: instagram
        tags:
          - id: 3
            name: Cliente VIP
            color: '#6941C6'
        metaWindowOpenTimestamp: '2026-08-18T14:20:03.000Z'
        metaWindowType: 24
        protocol:
          id: 21877
          userId: 3
          channelId: 11
          startedFrom: receptive
          startedFromContact: true
          fromApi: false
          fromAutomation: false
          campaignSlug: null
          rated: false
          nps: null
          createdAt: '2026-08-18T12:03:44.001Z'
          queuedAt: '2026-08-18T12:03:44.120Z'
          startedAt: '2026-08-18T12:05:10.300Z'
          userFirstAnswerAt: '2026-08-18T12:05:41.002Z'
          lastCustomerReplyAt: '2026-08-18T14:20:03.000Z'
          lastOperatorReplyAt: '2026-08-18T14:27:10.556Z'
          finishedAt: null
          ratingAt: null
          metaData:
            pedido: PED-48213
            origem: site
        createdAt: '2026-08-18T12:03:44.001Z'
        updatedAt: '2026-08-18T14:27:10.556Z'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Código fixo do erro, para você tratar cada caso no seu sistema.
              example: ERR_API_FORBIDDEN_SCOPE
            message:
              type: string
            details: {}
    TicketProtocol:
      type: object
      description: >-
        Protocolo de um atendimento. Cada vez que a conversa recomeça (nova
        mensagem depois de encerrada, nova campanha) nasce um protocolo novo; o
        atendimento traz o atual.
      properties:
        id:
          type: integer
          description: Número do protocolo.
          example: 21877
        userId:
          type: integer
          nullable: true
          description: >-
            Atendente responsável pelo protocolo (id do usuário na empresa, o
            mesmo de `/users`).
          example: 3
        channelId:
          type: integer
          nullable: true
          example: 11
        startedFrom:
          type: string
          nullable: true
          description: >-
            Como o protocolo começou: `receptive` (o cliente escreveu),
            `active-manual` (o atendente iniciou), `active-campaign`,
            `active-schedule`, `automation`, entre outros.
          example: receptive
        startedFromContact:
          type: boolean
          description: A conversa foi iniciada pelo contato.
        fromApi:
          type: boolean
          description: Aberto pela API.
        fromAutomation:
          type: boolean
          description: Aberto por uma automação.
        campaignSlug:
          type: string
          nullable: true
          description: Campanha que originou o protocolo, quando houver.
        rated:
          type: boolean
          description: O cliente respondeu à pesquisa de satisfação.
        nps:
          type: string
          nullable: true
          description: Nota da pesquisa de satisfação, quando respondida.
        createdAt:
          type: string
          format: date-time
        queuedAt:
          type: string
          format: date-time
          nullable: true
          description: Entrou na fila.
        startedAt:
          type: string
          format: date-time
          nullable: true
          description: Um atendente assumiu.
        userFirstAnswerAt:
          type: string
          format: date-time
          nullable: true
          description: Primeira resposta do atendente.
        lastCustomerReplyAt:
          type: string
          format: date-time
          nullable: true
          description: Última mensagem do cliente.
        lastOperatorReplyAt:
          type: string
          format: date-time
          nullable: true
          description: Última mensagem da empresa.
        finishedAt:
          type: string
          format: date-time
          nullable: true
          description: Encerramento. `null` enquanto o protocolo está em andamento.
        ratingAt:
          type: string
          format: date-time
          nullable: true
          description: Resposta da pesquisa de satisfação.
        metaData:
          type: object
          additionalProperties: true
          description: >-
            Dados do protocolo preenchidos pela empresa, em geral pelas
            automações (variáveis guardadas durante o atendimento). Objeto vazio
            quando não há nenhum.
          example:
            pedido: PED-48213
            origem: site
      example:
        id: 21877
        userId: 3
        channelId: 11
        startedFrom: receptive
        startedFromContact: true
        fromApi: false
        fromAutomation: false
        campaignSlug: null
        rated: false
        nps: null
        createdAt: '2026-08-18T12:03:44.001Z'
        queuedAt: '2026-08-18T12:03:44.120Z'
        startedAt: '2026-08-18T12:05:10.300Z'
        userFirstAnswerAt: '2026-08-18T12:05:41.002Z'
        lastCustomerReplyAt: '2026-08-18T14:20:03.000Z'
        lastOperatorReplyAt: '2026-08-18T14:27:10.556Z'
        finishedAt: null
        ratingAt: null
        metaData:
          pedido: PED-48213
          origem: site
    Contact:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Nome exibido.
        number:
          type: string
        numberCountry:
          type: string
          nullable: true
          description: >-
            País do número, no padrão ISO 3166-1 alfa-2. Deduzido do DDI quando
            o número é gravado pela API.
          example: BR
        email:
          type: string
          nullable: true
          example: marina@exemplo.com.br
        code:
          type: string
          nullable: true
        cpfCnpj:
          type: string
          nullable: true
          example: '12345678909'
        origin:
          type: string
          nullable: true
        profilePicUrl:
          type: string
          nullable: true
          example: https://cdn.exemplo.com.br/avatar/1042.jpg
        isGroup:
          type: boolean
          description: O contato é um grupo, e não uma pessoa.
        instagramUsername:
          type: string
          nullable: true
          example: marina.alves
        lid:
          type: string
          nullable: true
          example: '178452961234567'
        sourceUrl:
          type: string
          nullable: true
          example: https://loja.exemplo.com.br/promo
        sourceId:
          type: string
          nullable: true
          example: '23851234567890123'
        headline:
          type: string
          nullable: true
          example: Coleção de inverno
        mediaType:
          type: string
          nullable: true
          example: image
        mediaUrl:
          type: string
          nullable: true
          example: https://cdn.exemplo.com.br/anuncios/inverno.jpg
        utmSource:
          type: string
          nullable: true
          example: instagram
        utmMedium:
          type: string
          nullable: true
          example: cpc
        utmCampaign:
          type: string
          nullable: true
          example: inverno-2026
        utmId:
          type: string
          nullable: true
          example: '6543210987'
        fbclid:
          type: string
          nullable: true
          example: IwAR0xYzAbC123
        gclid:
          type: string
          nullable: true
        ctwaClid:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
                description: Nome exibido.
              color:
                type: string
                description: Cor em hexadecimal, com `#`.
                example: '#6941C6'
        customFields:
          type: array
          description: >-
            Campos personalizados de contato preenchidos. Sempre vem na
            resposta, como lista vazia quando o contato não tem nenhum.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
        lastChannel:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Nome exibido.
            type:
              type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      example:
        id: 842
        name: Maria Silva
        number: '5511987654321'
        numberCountry: BR
        email: maria.silva@exemplo.com.br
        code: CLI-00842
        cpfCnpj: '12345678909'
        origin: site
        profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg
        isGroup: false
        instagramUsername: maria.silva
        lid: null
        sourceUrl: https://loja.exemplo.com.br/promo
        sourceId: '23851234567890123'
        headline: Coleção de inverno
        mediaType: image
        mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg
        utmSource: instagram
        utmMedium: cpc
        utmCampaign: inverno-2026
        utmId: '6543210987'
        fbclid: IwAR0xYzAbC123
        gclid: null
        ctwaClid: null
        tags:
          - id: 3
            name: Cliente VIP
            color: '#6941C6'
        customFields:
          - key: plano
            value: Ouro
            customFieldId: 91
            name: Plano
            type: select
        lastChannel:
          id: 11
          name: Instagram Loja
          type: instagram
        createdAt: '2026-07-14T13:22:05.412Z'
        updatedAt: '2026-08-18T09:41:17.883Z'
    CustomFieldValue:
      type: object
      description: >-
        Valor de um campo personalizado, junto com a definição do campo. Assim
        você não precisa chamar `GET /custom-fields` para saber qual é o campo
        91.
      properties:
        key:
          type: string
          nullable: true
          description: >-
            Identificador fixo do campo. Use-o para indicar o campo ao gravar
            valores, porque o `name` pode ser renomeado no painel e a integração
            deixaria de funcionar sem aviso.
        value:
          type: string
          description: Valor preenchido no campo, no formato definido pelo tipo.
        customFieldId:
          type: integer
          description: Id da definição do campo personalizado.
          example: 91
        name:
          type: string
          nullable: true
          description: Nome exibido.
        type:
          type: string
          nullable: true
          description: Tipo do campo, que define o formato aceito no valor.
      example:
        key: plano
        value: Ouro
        customFieldId: 91
        name: Plano
        type: select
  responses:
    NotFound:
      description: >-
        O recurso não existe ou pertence a outra empresa. Por segurança, a
        resposta é a mesma nos dois casos.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_NOT_FOUND
              message: Registro não encontrado.
    UnprocessableEntity:
      description: >-
        O corpo está bem formado, mas falta um campo obrigatório ou algum valor
        não é aceito. Por exemplo, `application` diferente de `contact`/`card`,
        `orderedIds` vazio ou `name` em branco.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_VALIDATION
              message: >-
                O parâmetro `application` é obrigatório e aceita "contact" ou
                "card".
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: Token da API no formato `sk_live_…`.

````

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