# Listar mensagens do negócio

`GET /api/v1/deals/{seq}/messages`

Consulta o histórico de mensagens do contato vinculado ao negócio, respeitando a visibilidade do membro.

## Autenticação

Envie a chave em `Authorization: Bearer pf_live_…`.

## Parâmetros

| Nome | Local | Obrigatório | Tipo | Descrição |
| --- | --- | --- | --- | --- |
| `seq` | path | Sim | `integer` | Sequência do negócio neste workspace. |
| `limit` | query | Não | `integer` | Tamanho da página. |
| `cursor` | query | Não | `string` | Cursor opaco da página anterior. |

## Respostas

### 200

Operação concluída.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `data` | `object` | Não |  |
| `data.items` | `array` | Não |  |
| `data.items[].id` | `string` | Não |  |
| `data.items[].conversationId` | `string` | Não |  |
| `data.items[].channelId` | `string` | Não | Aceita null. |
| `data.items[].externalId` | `string` | Não | Aceita null. |
| `data.items[].direction` | `string` | Não | Valores: inbound, outbound. |
| `data.items[].senderPhone` | `string` | Não | Aceita null. |
| `data.items[].recipientPhone` | `string` | Não | Aceita null. |
| `data.items[].body` | `string` | Não |  |
| `data.items[].previewText` | `string` | Não |  |
| `data.items[].type` | `string` | Não |  |
| `data.items[].status` | `string` | Não |  |
| `data.items[].read` | `boolean` | Não |  |
| `data.items[].timestamp` | `string` | Não | Formato: date-time. |
| `data.items[].statusTimestamp` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].errorMessage` | `string` | Não | Aceita null. |
| `data.items[].quotedText` | `string` | Não | Aceita null. |
| `data.items[].quotedDirection` | `string` | Não | Valores: inbound, outbound. Aceita null. |
| `data.items[].quotedMessageId` | `string` | Não | Aceita null. |
| `data.items[].quotedType` | `string` | Não | Aceita null. |
| `data.items[].quotedMedia` | `object` | Não | Aceita null. |
| `data.items[].quotedMedia.mediaAssetId` | `string` | Não | Aceita null. |
| `data.items[].quotedMedia.status` | `string` | Não | Estado de ingestão da mídia armazenada. Aceita null. |
| `data.items[].quotedMedia.mediaType` | `string` | Não |  |
| `data.items[].quotedMedia.contentType` | `string` | Não | Aceita null. |
| `data.items[].quotedMedia.caption` | `string` | Não | Aceita null. |
| `data.items[].quotedMedia.filename` | `string` | Não | Aceita null. |
| `data.items[].quotedMedia.sizeBytes` | `integer` | Não | Formato: int64. Aceita null. |
| `data.items[].quotedMedia.durationMs` | `integer` | Não | Aceita null. |
| `data.items[].quotedMedia.width` | `integer` | Não | Aceita null. |
| `data.items[].quotedMedia.height` | `integer` | Não | Aceita null. |
| `data.items[].quotedMedia.providerMediaId` | `string` | Não | Aceita null. |
| `data.items[].quotedMedia.providerMediaUrl` | `string` | Não | Aceita null. |
| `data.items[].quotedMedia.contentUrl` | `string` | Não | 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` | Não | Aceita null. |
| `data.items[].origin` | `string` | Não | Origem da mensagem: api, app, automation, agent ou outra. Aceita null. |
| `data.items[].originLabel` | `string` | Não | Aceita null. |
| `data.items[].media` | `object` | Não | Aceita null. |
| `data.items[].media.mediaAssetId` | `string` | Não | Aceita null. |
| `data.items[].media.status` | `string` | Não | Estado de ingestão da mídia armazenada. Aceita null. |
| `data.items[].media.mediaType` | `string` | Não |  |
| `data.items[].media.contentType` | `string` | Não | Aceita null. |
| `data.items[].media.caption` | `string` | Não | Aceita null. |
| `data.items[].media.filename` | `string` | Não | Aceita null. |
| `data.items[].media.sizeBytes` | `integer` | Não | Formato: int64. Aceita null. |
| `data.items[].media.durationMs` | `integer` | Não | Aceita null. |
| `data.items[].media.width` | `integer` | Não | Aceita null. |
| `data.items[].media.height` | `integer` | Não | Aceita null. |
| `data.items[].media.providerMediaId` | `string` | Não | Aceita null. |
| `data.items[].media.providerMediaUrl` | `string` | Não | Aceita null. |
| `data.items[].media.contentUrl` | `string` | Não | 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` | Não | 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` | Não | Formato: date-time. |
| `data.items[].editedAt` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].deletedAt` | `string` | Não | 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` | Não | Aceita null. |
| `data.hasMore` | `boolean` | Não |  |

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

### 401

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

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "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"
  ]
}
```

### 403

Autenticado, 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 | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "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"
  ]
}
```

### 404

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

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "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"
  ]
}
```

### 429

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

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "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"
  ]
}
```