> ## 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. # Consultar relatório de conversas > Relatório de conversas, com uma linha por protocolo. Para volumes grandes, use a exportação do sistema, que roda em segundo plano. ## OpenAPI ````yaml /api-reference/openapi.yaml get /reports/conversations 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: /reports/conversations: get: tags: - reports summary: Consultar relatório de conversas description: >- Relatório de conversas, com uma linha por protocolo. Para volumes grandes, use a exportação do sistema, que roda em segundo plano. parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/perPage' - name: date_start in: query description: >- Início do período, no fuso da empresa: `AAAA-MM-DD` ou `AAAA-MM-DD HH:mm:ss`. Só com a data, conta a partir de 00:00:00. schema: type: string example: '2026-09-01 00:00:00' required: true - name: date_finish in: query description: >- Fim do período, no mesmo formato. Só com a data, vale até 23:59:59 daquele dia. schema: type: string example: '2026-09-30 23:59:59' required: true - name: dateType in: query description: >- `updated` considera as datas de criação, conclusão e atualização. `created` considera só a data de criação. schema: type: string enum: - updated - created default: updated - name: days in: query description: 'Alternativa ao período: os últimos N dias.' schema: type: integer example: 30 - name: status in: query schema: type: string - name: users in: query description: >- Ids dos atendentes (o `id` de `GET /users`), separados por vírgula. Atendente que não é da sua empresa responde `404` (`ERR_API_USER_NOT_FOUND`). schema: type: string example: '3' - name: queues in: query description: >- Ids das filas, separados por vírgula. Id que não é da sua empresa responde `422` (`ERR_API_INVALID_REFERENCE`). schema: type: string example: '7' - name: channels in: query description: >- Ids dos canais, separados por vírgula. Id que não é da sua empresa responde `422` (`ERR_API_INVALID_REFERENCE`). schema: type: string example: '4' - name: tags in: query description: >- Ids das tags, separados por vírgula. Id que não é da sua empresa responde `422` (`ERR_API_INVALID_REFERENCE`). schema: type: string example: 3,7 - name: wrapupTypes in: query description: >- Ids das qualificações, separados por vírgula. Id que não é da sua empresa responde `422` (`ERR_API_INVALID_REFERENCE`). schema: type: string example: '12' - name: contactSearchParams in: query description: Busca por contato. schema: type: string example: marina - name: protocol in: query description: Número de protocolo do atendimento. schema: type: string example: '2026090800125' - name: conversationType description: 'Tipo da conversa: receptiva, ativa, por campanha ou por agendamento.' in: query schema: type: string enum: - incoming - outcoming - campaign - outcoming_api - outcoming_automation - outcoming_schedule description: | Como a conversa começou: | valor | significado | | --- | --- | | `incoming` | Receptiva (o contato falou primeiro). | | `outcoming` | Ativa (um atendente iniciou pelo painel). | | `campaign` | Disparo de campanha. | | `outcoming_api` | Iniciada por esta API. | | `outcoming_automation` | Iniciada por uma automação do Flow. | | `outcoming_schedule` | Envio programado. | responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ConversationReportRow' meta: $ref: '#/components/schemas/PageMeta' '400': description: >- Faltou `date_start` ou `date_finish` (`ERR_COMPANY_OR_DATE_NOT_DEFINED`). 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: ConversationReportRow: type: object description: >- Uma passagem de atendimento. Os nomes das chaves vêm em minúsculas, como `userid`, `channelid` e `contactid`. properties: protocol: type: integer description: Número do protocolo, que identifica a passagem de atendimento. example: 448120 channelid: type: integer nullable: true example: 11 channelname: type: string nullable: true example: Instagram Loja channeltype: type: string nullable: true example: instagram channelaccount: type: string nullable: true description: Conta do canal no provedor. example: '@lojaexemplo' ticketid: type: integer nullable: true example: 90211 ticketnps: type: boolean nullable: true description: Indica se o atendimento é de pesquisa de satisfação. updateat: type: string format: date-time nullable: true description: >- Data do encerramento. Se o atendimento ainda estiver aberto, é a data da última alteração. userid: type: integer nullable: true description: >- Atendente, pelo id de usuário nesta empresa. Vem `null` quando ninguém atendeu ou quando o atendente não faz mais parte da empresa. Nesse caso a linha continua no relatório, e `username` mostra quem atendeu. example: 3 username: type: string nullable: true example: Marina Alves userprofileurl: type: string nullable: true description: URL da foto do atendente. contactid: type: integer nullable: true example: 842 contactcreatedat: type: string format: date-time nullable: true description: >- Data em que o contato foi cadastrado. Serve para separar quem está no primeiro contato de quem já é recorrente. contactname: type: string nullable: true example: Maria Silva contactnumber: type: string nullable: true example: '5511987654321' contactemail: type: string nullable: true example: maria.silva@exemplo.com.br contactcode: type: string nullable: true example: CLI-00842 contactorigin: type: string nullable: true example: site contactcpfcnpj: type: string nullable: true example: '12345678909' queueid: type: integer nullable: true example: 2 queuename: type: string nullable: true example: Suporte createdat: type: string format: date-time description: Início da passagem. finishedat: type: string format: date-time nullable: true description: Fim da passagem. Vem `null` enquanto ela estiver aberta. nps: type: boolean nullable: true wrapupid: type: integer nullable: true description: Qualificação registrada no encerramento. wrapupchatbot: type: boolean nullable: true description: Indica se a qualificação foi feita pelo chatbot, sem atendente. wrapuptypeid: type: integer nullable: true description: Tipo da qualificação. Veja a lista em `GET /wrapup-types`. example: 12 wrapuptypename: type: string nullable: true example: Dúvida resolvida wrapupnotes: type: string nullable: true description: Observação escrita no encerramento. status: type: string enum: - closed - open_noservice - inservice_automation - inservice_waiting - inservice_attending description: > Situação da passagem: | valor | significado | | --- | --- | | `closed` | Encerrada. | | `open_noservice` | O atendimento foi fechado sem que esta passagem fosse encerrada. | | `inservice_automation` | Em automação, sem atendente. | | `inservice_waiting` | Aguardando na fila. | | `inservice_attending` | Em atendimento com um atendente. | example: closed chattype: type: string description: >- Como a conversa começou, em texto pronto para exibir (sempre em português). Valores possíveis: `Receptivo`, `Ativo - Manual`, `Ativo - Campanha`, `Ativo - API`, `Ativo - Automação` ou `Ativo - Agendamento`. example: Receptivo tags: type: array nullable: true description: Tags do contato no momento da consulta. items: type: object properties: id: type: integer example: 3 name: type: string example: Cliente VIP color: type: string example: '#6941C6' 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 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.