# contacts.history Histórico do contato. Linha do tempo do contato (mais recente primeiro) e atividade por semana. `filter`: all, conversation (mensagens, notas internas, eventos de atendimento), purchases (compras), automations (execuções de automação); `all` inclui também oportunidades e tarefas. `weekly` cobre as últimas 12 semanas (janelas de 7 dias terminando hoje, no fuso da conta, da mais antiga à atual) com `total`, `thisWeek` e `peak` (`weeksAgo` 0 = esta semana; null sem atividade), e não muda com nenhum filtro. Itens: até 300 mais recentes por fonte; cada um traz `eventName` (veja `contacts.history_filter_options`). Paginação: `before` = `nextBefore` da resposta anterior. Filtros novos (aba Histórico de Atividades): `q` (texto no título e no detalhe, sem acento nem caixa), `eventNames`, `from`/`to` (ISO com fuso, inclusivos), `tagIds`, `flowIds`, `pipelineIds` (E entre filtros, qualquer valor dentro da lista). Qualquer filtro novo presente, até `eventNames: []`, liga o modo ampliado: entram também execuções de flow (`type: flow`) e eventos de domínio (`type: event`, como etiqueta adicionada ou oportunidade mudou de etapa). Sem eles a resposta é a de sempre. - Endpoint: `POST https://app.atomiks.com.br/api/v1/contacts.history` (corpo JSON) - Quem pode chamar: membro da conta - Escopo da chave: `crm:read` - Grava dados: não - Pela chave de API: sim - Ferramenta MCP: `contacts_history` - Ficha em JSON: `https://app.atomiks.com.br/api/v1/openapi.json` (operationId `contacts.history`) ## Entrada | Campo | Tipo | Obrigatório | Nota | |---|---|---|---| | `contactId` | string (uuid) | sim | | | `filter` | "all" \| "conversation" \| "purchases" \| "automations" | não | | | `limit` | integer | não | | | `before` | string (date-time) | não | | | `q` | string | não | | | `eventNames` | string[] | não | | | `from` | string (date-time) | não | | | `to` | string (date-time) | não | | | `tagIds` | string (uuid)[] | não | | | `flowIds` | string (uuid)[] | não | | | `pipelineIds` | string (uuid)[] | não | |
JSON Schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "filter": { "type": "string", "enum": [ "all", "conversation", "purchases", "automations" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "before": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "q": { "type": "string", "minLength": 1, "maxLength": 200 }, "eventNames": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "tagIds": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "flowIds": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "pipelineIds": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "contactId" ] } ```
## Exemplo ```bash curl -X POST https://app.atomiks.com.br/api/v1/contacts.history \ -H "Authorization: Bearer $ATOMIKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"contactId":"00000000-0000-0000-0000-000000000000","filter":"all"}' ``` CLI: ```bash node cli/atomiks.mjs contacts.history --json '{"contactId":"00000000-0000-0000-0000-000000000000","filter":"all"}' ``` MCP: ferramenta `contacts_history` com a mesma entrada. ## Saída Sucesso: `{"data": ...}` com o formato abaixo. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "weekly": { "type": "object", "properties": { "weeks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "count": { "type": "number" } }, "required": [ "start", "count" ], "additionalProperties": false } }, "total": { "type": "number" }, "thisWeek": { "type": "number" }, "peak": { "anyOf": [ { "type": "object", "properties": { "count": { "type": "number" }, "weeksAgo": { "type": "number" } }, "required": [ "count", "weeksAgo" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "weeks", "total", "thisWeek", "peak" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "attendance", "note", "sale", "opportunity", "task", "automation", "event", "flow" ] }, "eventName": { "type": "string" }, "category": { "type": "string", "enum": [ "conversation", "purchases", "automations", "other" ] }, "at": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "channelKind": { "anyOf": [ { "type": "string", "enum": [ "whatsapp_cloud", "whatsapp_web", "instagram" ] }, { "type": "null" } ] }, "valueCents": { "type": [ "number", "null" ] } }, "required": [ "id", "type", "eventName", "category", "at", "title", "detail", "channelKind", "valueCents" ], "additionalProperties": false } }, "nextBefore": { "type": [ "string", "null" ] } }, "required": [ "weekly", "items", "nextBefore" ], "additionalProperties": false } ``` ## Erros `{"error": {"code", "message", "requestId"}}`. Códigos: `invalid_input` (400), `unauthorized` (401), `forbidden` / `account_pending` / `scope_missing` (403), `not_found` (404), `limit_reached` (409), `internal` (500).