Listar mensagens da conversa

GET/api/v1/conversations/{conversationKey}/messages

Retorna o histórico da conversa paginado por cursor. Uma conversa fora da visibilidade do membro resulta em 404. Exige whatsapp.view_conversations. Sem since, pagina para trás a partir das mensagens mais recentes, para abrir uma conversa. Com since, pagina para frente a partir do instante informado, para acompanhamento contínuo. Os itens de cada página vêm em ordem cronológica nos dois modos. Consulte primeiro sem since. Depois, use em since o horário da última mensagem recebida. O limite é inclusivo: mensagens com esse mesmo horário podem repetir. Remova duplicatas pelo identificador da mensagem. Ao percorrer várias páginas para frente, mantenha since junto de cursor. Um cursor enviado sem since volta ao modo de leitura para trás.

Exemplos

A URL usa o servidor de produção. Defina PIPEFACIL_API_KEY e as variáveis de caminho (como SEQ ou ID) com os identificadores reais. Ajuste o corpo antes de executar: requisições de escrita alteram dados do workspace.

cURL

curl --request GET \
  --url "https://pipefacil-server.matchsales.com.br/api/v1/conversations/$CONVERSATIONKEY/messages" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY"

JavaScript

const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/conversations/${process.env.CONVERSATIONKEY}/messages`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const text = await response.text();
const data = text ? JSON.parse(text) : null;

Python

import os
import json
import requests

response = requests.request(
    "GET",
    f"https://pipefacil-server.matchsales.com.br/api/v1/conversations/{os.environ['CONVERSATIONKEY']}/messages",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
)
response.raise_for_status()
data = response.json() if response.content else None

Parâmetros

Nome	Local	Tipo	Obrigatório	Descrição
`conversationKey`	`path`	`string`	Sim	Identificador da conversa ou telefone que permita localizá-la.
`limit`	`query`	`integer`	Não	—
`cursor`	`query`	`string`	Não	Cursor opaco retornado pela página anterior. Mantenha `since` ao paginar para frente.
`channelId`	`query`	`string`	Não	Restringe o histórico a um único canal.
`since`	`query`	`string`	Não	Instante ISO 8601 UTC, por exemplo, 2026-08-25T03:14:00Z. Ativa a paginação para frente, com limite inclusivo. Uma data sem horário resulta em `400`.

Respostas

200Sucesso

Campo	Tipo	Descrição
`data`	`object`	—
`data.items`	`array`	—
`data.items[].id`	`string`	—
`data.items[].conversationId`	`string`	—
`data.items[].channelId`	`string`	Aceita null.
`data.items[].externalId`	`string`	Aceita null.
`data.items[].direction`	`string`	Valores: inbound, outbound.
`data.items[].senderPhone`	`string`	Aceita null.
`data.items[].recipientPhone`	`string`	Aceita null.
`data.items[].body`	`string`	—
`data.items[].previewText`	`string`	—
`data.items[].type`	`string`	—
`data.items[].status`	`string`	—
`data.items[].read`	`boolean`	—
`data.items[].timestamp`	`string`	Formato: date-time.
`data.items[].statusTimestamp`	`string`	Formato: date-time. Aceita null.
`data.items[].errorMessage`	`string`	Aceita null.
`data.items[].quotedText`	`string`	Aceita null.
`data.items[].quotedDirection`	`string`	Valores: inbound, outbound. Aceita null.
`data.items[].quotedMessageId`	`string`	Aceita null.
`data.items[].quotedType`	`string`	Aceita null.
`data.items[].quotedMedia`	`object`	Aceita null.
`data.items[].quotedMedia.mediaAssetId`	`string`	Aceita null.
`data.items[].quotedMedia.status`	`string`	Estado de ingestão da mídia armazenada. Aceita null.
`data.items[].quotedMedia.mediaType`	`string`	—
`data.items[].quotedMedia.contentType`	`string`	Aceita null.
`data.items[].quotedMedia.caption`	`string`	Aceita null.
`data.items[].quotedMedia.filename`	`string`	Aceita null.
`data.items[].quotedMedia.sizeBytes`	`integer`	Formato: int64. Aceita null.
`data.items[].quotedMedia.durationMs`	`integer`	Aceita null.
`data.items[].quotedMedia.width`	`integer`	Aceita null.
`data.items[].quotedMedia.height`	`integer`	Aceita null.
`data.items[].quotedMedia.providerMediaId`	`string`	Aceita null.
`data.items[].quotedMedia.providerMediaUrl`	`string`	Aceita null.
`data.items[].quotedMedia.contentUrl`	`string`	URL relativa para baixar o arquivo. Nula enquanto a mídia não estiver READY. A cópia do provedor para o armazenamento é assíncrona. Aceita null.
`data.items[].sentByUserId`	`string`	Aceita null.
`data.items[].origin`	`string`	Origem da mensagem: api, app, automation, agent ou outra. Aceita null.
`data.items[].originLabel`	`string`	Aceita null.
`data.items[].media`	`object`	Aceita null.
`data.items[].media.mediaAssetId`	`string`	Aceita null.
`data.items[].media.status`	`string`	Estado de ingestão da mídia armazenada. Aceita null.
`data.items[].media.mediaType`	`string`	—
`data.items[].media.contentType`	`string`	Aceita null.
`data.items[].media.caption`	`string`	Aceita null.
`data.items[].media.filename`	`string`	Aceita null.
`data.items[].media.sizeBytes`	`integer`	Formato: int64. Aceita null.
`data.items[].media.durationMs`	`integer`	Aceita null.
`data.items[].media.width`	`integer`	Aceita null.
`data.items[].media.height`	`integer`	Aceita null.
`data.items[].media.providerMediaId`	`string`	Aceita null.
`data.items[].media.providerMediaUrl`	`string`	Aceita null.
`data.items[].media.contentUrl`	`string`	URL relativa para baixar o arquivo. Nula enquanto a mídia não estiver READY. A cópia do provedor para o armazenamento é assíncrona. Aceita null.
`data.items[].content`	`object`	Dados estruturados de tipos sem corpo de texto, como anúncio de origem, localização, cartão de contato ou alvo de reação. Aceita null.
`data.items[].createdAt`	`string`	Formato: date-time.
`data.items[].editedAt`	`string`	Formato: date-time. Aceita null.
`data.items[].deletedAt`	`string`	Data da exclusão. O conteúdo pode permanecer no histórico de auditoria; a integração decide como exibi-lo. Formato: date-time. Aceita null.
`data.nextCursor`	`string`	Aceita null.
`data.hasMore`	`boolean`	—

Esquema OpenAPI

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ConversationMessage"
          }
        },
        "nextCursor": {
          "type": "string",
          "nullable": true
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    }
  }
}

400Falha de validação dos campos; `fieldErrors` contém os erros.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

Esquema OpenAPI

{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}

401Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

Esquema OpenAPI

{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}

403Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

Esquema OpenAPI

{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}

404Recurso não encontrado ou fora da visibilidade do membro.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

Esquema OpenAPI

{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}

429Limite de requisições excedido por workspace ou IP.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

Esquema OpenAPI

{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}

OpenAPI JSON Markdown desta operação

Listar mensagens da conversa

Exemplos

cURL

Parâmetros

Respostas

Precisa de ajuda?