> ## Documentation Index
> Fetch the complete documentation index at: https://help.wizebot.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar conversas
> Conversas por atividade recente — da mais recente para a mais antiga —, com paginação por cursor.
### Os dois filtros de identidade
**Ambos devolvem sempre uma lista, mesmo quando há um único resultado.** Nunca um objeto solto. Um mesmo telefone pode estar em conversas de contas de canal diferentes — medimos até 11 no pior caso — e um recurso que às vezes devolve lista e às vezes devolve um item é armadilha de integração. Quem quer a mais recente lê o primeiro item de `items`.
Os dois não alcançam o mesmo conjunto, e a diferença importa:
| | `channel_identifier` | `phone` |
|---|---|---|
| Precisão | praticamente unívoco | ambíguo: o mesmo número pode ser contatos diferentes em contas diferentes |
| Cobertura | não encontra contato sem vínculo de canal registrado | encontra |
**Prefira `channel_identifier` quando souber o endereço nativo** — ele é o identificador real do contato naquele canal. Mas saiba que ele depende de um vínculo que nem todo contato antigo tem: hoje, cerca de **5% das conversas ativas** pertencem a contatos sem esse vínculo, e para elas só o filtro `phone` responde. Se você busca por identidade e não encontra uma conversa que sabe existir, tente por `phone` antes de concluir que ela não existe.
Isso afeta **apenas os dois filtros de identidade**. A listagem sem filtro de identidade, a leitura de mensagens e a resolução de anexo não dependem desse vínculo e devolvem tudo normalmente.
### O que a resposta não traz
**Não há contagem de mensagens da conversa.** O contador que existe internamente está incorreto — ele só soma e nunca subtrai quando mensagens são removidas —, e publicar um número errado seria pior que não publicar nenhum. Para saber quantas mensagens uma conversa tem, pagine `GET /v1/conversations/{id}/messages`.
## OpenAPI
````yaml /openapi.json get /conversations
openapi: 3.1.0
info:
title: API WizeBot
version: 3.0.0
description: >-
A API da WizeBot tem duas camadas sobre a **mesma base**
`https://api.wizebot.com.br/v1`.
**Contrato multicanal** — a camada neutra. Os mesmos endpoints falam com
WhatsApp, com Telegram e com os canais que vierem depois. O canal não
aparece na URL nem no corpo: ele vem da conta escolhida como remetente.
Campos, códigos e mensagens em inglês.
**API de WhatsApp** — a camada específica do canal, com o que só o WhatsApp
tem. Continua existindo e não muda; quem já integrou com ela não precisa
migrar.
Toda requisição se autentica por cabeçalho. Não há autenticação por corpo
nem por query string.
servers:
- url: https://api.wizebot.com.br/v1
description: Produção
security:
- bearerAuth: []
tags:
- name: Canais
description: Contas de canal conectadas e o que cada uma aceita.
- name: Mensagens
description: Envio e status pelo contrato neutro, em qualquer canal.
- name: WhatsApp · Mensagens
description: Envio, status e modelos na camada específica de WhatsApp.
- name: WhatsApp · Contatos
description: Contatos e campos personalizados.
- name: WhatsApp · Etiquetas
description: Etiquetas e sua atribuição a contatos.
- name: WhatsApp · Sequências
description: Sequências agendadas de um contato.
- name: WhatsApp · Conta
description: Verificação da chave de API.
- name: Conversas
description: Leitura de diagnóstico das conversas — o que está esperando resposta.
paths:
/conversations:
get:
tags:
- Conversas
summary: Listar conversas
description: >-
Conversas por atividade recente — da mais recente para a mais antiga —,
com paginação por cursor.
### Os dois filtros de identidade
**Ambos devolvem sempre uma lista, mesmo quando há um único resultado.**
Nunca um objeto solto. Um mesmo telefone pode estar em conversas de
contas de canal diferentes — medimos até 11 no pior caso — e um recurso
que às vezes devolve lista e às vezes devolve um item é armadilha de
integração. Quem quer a mais recente lê o primeiro item de `items`.
Os dois não alcançam o mesmo conjunto, e a diferença importa:
| | `channel_identifier` | `phone` |
|---|---|---|
| Precisão | praticamente unívoco | ambíguo: o mesmo número pode ser
contatos diferentes em contas diferentes |
| Cobertura | não encontra contato sem vínculo de canal registrado |
encontra |
**Prefira `channel_identifier` quando souber o endereço nativo** — ele é
o identificador real do contato naquele canal. Mas saiba que ele depende
de um vínculo que nem todo contato antigo tem: hoje, cerca de **5% das
conversas ativas** pertencem a contatos sem esse vínculo, e para elas só
o filtro `phone` responde. Se você busca por identidade e não encontra
uma conversa que sabe existir, tente por `phone` antes de concluir que
ela não existe.
Isso afeta **apenas os dois filtros de identidade**. A listagem sem filtro de identidade, a leitura de mensagens e a resolução de anexo não dependem desse vínculo e devolvem tudo normalmente.
### O que a resposta não traz
**Não há contagem de mensagens da conversa.** O contador que existe
internamente está incorreto — ele só soma e nunca subtrai quando
mensagens são removidas —, e publicar um número errado seria pior que
não publicar nenhum. Para saber quantas mensagens uma conversa tem,
pagine `GET /v1/conversations/{id}/messages`.
operationId: listarConversas
parameters:
- name: channel
in: query
required: false
schema:
type: string
description: '`whatsapp`, `telegram`, `webchat`.'
- name: channel_id
in: query
required: false
schema:
type: string
description: Conta de canal, vinda de `GET /v1/channels`.
- name: status
in: query
required: false
schema:
type: string
enum:
- open
- resolved
- archived
- all
default: open
- name: assigned
in: query
required: false
schema:
type: boolean
description: Com ou sem atendente responsável.
- name: since
in: query
required: false
schema:
type: string
format: date-time
- name: until
in: query
required: false
schema:
type: string
format: date-time
- name: channel_identifier
in: query
required: false
schema:
type: string
description: Endereço nativo do contato no canal.
- name: phone
in: query
required: false
schema:
type: string
description: Telefone. Ambíguo por construção — ver acima.
- name: limit
in: query
required: false
schema:
type: integer
default: 25
maximum: 100
- name: cursor
in: query
required: false
schema:
type: string
description: '`next_cursor` da página anterior.'
responses:
'200':
description: Página de conversas.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
items:
type: array
items:
type: object
properties:
conversation_id:
type: string
description: >-
Identificador estável da conversa. É ele que vai
na leitura de mensagens.
contact_id:
type: string
channel:
type: string
channel_account_id:
type:
- string
- 'null'
status:
type: string
assigned:
type: boolean
unread_count:
type: integer
last_message_at:
type:
- string
- 'null'
format: date-time
last_inbound_at:
type:
- string
- 'null'
format: date-time
next_cursor:
type:
- string
- 'null'
timestamp:
type: string
format: date-time
example:
success: true
data:
items:
- conversation_id: 7f3e1a24-5b6c-4d8e-9f01-2a3b4c5d6e7f
contact_id: 9c8b7a65-4321-4def-8abc-1234567890ab
channel: whatsapp
channel_account_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
status: open
assigned: false
unread_count: 2
last_message_at: '2026-09-13T02:44:51.602Z'
last_inbound_at: '2026-09-13T02:44:51.602Z'
next_cursor: eyJ0IjoiMjAyNi0wOS0xMyJ9
timestamp: '2026-09-13T03:20:00.000Z'
'400':
description: '`INVALID_PARAM` — limit must be an integer between 1 and 100.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErroDaApi'
example:
success: false
statusCode: 400
timestamp: '2026-09-13T03:20:00.000Z'
path: /api/v1/conversations
method: GET
message:
error: INVALID_PARAM
message: limit must be an integer between 1 and 100.
details:
min: 1
max: 100
errorId: ERR-MTUD0DBO-KKRMP8
'401':
description: '`UNAUTHORIZED` — Invalid or missing API key.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErroDaApi'
example:
success: false
statusCode: 401
timestamp: '2026-09-13T03:20:00.000Z'
path: /api/v1/conversations
method: GET
message:
error: UNAUTHORIZED
message: Invalid or missing API key.
errorId: ERR-MTUD0DBO-KKRMP8
'429':
description: '`RATE_LIMITED` — Too many requests.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErroDaApi'
example:
success: false
statusCode: 429
timestamp: '2026-09-13T03:20:00.000Z'
path: /api/v1/conversations
method: GET
message:
error: RATE_LIMITED
message: Too many requests.
errorId: ERR-MTUD0DBO-KKRMP8
components:
schemas:
ErroDaApi:
type: object
description: >-
Corpo de erro da API. `message` é um **objeto** com o código nomeado —
não uma string.
required:
- success
- statusCode
- message
properties:
success:
type: boolean
description: Sempre `false`.
statusCode:
type: integer
timestamp:
type: string
format: date-time
path:
type: string
description: >-
Caminho interno da requisição. Traz o prefixo `/api/v1` mesmo quando
você chamou por `/v1`: o apelido é reescrito antes do roteamento.
method:
type: string
message:
type: object
required:
- error
- message
properties:
error:
type: string
description: >-
Código nomeado. É por ele que se trata o erro em código, nunca
pelo texto.
message:
type: string
description: Descrição em inglês, para leitura humana.
details:
type: object
additionalProperties: true
description: >-
Contexto estruturado, presente nos códigos que o emitem —
`CHANNEL_MISMATCH`, `NO_OPEN_CONVERSATION`,
`RECIPIENT_NOT_ON_CHANNEL` e `UNSUPPORTED_CAPABILITY`.
errorId:
type: string
description: Identificador do erro. Cite-o ao falar com o suporte.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Chave de API no cabeçalho `Authorization: Bearer SUA-CHAVE`.
A API também aceita `x-api-key: SUA-CHAVE` e `Authorization: ApiKey
SUA-CHAVE` — as três formas são equivalentes, inclusive para o limite de
requisições.
A chave dá acesso total à conta e é de servidor para servidor: não a use
em navegador ou aplicativo móvel.
````