POST

`messages.list`

Obtém as mensagens mais recentes de uma conversa da empresa do token, excluindo linhas com deleted=true.

Grupo: MensagensRevisão: 2026-10-02Escopo recomendado: messages.list

Exemplos seguros e fictícios. O domínio example.invalid e a credencial demonstrativa abaixo não funcionam. Use o token real somente no servidor da sua integração e nunca o inclua em páginas públicas.

Parâmetros

Parâmetros aceitos por messages.list
Campo	Tipo	Obrigatoriedade	Descrição	Exemplo fictício
`conversation_id`	string (UUID)	Obrigatório	ID da conversa.	`"22222222-2222-4222-8222-222222222222"`
`limit`	integer	Opcional	Máximo de mensagens. Padrão: 50; mínimo 1, máximo 200.	`50`
`before`	string	Opcional	Cursor opaco retornado em next_cursor para buscar a página seguinte. Por compatibilidade, também aceita o UUID de uma mensagem da mesma conversa. Máximo: 2048 caracteres.	`"eyJ2IjoxLCJpZCI6IjU1NTU1NTU1LTU1NTUtNDU1NS04NTU1LTU1NTU1NTU1NTU1NSIsImF0IjoiMjAyNi0wOS0xOFQxMjowMDowMC4wMDBaIn0"`

Exemplos fictícios

Os exemplos documentam o formato; eles não executam nenhuma operação.

Requisição

cURL demonstrativo

curl --request POST \
  'https://example.invalid/api/v1/CREDENCIAL_FICTICIA_SEM_VALOR/messages.list' \
  --header 'Content-Type: application/json' \
  --data '{"conversation_id":"22222222-2222-4222-8222-222222222222","limit":50,"before":"eyJ2IjoxLCJpZCI6IjU1NTU1NTU1LTU1NTUtNDU1NS04NTU1LTU1NTU1NTU1NTU1NSIsImF0IjoiMjAyNi0wOS0xOFQxMjowMDowMC4wMDBaIn0"}'

Corpo JSON

{
  "conversation_id": "22222222-2222-4222-8222-222222222222",
  "limit": 50,
  "before": "eyJ2IjoxLCJpZCI6IjU1NTU1NTU1LTU1NTUtNDU1NS04NTU1LTU1NTU1NTU1NTU1NSIsImF0IjoiMjAyNi0wOS0xOFQxMjowMDowMC4wMDBaIn0"
}

Resposta HTTP 200

{
  "ok": true,
  "method": "messages.list",
  "result": {
    "total": 1,
    "total_count": 1,
    "messages": [
      {
        "id": "55555555-5555-4555-8555-555555555555",
        "sender_type": "system",
        "content": "Nota de exemplo",
        "message_type": "note",
        "media_url": null,
        "delivery_status": null,
        "created_at": "2026-09-18T12:00:00.000Z",
        "delivered_at": null,
        "read_at": null
      }
    ],
    "hasMore": false,
    "next_cursor": null
  }
}

Erros

Condições de erro específicas de messages.list
HTTP	Código	Condição
400	`BAD_REQUEST`	conversation_id ausente/inválido ou cursor before inválido.
403	`NO_COMPANY`	Token sem empresa associada.
404	`NOT_FOUND`	Conversa inexistente/de outra empresa, ou cursor que não pertence ao histórico consultado.

Consulte também os erros globais e limites.

Observações

Ordenação estável por created_at decrescente, com valores null primeiro, e id decrescente para desempate.
total é o tamanho do lote retornado; total_count conta todo o histórico não excluído da conversa. hasMore indica continuação e next_cursor contém o cursor opaco da próxima página ou null.
Reenvie next_cursor em before sem interpretar ou modificar seu conteúdo. O UUID legado de uma mensagem da mesma conversa também é aceito como âncora.
Conversa inexistente/de outra empresa ou cursor ausente desse histórico retorna HTTP 404 NOT_FOUND. Cursor malformado, adulterado ou maior que 2048 caracteres retorna HTTP 400 BAD_REQUEST.
Cada item inclui delivered_at e read_at; ambos podem ser null. Eles representam a primeira evidência persistida pelo SYSLED, não o instante físico exato no aparelho. Em linhas legadas/incompletas, até status delivered/read pode permanecer sem horário até surgir evidência correspondente.
Resposta ilustrativa do campo result; IDs, nomes e valores são fictícios. Campos adicionais podem existir.
Pode retornar conteúdo de conversas e URLs de mídia. Use escopo exclusivo, aplique as regras de proteção de dados da sua empresa e não registre o conteúdo sem necessidade.