> ## 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. # Get conversations report > Conversation report, with one row per protocol. For large volumes, use the system's export, which runs in the background. ## OpenAPI ````yaml /api-reference/openapi.en.yaml get /reports/conversations openapi: 3.0.3 info: title: Connecta DESK Public API version: 1.0.0 description: >- Public API of Connecta DESK, available at `/api/v1`. Access uses a token generated in the tokens module. Each token has permissions per **module × method**, and every list read is paginated. ## Authentication ``` Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` The token belongs to a **company**, not to a user. The company used is always the token's company, so sending `companyId` in the body has no effect. A missing, invalid, revoked or expired token gets the same `401` response. ## Order of checks 1. **token** → `401` 2. **active company** → `403` 3. **API enabled on the plan** → `403 ERR_API_NOT_ENABLED` (does not apply to on-premise) 4. **company rate limit** → `429` 5. **token permission** → `403 ERR_API_FORBIDDEN_SCOPE` ## User ids Every user id in the API is the user's id **in this company**, the same one `GET /users` returns. This applies to what the API returns (`user.id`, `assignedTo.id`, `userCreated.id`) and to what it accepts (`userId`, `userIds`, `assignedToUserId` and the `{id}` in user routes). The same person can work in several companies, with a different name and profile in each one, and has a different id in each company. An id that does not belong to this company returns `404`, with the same message as an id that does not exist. ## Pagination Every list `GET` is paginated. The `meta` contains only `page`, `perPage` and `hasMore`, without the total number of records. To go through everything, keep advancing `page` while `hasMore` is `true`. ## Idempotency Optional on `POST`/`PUT`, through the `Idempotency-Key` header. If you repeat the call with the same key and the same body, you get the stored response (with `Idempotent-Replay: true`). With the same key and a different body, the response is `409`. servers: - url: https://api.connectadesk.com/api/v1 description: Production security: - apiToken: [] tags: - name: contacts description: Contact records, extra fields and marketing source. - name: tickets x-displayName: Tickets description: Opening, transferring, closing and wrap-up of tickets. - name: messages description: Asynchronous sending and reading of messages. - name: tags description: Tags and their link to tickets. - name: queues description: Service queues and their agents. - name: wrapups description: Wrap-up types. - name: users description: Agents and administrators. - name: schedules description: Scheduled messages. - name: quick-messages description: Quick replies. - name: campaigns description: Bulk sending. - name: crm description: Boards, stages, cards and metrics. - name: channels description: Channels (read only). - name: reports description: Reports and dashboards. - name: products description: Product catalog, categories and sales performance. - name: custom-fields description: Custom fields for contacts and cards, plus company-wide global variables. - name: profiles description: Company permission profiles (read only). - name: webchat description: >- Native webchat from your own system: open a visitor session, send and read messages. The token needs the `webchat` scope (GET and POST). paths: /reports/conversations: get: tags: - reports summary: Get conversations report description: >- Conversation report, with one row per protocol. For large volumes, use the system's export, which runs in the background. parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/perPage' - name: date_start in: query description: >- Start of the period, in the company time zone: `YYYY-MM-DD` or `YYYY-MM-DD HH:mm:ss`. With only the date, it starts at 00:00:00. schema: type: string example: '2026-09-01 00:00:00' required: true - name: date_finish in: query description: >- End of the period, in the same format. With only the date, it runs until 23:59:59 of that day. schema: type: string example: '2026-09-30 23:59:59' required: true - name: dateType in: query description: >- `updated` considers the creation, closing and update dates. `created` considers only the creation date. schema: type: string enum: - updated - created default: updated - name: days in: query description: 'Alternative to the period: the last N days.' schema: type: integer example: 30 - name: status in: query schema: type: string - name: users in: query description: >- Agent ids (the `id` from `GET /users`), separated by commas. An agent that is not from your company returns `404` (`ERR_API_USER_NOT_FOUND`). schema: type: string example: '3' - name: queues in: query description: >- Queue ids, separated by commas. An id that is not from your company returns `422` (`ERR_API_INVALID_REFERENCE`). schema: type: string example: '7' - name: channels in: query description: >- Channel ids, separated by commas. An id that is not from your company returns `422` (`ERR_API_INVALID_REFERENCE`). schema: type: string example: '4' - name: tags in: query description: >- Tag ids, separated by commas. An id that is not from your company returns `422` (`ERR_API_INVALID_REFERENCE`). schema: type: string example: 3,7 - name: wrapupTypes in: query description: >- Wrap-up ids, separated by commas. An id that is not from your company returns `422` (`ERR_API_INVALID_REFERENCE`). schema: type: string example: '12' - name: contactSearchParams in: query description: Search by contact. schema: type: string example: marina - name: protocol in: query description: Ticket protocol number. schema: type: string example: '2026090800125' - name: conversationType description: 'Conversation type: inbound, outbound, campaign or scheduled.' in: query schema: type: string enum: - incoming - outcoming - campaign - outcoming_api - outcoming_automation - outcoming_schedule description: |- How the conversation started: | value | meaning | | --- | --- | | `incoming` | Inbound (the contact spoke first). | | `outcoming` | Outbound (an agent started it from the panel). | | `campaign` | Campaign send. | | `outcoming_api` | Started by this API. | | `outcoming_automation` | Started by a Flow automation. | | `outcoming_schedule` | Scheduled send. | 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: >- `date_start` or `date_finish` is missing (`ERR_COMPANY_OR_DATE_NOT_DEFINED`). components: parameters: page: name: page in: query description: Page number, starting at 1. An invalid value is treated as 1. schema: type: integer minimum: 1 default: 1 example: 1 perPage: name: perPage in: query description: >- Number of items per page. The maximum depends on the environment (default 100). schema: type: integer minimum: 1 maximum: 100 default: 20 example: 50 schemas: ConversationReportRow: type: object description: >- A service leg. Key names come in lowercase, such as `userid`, `channelid` and `contactid`. properties: protocol: type: integer description: Protocol number, which identifies the service leg. 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: Channel account at the provider. example: '@lojaexemplo' ticketid: type: integer nullable: true example: 90211 ticketnps: type: boolean nullable: true description: Whether the ticket is a satisfaction survey. updateat: type: string format: date-time nullable: true description: >- Closing date. If the ticket is still open, this is the date of the last change. userid: type: integer nullable: true description: >- Agent, by their user id in this company. Comes as `null` when nobody handled the ticket or when the agent is no longer part of the company. In that case the row stays in the report, and `username` shows who handled it. example: 3 username: type: string nullable: true example: Marina Alves userprofileurl: type: string nullable: true description: URL of the agent's photo. contactid: type: integer nullable: true example: 842 contactcreatedat: type: string format: date-time nullable: true description: >- Date the contact was added. Use it to tell first-time contacts from returning ones. 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: Start of the leg. finishedat: type: string format: date-time nullable: true description: End of the leg. Comes as `null` while it is open. nps: type: boolean nullable: true wrapupid: type: integer nullable: true description: Wrap-up recorded at closing. wrapupchatbot: type: boolean nullable: true description: Whether the wrap-up was done by the chatbot, with no agent. wrapuptypeid: type: integer nullable: true description: Wrap-up type. See the list at `GET /wrapup-types`. example: 12 wrapuptypename: type: string nullable: true example: Dúvida resolvida wrapupnotes: type: string nullable: true description: Note written at closing. status: type: string enum: - closed - open_noservice - inservice_automation - inservice_waiting - inservice_attending description: >- Status of the leg: | value | meaning | | --- | --- | | `closed` | Closed. | | `open_noservice` | The ticket was closed without this leg being closed. | | `inservice_automation` | In automation, with no agent. | | `inservice_waiting` | Waiting in the queue. | | `inservice_attending` | Being handled by an agent. | example: closed chattype: type: string description: >- How the conversation started, as display-ready text (always in Portuguese). Possible values: `Receptivo`, `Ativo - Manual`, `Ativo - Campanha`, `Ativo - API`, `Ativo - Automação` or `Ativo - Agendamento`. example: Receptivo tags: type: array nullable: true description: The contact's tags at the time of the query. 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: Whether there are more records beyond this page. example: true example: page: 1 perPage: 20 hasMore: true securitySchemes: apiToken: type: http scheme: bearer description: API token in the `sk_live_…` format. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.