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

# Listar conversas

> Lista os atendimentos da empresa, ordenados pela data da última atualização.
Pela API não existe o filtro de visibilidade por atendente que a tela do sistema aplica. O token
enxerga todos os atendimentos da empresa.

Cada atendimento traz a janela da Meta (`metaWindowOpenTimestamp`, `metaWindowType`) e o
protocolo atual (`protocol`), carregados por página, sem chamada extra.




## OpenAPI

````yaml /api-reference/openapi.yaml get /tickets
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:
    get:
      tags:
        - tickets
      summary: Listar conversas
      description: >
        Lista os atendimentos da empresa, ordenados pela data da última
        atualização.

        Pela API não existe o filtro de visibilidade por atendente que a tela do
        sistema aplica. O token

        enxerga todos os atendimentos da empresa.


        Cada atendimento traz a janela da Meta (`metaWindowOpenTimestamp`,
        `metaWindowType`) e o

        protocolo atual (`protocol`), carregados por página, sem chamada extra.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/perPage'
        - name: status
          in: query
          description: >-
            Filtra pela situação do atendimento. Aceita vários valores separados
            por vírgula (ex.: `open,pending`).
          schema:
            type: string
            example: open,pending
        - name: queueId
          in: query
          description: Somente atendimentos desta fila.
          schema:
            type: integer
          example: 7
        - name: userId
          in: query
          description: Somente atendimentos deste atendente responsável.
          schema:
            type: integer
          example: 3
        - name: channelId
          in: query
          schema:
            type: integer
          example: 4
        - name: contactId
          in: query
          schema:
            type: integer
          example: 1042
        - name: tagId
          in: query
          description: Somente atendimentos com esta tag.
          schema:
            type: integer
          example: 3
        - name: from
          in: query
          description: Início do período, no fuso horário da empresa.
          schema:
            type: string
            format: date
          example: '2026-09-01'
        - name: to
          in: query
          description: Fim do período, no fuso horário da empresa.
          schema:
            type: string
            format: date
          example: '2026-09-30'
        - name: dateField
          in: query
          description: >-
            Define qual data o filtro de período usa: a de criação ou a da
            última atualização.
          schema:
            type: string
            enum:
              - created
              - updated
            default: created
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ticket'
                  meta:
                    $ref: '#/components/schemas/PageMeta'
components:
  parameters:
    page:
      name: page
      in: query
      description: Número da página, começando em 1. Um valor inválido é tratado como 1.
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    perPage:
      name: perPage
      in: query
      description: >-
        Quantidade de itens por página. O máximo depende do ambiente (padrão
        100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 50
  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'
    PageMeta:
      type: object
      required:
        - page
        - perPage
        - hasMore
      properties:
        page:
          type: integer
          example: 1
        perPage:
          type: integer
          example: 20
        hasMore:
          type: boolean
          description: Indica se há mais registros além desta página.
          example: true
      example:
        page: 1
        perPage: 20
        hasMore: true
    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
  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.