# Consultar o processamento do histórico inicial GET /inbox/history-sync Mostra como foi o histórico inicial do pareamento mais recente desta inbox: o que o WhatsApp mandou e o que a api entregou aos webhooks. Só consulta; não pede histórico novo. - Sem pareamento desde que o servidor subiu, volta só `diagnosis: ["no_trace"]`: o rastro fica em memória e zera quando o servidor reinicia. - O `request_id` é o mesmo de `history_request_id` (`POST /inbox/connect`) e dos lotes do histórico desse pareamento. - Pedidos feitos em `POST /chats/history-sync` não aparecem aqui: acompanhe pelo `request_id` deles nos eventos. - `progress` em 100 não quer dizer que tudo foi entregue: veja `delivery_status`. A resposta pode trazer as URLs dos webhooks; trate como informação sensível. ## Autenticação ```json [ { "token": [] } ] ``` ```json { "token": { "name": "token", "type": "apiKey", "in": "header" } } ``` ## Respostas ```json { "200": { "description": "Estado observado da sincronização mais recente, ou diagnóstico sem rastreamento.", "content": { "application/json": { "schema": { "type": "object", "required": [ "diagnosis" ], "properties": { "request_id": { "type": "string", "description": "Identificador do histórico deste pareamento: o mesmo de `history_request_id` em `POST /inbox/connect` e dos lotes do histórico. Ausente sem rastreamento." }, "progress": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Progresso informado pelo WhatsApp (0 a 100). Chegar a 100 não garante que tudo foi entregue." }, "processing_stopped": { "type": "boolean", "description": "O processamento do histórico foi encerrado; veja `processing_complete` para saber se terminou inteiro." }, "processing_complete": { "type": "boolean", "description": "A api processou todo o histórico que o WhatsApp mandou." }, "pending_emissions": { "type": "integer", "description": "Lotes ainda sendo preparados para envio aos webhooks." }, "total_batches": { "type": "integer", "description": "Total de lotes gerados (a soma de `emitted`)." }, "delivery_status": { "type": "string", "enum": [ "pending", "delivered", "partial", "failed", "no_webhook", "no_batches" ], "description": "Resumo da entrega: `pending` (em andamento), `delivered` (tudo entregue), `partial` (parte entregue, parte falhou ou ficou de fora), `failed` (falhou sem nada entregue), `no_webhook` (nenhum webhook para receber), `no_batches` (nada a entregar)." }, "paired_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando foi o pareamento rastreado; `null` sem rastreamento." }, "diagnosis": { "type": "array", "items": { "type": "string" }, "description": "Códigos dos problemas encontrados; vazio quando está tudo certo. Ex.: `no_trace`, `no_history_received`, `chunks_aborted`, `no_webhook_configured`, `history_event_not_subscribed`, `delivery_failed`, `queue_dropped`." }, "no_webhook_configured": { "type": "boolean", "description": "Algum lote ficou sem webhook para receber." }, "serialization_failures": { "type": "integer", "description": "Lotes que a api não conseguiu montar para envio." }, "received": { "type": "object", "description": "O que chegou do WhatsApp.", "properties": { "contacts": { "type": "integer", "description": "Contatos recebidos na sincronização." }, "inline_contacts": { "type": "integer", "description": "Contatos que vieram dentro das partes do histórico." }, "labels": { "type": "integer", "description": "Etiquetas recebidas." }, "notifications": { "type": "integer", "description": "Avisos de parte do histórico recebidos." }, "chunks": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Partes do histórico por tipo: `INITIAL_BOOTSTRAP`, `INITIAL_STATUS_V3`, `FULL`, `RECENT`, `PUSH_NAME`, `NON_BLOCKING_DATA`, `nil_data` ou `other`." }, "chunks_ok": { "type": "integer", "description": "Partes processadas inteiras." }, "chunks_aborted": { "type": "integer", "description": "Partes interrompidas." }, "conversations": { "type": "integer", "description": "Conversas." }, "messages": { "type": "integer", "description": "Mensagens." }, "pushnames": { "type": "integer", "description": "Nomes de perfil." }, "calls": { "type": "integer", "description": "Registros de ligação." }, "skipped_filtered": { "type": "integer", "description": "Itens descartados por filtro." }, "skipped_malformed": { "type": "integer", "description": "Itens descartados por vir com defeito." } } }, "emitted": { "type": "object", "additionalProperties": { "type": "object", "properties": { "batches": { "type": "integer", "description": "Lotes gerados deste tipo." }, "items": { "type": "integer", "description": "Itens nesses lotes." } } }, "description": "Lotes e itens gerados, por tipo (`chats`, `messages`, `calls`, `labels`, `chat_labels`, `contacts`)." }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL do webhook; `(global)` para o webhook global e `(overflow)` para o que passar de 16 webhooks." }, "pending": { "type": "integer", "description": "Entregas em andamento." }, "delivered": { "type": "integer", "description": "Entregues." }, "failed": { "type": "integer", "description": "Falharam." }, "not_subscribed": { "type": "integer", "description": "O webhook não assina o evento." }, "queue_dropped": { "type": "integer", "description": "Descartadas com a fila cheia." }, "skipped": { "type": "integer", "description": "Puladas por outro motivo." }, "by_event": { "type": "object", "additionalProperties": { "type": "object", "properties": { "pending": { "type": "integer", "description": "Entregas em andamento." }, "delivered": { "type": "integer", "description": "Entregues." }, "failed": { "type": "integer", "description": "Falharam." }, "not_subscribed": { "type": "integer", "description": "O webhook não assina o evento." }, "queue_dropped": { "type": "integer", "description": "Descartadas com a fila cheia." }, "skipped": { "type": "integer", "description": "Puladas por outro motivo." } } }, "description": "As mesmas contagens por tipo de lote." }, "last_status_code": { "type": "integer", "description": "Código HTTP da última falha, quando há." }, "last_error": { "type": "string", "description": "Código da última falha (ex.: `timeout`, `http_error`, `not_subscribed`), quando há." } } }, "description": "Entrega por webhook: a URL, as contagens (entregues, falhas, pendentes, não inscritos) e o último erro.", "maxItems": 18 }, "events": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "description": "Quando aconteceu. ISO 8601 em UTC." }, "stage": { "type": "string", "description": "Etapa: `pair`, `chunk`, `sync`, `emitted` ou `delivery`." }, "status": { "type": "string", "description": "Resultado da etapa." }, "detail": { "type": "string", "description": "Detalhe da etapa, quando há." } } }, "description": "Linha do tempo das etapas (as 100 mais recentes)." } } }, "examples": { "sem_rastreamento": { "value": { "paired_at": null, "diagnosis": [ "no_trace" ] } } } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "unauthorized", "message": "Token inválido." } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "$ref": "#/components/responses/CloudUnsupported" } } ``` **Estado:** Disponível ## Compatibilidade de canais | Canal | Compatível | Observação | |---|---|---| | WhatsApp (Web) | Sim | | | WhatsApp (API oficial) | Não | Só no WhatsApp Web. | | Instagram | Não | | | Messenger | Não | | | Telegram | Não | | ## Eventos que esta rota gera Nenhum. Esta rota não gera evento no webhook (nem em `GET /events`): o resultado vem só na resposta. ## Antes e depois (uazapi → Orkesio) Na uazapi: `GET /instance/history-sync/status`. - `/inbox/history-sync`; campos em snake_case (`deliveryStatus` → `delivery_status`, `pairedAt` → `paired_at`...). ## #/components/schemas/OrkesioError ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP." }, "message": { "type": "string", "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`." }, "field": { "type": "string", "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)." } }, "required": [ "error", "message" ], "additionalProperties": true, "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)." } ``` ## #/components/responses/RateLimited ```json { "description": "`rate_limited`: passou do limite de chamadas desta inbox (ou do admin); espere o tempo do header `Retry-After` e tente de novo.", "headers": { "Retry-After": { "description": "Segundos até poder chamar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "rate_limited", "message": "Muitas requisições." } } } } ``` ## #/components/responses/InternalError ```json { "description": "`internal_error`: falha inesperada na api (no banco, por exemplo); tente de novo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "internal_error", "message": "Falha inesperada." } } } } ``` ## #/components/responses/CloudUnsupported ```json { "description": "`unsupported_for_channel`: o canal da inbox não atende esta rota (rota só do WhatsApp Web numa inbox oficial, ou rota da API oficial numa inbox do WhatsApp Web). O canal está em `Inbox.channel`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "unsupported_for_channel", "message": "Esta rota não está disponível no canal da inbox." } } } } ``` ## Guias relacionados [Visão geral](/docs/overview) · [O que funciona em cada canal](/docs/canais) · [O que muda da uazapi](/docs/o-que-muda)