> ## Documentation Index > Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt > Use this file to discover all available pages before exploring further. # Solicitar histórico sob demanda de um chat > Solicita ao WhatsApp um sync sob demanda de mensagens antigas de um chat, para trás a partir de uma mensagem de referência (âncora). Para recuperar uma mensagem salva que não abriu (`messageType: "error"` no `/message/find`), use `POST /message/reload`. Regras: - envie `number` - `count` é opcional e limitado a 100 - `messageid` é opcional; quando informado, a API usa essa mensagem como referência para buscar mensagens mais antigas do chat Observação: - **Importante:** a recuperação pode só acontecer depois de abrir o WhatsApp no celular ou deixá-lo ativo em segundo plano - `messageid` define a mensagem de referência para carregar histórico anterior; esse campo não serve para buscar essa mensagem específica - se você quiser recuperar apenas uma mensagem específica `X` via histórico, informe como `messageid` a mensagem logo depois de `X` e use `count=1` - se `messageid` não for informado, a API usa a mensagem mais antiga conhecida localmente desse chat como referência para buscar histórico anterior - as mensagens retornam depois via webhook/SSE em eventos do tipo `history` e também ficam disponíveis em `/message/find` ## Resultado A resposta traz o `request_id` do pedido. As mensagens chegam no webhook/SSE `history` com `event: "messages"` e o `request_id` em cada mensagem. Ele também vem no topo dos lotes `messages` e `chats` quando todo o lote pertence ao mesmo pedido; lotes mistos podem omiti-lo no topo. O pedido termina com um único lote `event: "status"` com o mesmo `request_id`: - `status`: `completed` quando o WhatsApp confirma a conclusão do pedido, `timeout` quando não houve resposta conclusiva em 2 minutos, `blocked` quando o celular indica mais mensagens, mas não entregou uma página que avance - `success` e `error`: só quando não há próxima página possível; `success: false` e o motivo em `error` (`pagination_no_progress`, `anchor_unavailable`, `history_access_unavailable` ou `cursor_lookup_failed`). Sempre vêm com `blocked` - `has_more`: o que o celular declarou. `true` há mais mensagens no celular, `false` chegou ao início da conversa, `null` não foi confirmado. Alguns aparelhos declaram `true` em toda resposta sob demanda, inclusive na vazia: com eles, a paginação termina em `blocked` com `pagination_no_progress`, nunca em `has_more: false` - `history_access`: `unavailable` quando há mais mensagens, mas o WhatsApp não dá acesso a elas - `next_request`: corpo pronto para pedir as mensagens anteriores; reenvie como veio. `null` quando não há uma próxima requisição utilizável Para paginar, reenvie `next_request` do resultado final até ele vir `null`, aguardando o resultado de cada pedido. `completed` encerra o pedido, não toda a conversa. `next_request: null` sem `has_more: false` não comprova o início da conversa. Silêncio ou um lote com menos mensagens que `count` não indicam o fim do histórico: só `has_more: false` indica. Com `blocked` e `error: "pagination_no_progress"`, encerre a paginação desse chat sem repetir o pedido automaticamente: é o fim do que o celular entrega a partir daquela âncora, e repetir dá o mesmo resultado. Cada chat tem um pedido ativo por vez. Repetir o pedido com a mesma mensagem de referência antes do `status` devolve o mesmo `request_id` (`details.reused: true`), sem novo envio ao celular. Um pedido com outra referência encerra o anterior, que recebe o próprio `status` final (em geral `timeout`), e segue normalmente. `409` só ocorre quando o `requestId` informado já está em uso. O resultado final chega por webhook/SSE em até 2 minutos após enviar o pedido ao WhatsApp (`details.result_timeout_ms`). Mensagens atrasadas podem continuar chegando com o mesmo `request_id` por cerca de 5 minutos após o pedido, sem um segundo status final. ## Modo síncrono (`sync: true`) `sync: true` segura a resposta até o resultado, por até `timeoutMs` (padrão e máximo 25000). As mensagens vêm em `messages`, e o topo da resposta traz os mesmos campos do `status` final (`status`, `has_more`, `history_access`, `received_messages`, `next_request`), além de `received`, `timed_out` e `partial`: - resultado final dentro do prazo: `200` com esse resultado; - chegaram mensagens, mas não o resultado: `200` com `status: "pending"`, cerca de 2 segundos depois da última mensagem; - nada chegou no prazo: `202` com `status: "pending"`, `timed_out: true` e `messages` vazio. Com `status: "pending"`, o resultado final chega depois pelo webhook/SSE `history`, com o mesmo `request_id`. O webhook e o SSE são enviados também no modo síncrono, e as mensagens são salvas do mesmo jeito. ## Mensagem de referência apagada Se a âncora foi apagada, a API tenta usar a próxima mensagem válida desse chat. `details.requested_anchor_messageid` informa a referência solicitada, `details.anchor_messageid` a usada e `details.anchor_replaced` indica a substituição. Sem alternativa, retorna HTTP `400` com `status: "anchor_unavailable"`; tente sem `messageid` para usar a mensagem mais antiga salva. ## OpenAPI ````yaml /openapi-pt-BR.json post /message/history-sync openapi: 3.1.0 info: title: WppFy - WhatsApp API version: 1.0.0 description: > API para gerenciamento de instâncias do WhatsApp e comunicações. ## Recomendação Importante: WhatsApp Business **É ALTAMENTE RECOMENDADO usar contas do WhatsApp Business** em vez do WhatsApp normal para integração, o WhatsApp normal pode apresentar inconsistências, desconexões, limitações e instabilidades durante o uso com a nossa API. ## Autenticação - Endpoints regulares requerem um header 'token' com o token da instância ## Estados da Instância As instâncias podem estar nos seguintes estados: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de conexão - `connected`: Conectado e autenticado com sucesso servers: - url: https://api.wppfy.com security: - token: [] tags: - name: Instancia description: | Operações relacionadas ao ciclo de vida de uma instância, como conectar, desconectar e verificar o status. - name: Proxy description: > A WppFy opera com um proxy interno como padrão. Você pode manter esse padrão, configurar um proxy próprio via `proxy_url` ou usar seu celular android como proxy instalando o app em https://github.com/WppFy/silver_proxy_apk (APK direto: https://github.com/WppFy/silver_proxy_apk/raw/refs/heads/main/silver_proxy.apk). Se nada for enviado, seguimos no proxy interno. IPs são brasileiros; para clientes internacionais, considere um proxy da região do cliente. - name: Perfil description: | Operações relacionadas ao perfil da instância do WhatsApp, como alterar nome e imagem de perfil. - name: Business description: | ⚠️ **EXPERIMENTAL** - Endpoints ainda não testados completamente. Operações relacionadas ao perfil comercial do WhatsApp Business. Permite consultar e atualizar dados do perfil comercial como descrição, endereço, email, categorias e gerenciar o catálogo de produtos. **Requisitos:** - A conta atualmente conectada deve ser uma conta **WhatsApp Business** - Contas pessoais do WhatsApp não possuem perfil comercial **Nota:** Estes endpoints podem não funcionar como esperado. Reporte problemas encontrados. - name: Chamadas description: | Operações relacionadas a chamadas peloWhatsApp. Permite realizar e rejeitar chamadas programaticamente. - name: Enviar Mensagem description: > Endpoints para envio de mensagens do WhatsApp com diferentes tipos de conteúdo. ## Campos Opcionais Comuns Todos os endpoints de envio de mensagem suportam os seguintes campos opcionais: - **`delay`** *(integer)*: Atraso em milissegundos antes do envio - Durante o atraso aparecerá "Digitando..." ou "Gravando áudio..." dependendo do tipo - Exemplo: `5000` (5 segundos) - **`readchat`** *(boolean)*: Marcar chat como lido após envio - Remove o contador de mensagens não lidas do chat - Exemplo: `true` - **`readmessages`** *(boolean)*: Marcar últimas mensagens recebidas como lidas - Marca as últimas 10 mensagens **recebidas** (não enviadas por você) como lidas - Útil para confirmar leitura de mensagens pendentes antes de responder - Diferente do `readchat` que apenas remove contador de não lidas - Exemplo: `true` - **`replyid`** *(string)*: ID da mensagem para responder - Cria uma resposta vinculada à mensagem original - Suporte varia por tipo de mensagem - Exemplo: `"3A12345678901234567890123456789012"` - **`mentions`** *(string)*: Números para mencionar (apenas para envio em grupos) - Números específicos: `"5511999999999,5511888888888"` - Mencionar todos: `"all"` - **`forward`** *(boolean)*: Marca a mensagem como encaminhada no WhatsApp - Adiciona o indicador "Encaminhada" na mensagem - Exemplo: `true` - **`track_source`** *(string)*: Origem do rastreamento da mensagem - Identifica o sistema ou fonte que está enviando a mensagem - Útil para integrações (ex: "chatwoot", "crm", "chatbot") - Exemplo: `"chatwoot"` - **`track_id`** *(string)*: ID para rastreamento da mensagem - Identificador livre para acompanhar a mensagem em sistemas externos - Permite correlacionar mensagens entre diferentes plataformas - **Nota**: O sistema aceita valores duplicados - não há validação de unicidade - Use o mesmo ID em várias mensagens se fizer sentido para sua integração - Exemplo: `"msg_123456789"` ### Envio para Grupos - **`number`** *(string)*: Para enviar mensagem para grupo, use o ID do grupo que termina com `@g.us` - Exemplo: `"120363012345678901@g.us"` - **Como obter o ID do grupo:** - Use o `chatid` do webhook recebido quando alguém envia mensagem no grupo - Use o endpoint `GET /group/list` para listar todos os grupos e seus IDs ## Placeholders Disponíveis Todos os endpoints de envio de mensagem suportam placeholders dinâmicos para personalização automática: ### Campos de Nome - **`{{name}}`**: Nome consolidado do chat, usando a primeira opção disponível: 1. Nome do lead (`lead_name`) 2. Nome completo do lead (`lead_fullName`) 3. Nome do contato no WhatsApp (`wa_contactName`) 4. Nome do perfil do WhatsApp (`wa_name`) - **`{{first_name}}`**: Primeira palavra válida do nome consolidado (mínimo 2 caracteres) ### Campos do WhatsApp - **`{{wa_name}}`**: Nome do perfil do WhatsApp - **`{{wa_contactName}}`**: Nome do contato como salvo no WhatsApp ### Campos do Lead - **`{{lead_name}}`**: Nome do lead - **`{{lead_fullName}}`**: Nome completo do lead - **`{{lead_personalid}}`**: ID pessoal (CPF, CNPJ, etc) - **`{{lead_email}}`**: Email do lead - **`{{lead_status}}`**: Status atual do lead - **`{{lead_notes}}`**: Anotações do lead - **`{{lead_assignedAttendant_id}}`**: ID do atendente designado ### Campos Personalizados Campos adicionados via custom fields são acessíveis usando `{{lead_field01}}` à `{{lead_field20}}` ou usar `{{nomedocampo}}` definido em `/instance/updateFieldsMap`. ### Exemplo de Uso ``` Olá {{name}}! Vi que você trabalha na {{company}}. Seu email {{lead_email}} está correto? ``` **💡 Dica**: Use `/chat/find` para buscar dados do chat e ver os campos disponíveis antes de enviar mensagens com placeholders. - name: Mensagem Async description: > Controles operacionais da fila interna de envio assíncrono usada quando um endpoint de envio recebe `async=true`. Esta seção serve para: - consultar o estado atual da fila async - configurar o delay entre mensagens enviadas com `async=true` - limpar backlog pendente e cancelar mensagens ainda não concluídas Escopo: - cobre apenas a fila interna de mensagens diretas async - não altera mensagens já enviadas com sucesso - name: Ações na mensagem e Buscar - name: Chats - name: Contatos - name: Bloqueios - name: Etiquetas - name: Grupos e Comunidades - name: Newsletters e Canais description: > Operações para leitura e acompanhamento de canais do WhatsApp (newsletters). Casos de uso principais: - listar posts já publicados em um canal - editar posts recentes de um canal - deletar posts recentes de um canal - consultar views e reações dos posts - integrar canais sem necessidade de persistir as mensagens localmente Observações: - `/newsletter/messages` retorna o conteúdo dos posts - `/newsletter/messages/edit` edita o conteúdo de posts recentes - `/newsletter/messages/delete` apaga posts recentes - views (`viewsCount`) e reactions (`reactionCounts`) vêm em cada post de `/newsletter/messages`, não por evento de webhook - `/newsletter/updates` está obsoleta: o WhatsApp não responde e a API devolve 504 - newsletters usam rotas próprias e não devem usar `/message/edit` ou `/message/delete` - name: Respostas Rápidas description: > Gerenciamento de respostas rápidas para agilizar o atendimento. **⚠️ Importante**: Este recurso tem serventia apenas se você utilizar um sistema frontend/interface personalizada para registrar e utilizar as respostas. A API apenas armazena as respostas, mas não as aplica automaticamente. ### Como funciona: - **Criar**: Cadastre respostas pré-definidas com títulos e conteúdo - **Listar**: Recupere todas as respostas cadastradas para exibir na sua interface - **Usar**: Seu sistema frontend pode usar essas respostas para agilizar digitação ### Casos de uso: - Interfaces web personalizadas de atendimento - Apps mobile com sugestões de resposta - Sistemas CRM com templates de mensagem - Ferramentas de produtividade para atendentes **Não é um chatbot**: Para respostas automáticas, use os recursos de Chatbot. - name: CRM description: > Sistema completo de gestão de relacionamento com clientes integrado à API. **💾 Armazenamento interno**: Todos os dados dos leads ficam salvos diretamente na API, eliminando a necessidade de bancos de dados externos. Sua aplicação pode focar apenas na interface e lógica de negócio. ### Recursos disponíveis: - **📋 20+ campos personalizáveis**: Nome, telefone, email, empresa, observações, etc. - **🏷️ Sistema de etiquetas**: Organize e categorize seus contatos - **🔍 Busca avançada**: Filtre por qualquer campo ou etiqueta - **📊 Histórico completo**: Todas as interações ficam registradas automaticamente ### 🎯 Placeholders em mensagens: Use variáveis dinâmicas nas mensagens para personalização automática: ``` Olá {{nome}}! Vi que você trabalha na {{empresa}}. Seu email {{email}} está correto? Observações: {{observacoes}} ``` ### Fluxo típico: 1. **Captura**: Leads chegam via WhatsApp ou formulários 2. **Enriquecimento**: Adicione dados usando `/chat/editLead` 3. **Segmentação**: Organize com etiquetas 4. **Comunicação**: Envie mensagens personalizadas com placeholders 5. **Acompanhamento**: Histórico fica salvo automaticamente **Ideal para**: Vendas, marketing, atendimento, qualificação de leads - name: Integração Chatwoot description: > **🚧 INTEGRAÇÃO BETA - Sistema de integração com Chatwoot para atendimento unificado** **⚠️ AVISO**: Esta integração está em fase BETA. Use por sua conta e risco. Recomendamos testes em ambiente não-produtivo antes do uso em produção. Esta categoria contém recursos para configurar e gerenciar a integração com o Chatwoot, uma plataforma de atendimento ao cliente open-source. A integração permite centralizar conversas do WhatsApp no Chatwoot. ### Recursos disponíveis: - 🔧 **Configuração Completa**: Configure URL, tokens e credenciais do Chatwoot - 📬 **Sincronização Bidirecional**: Mensagens novas entre WhatsApp e Chatwoot são sincronizadas automaticamente - 📱 **Gerenciamento de Contatos**: Sincronização automática de nomes e telefones - 🔄 **Atualização LID→PN**: Migração automática de Local ID para Phone Number - 🏷️ **Nomes Inteligentes**: Sistema de nomes com til (~) para atualização automática - 🚫 **Separação de Grupos**: Opção para ignorar grupos na sincronização - 👤 **Assinatura de Mensagens**: Identificação do agente nas mensagens enviadas - 🔗 **Webhook Automático**: URL gerada automaticamente para configurar no Chatwoot ### 🏷️ Sistema de Nomes Inteligentes: - **Nomes com til (~)**: Atualizados automaticamente quando contato modifica nome no WhatsApp - **Nomes específicos**: Para nome fixo, remover til (~) do nome no Chatwoot - **Exemplo**: "~João Silva" = automático, "João Silva" = fixo - **Migração LID→PN**: Sem duplicação de conversas durante a transição - **Respostas nativas**: Aparecem diretamente no Chatwoot sem marcações externas ### ⚠️ Limitações conhecidas: - **Sincronização de histórico**: Não implementada - apenas mensagens novas são sincronizadas ### Casos de uso: - Atendimento centralizado no Chatwoot - Equipes de suporte com múltiplos agentes - Integração com CRM via Chatwoot - Centralização de canais de comunicação - Gestão automática de contatos e nomes **Ideal para**: Empresas com equipes de atendimento, call centers, suporte técnico (em ambiente de testes) **Requer**: Instância do Chatwoot configurada, tokens de API e ambiente de testes **🚧 Lembre-se**: Integração em BETA - funcionalidades podem mudar sem aviso prévio - name: Server-Sent Events (SSE) paths: /message/history-sync: post: tags: - Ações na mensagem e Buscar summary: Solicitar histórico sob demanda de um chat description: > Solicita ao WhatsApp um sync sob demanda de mensagens antigas de um chat, para trás a partir de uma mensagem de referência (âncora). Para recuperar uma mensagem salva que não abriu (`messageType: "error"` no `/message/find`), use `POST /message/reload`. Regras: - envie `number` - `count` é opcional e limitado a 100 - `messageid` é opcional; quando informado, a API usa essa mensagem como referência para buscar mensagens mais antigas do chat Observação: - **Importante:** a recuperação pode só acontecer depois de abrir o WhatsApp no celular ou deixá-lo ativo em segundo plano - `messageid` define a mensagem de referência para carregar histórico anterior; esse campo não serve para buscar essa mensagem específica - se você quiser recuperar apenas uma mensagem específica `X` via histórico, informe como `messageid` a mensagem logo depois de `X` e use `count=1` - se `messageid` não for informado, a API usa a mensagem mais antiga conhecida localmente desse chat como referência para buscar histórico anterior - as mensagens retornam depois via webhook/SSE em eventos do tipo `history` e também ficam disponíveis em `/message/find` ## Resultado A resposta traz o `request_id` do pedido. As mensagens chegam no webhook/SSE `history` com `event: "messages"` e o `request_id` em cada mensagem. Ele também vem no topo dos lotes `messages` e `chats` quando todo o lote pertence ao mesmo pedido; lotes mistos podem omiti-lo no topo. O pedido termina com um único lote `event: "status"` com o mesmo `request_id`: - `status`: `completed` quando o WhatsApp confirma a conclusão do pedido, `timeout` quando não houve resposta conclusiva em 2 minutos, `blocked` quando o celular indica mais mensagens, mas não entregou uma página que avance - `success` e `error`: só quando não há próxima página possível; `success: false` e o motivo em `error` (`pagination_no_progress`, `anchor_unavailable`, `history_access_unavailable` ou `cursor_lookup_failed`). Sempre vêm com `blocked` - `has_more`: o que o celular declarou. `true` há mais mensagens no celular, `false` chegou ao início da conversa, `null` não foi confirmado. Alguns aparelhos declaram `true` em toda resposta sob demanda, inclusive na vazia: com eles, a paginação termina em `blocked` com `pagination_no_progress`, nunca em `has_more: false` - `history_access`: `unavailable` quando há mais mensagens, mas o WhatsApp não dá acesso a elas - `next_request`: corpo pronto para pedir as mensagens anteriores; reenvie como veio. `null` quando não há uma próxima requisição utilizável Para paginar, reenvie `next_request` do resultado final até ele vir `null`, aguardando o resultado de cada pedido. `completed` encerra o pedido, não toda a conversa. `next_request: null` sem `has_more: false` não comprova o início da conversa. Silêncio ou um lote com menos mensagens que `count` não indicam o fim do histórico: só `has_more: false` indica. Com `blocked` e `error: "pagination_no_progress"`, encerre a paginação desse chat sem repetir o pedido automaticamente: é o fim do que o celular entrega a partir daquela âncora, e repetir dá o mesmo resultado. Cada chat tem um pedido ativo por vez. Repetir o pedido com a mesma mensagem de referência antes do `status` devolve o mesmo `request_id` (`details.reused: true`), sem novo envio ao celular. Um pedido com outra referência encerra o anterior, que recebe o próprio `status` final (em geral `timeout`), e segue normalmente. `409` só ocorre quando o `requestId` informado já está em uso. O resultado final chega por webhook/SSE em até 2 minutos após enviar o pedido ao WhatsApp (`details.result_timeout_ms`). Mensagens atrasadas podem continuar chegando com o mesmo `request_id` por cerca de 5 minutos após o pedido, sem um segundo status final. ## Modo síncrono (`sync: true`) `sync: true` segura a resposta até o resultado, por até `timeoutMs` (padrão e máximo 25000). As mensagens vêm em `messages`, e o topo da resposta traz os mesmos campos do `status` final (`status`, `has_more`, `history_access`, `received_messages`, `next_request`), além de `received`, `timed_out` e `partial`: - resultado final dentro do prazo: `200` com esse resultado; - chegaram mensagens, mas não o resultado: `200` com `status: "pending"`, cerca de 2 segundos depois da última mensagem; - nada chegou no prazo: `202` com `status: "pending"`, `timed_out: true` e `messages` vazio. Com `status: "pending"`, o resultado final chega depois pelo webhook/SSE `history`, com o mesmo `request_id`. O webhook e o SSE são enviados também no modo síncrono, e as mensagens são salvas do mesmo jeito. ## Mensagem de referência apagada Se a âncora foi apagada, a API tenta usar a próxima mensagem válida desse chat. `details.requested_anchor_messageid` informa a referência solicitada, `details.anchor_messageid` a usada e `details.anchor_replaced` indica a substituição. Sem alternativa, retorna HTTP `400` com `status: "anchor_unavailable"`; tente sem `messageid` para usar a mensagem mais antiga salva. requestBody: required: true content: application/json: schema: type: object required: - number properties: messageid: type: string description: >- ID da mensagem de referência usada para buscar mensagens mais antigas do chat. example: 3EB01234567890ABCDEF number: type: string description: JID completo do chat. example: 5511999999999@s.whatsapp.net count: type: integer minimum: 1 maximum: 100 description: Quantidade desejada de mensagens no sync. example: 20 default: 50 timestamp: type: integer description: >- Timestamp da mensagem de referência, em milissegundos ou segundos. Opcional; vem no `next_request` para a referência funcionar mesmo antes de a mensagem estar salva. example: 1706350400000 fromMe: type: boolean description: >- Indica se a mensagem de referência foi enviada pela conta conectada. Opcional; vem no `next_request`. example: false requestId: type: string description: >- Identificador opcional escolhido pelo cliente; quando omitido, a API gera um UUID. Retorna como request_id. Use um id novo por pedido: um id já em uso recebe `409`. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f fallbackMode: type: string enum: - try_alternates - exact default: try_alternates description: >- Para onde o pedido é enviado. `try_alternates` (padrão): em conversa individual, envia pelo número e pelo LID do chat, porque o celular guarda cada conversa por um dos dois endereços e ignora o pedido enviado pelo outro; a resposta chega uma vez só. `exact`: envia só pelo endereço preferido do chat (o LID, quando conhecido). Em grupos, o pedido vai sempre só para o grupo. sync: type: boolean default: false description: >- Segura a resposta até o resultado do pedido, por até `timeoutMs`. Veja "Modo síncrono". timeoutMs: type: integer default: 25000 maximum: 25000 description: >- Só com `sync: true`: espera máxima em milissegundos. Valores maiores viram 25000. examples: usando_ancora_explicita: summary: Buscar histórico anterior a uma mensagem de referência value: number: 5511999999999@s.whatsapp.net messageid: 3EB01234567890ABCDEF count: 20 recuperar_mensagem_especifica: summary: >- Recuperar apenas a mensagem imediatamente anterior à referência value: number: 5511999999999@s.whatsapp.net messageid: 3EB0MENSAGEM_LOGO_APOS_X count: 1 usando_ancora_local: summary: Reutilizar âncora local já persistida value: number: 5511999999999@s.whatsapp.net count: 50 proxima_pagina: summary: Pedir as mensagens anteriores com o next_request recebido value: number: 5511999999999@s.whatsapp.net count: 50 messageid: 3EB0MAIS_ANTIGA_RECEBIDA timestamp: 1706350400000 fromMe: false modo_sincrono: summary: Esperar o resultado na resposta (modo síncrono) value: number: 5511999999999@s.whatsapp.net count: 50 sync: true timeoutMs: 20000 responses: '200': description: >- Solicitação enviada com sucesso. As mensagens e o resultado chegam depois por webhook/SSE. Com `sync: true`, traz também as mensagens e o resultado do pedido. content: application/json: schema: type: object properties: success: type: boolean example: true request_id: type: string description: >- Identifica o pedido. Aparece nas mensagens correlacionadas e no status final do webhook/SSE history. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f message: type: string example: >- History sync request sent. Messages will be received as history sync events. details: type: object additionalProperties: true description: Metadados adicionais da operação properties: result_timeout_ms: type: integer example: 120000 description: Prazo para o resultado final por webhook/SSE. requested_anchor_messageid: type: string description: Referência originalmente solicitada. anchor_messageid: type: string description: Referência efetivamente usada. anchor_replaced: type: boolean description: >- A referência apagada foi substituída por uma mensagem válida posterior. reused: type: boolean description: >- O pedido repete a referência de um pedido em andamento: a API devolve o `request_id` dele e não envia outro pedido ao celular. fallback_mode: type: string enum: - try_alternates - exact description: Modo de envio usado (`fallbackMode`). attempted_chats: type: array items: type: string description: Endereços do chat para os quais o pedido foi enviado. sync: type: boolean description: >- `true` quando a resposta esperou o resultado (`sync: true`). status: type: string enum: - completed - timeout - pending - blocked description: >- Só no modo síncrono: resultado do pedido; `pending` quando ainda não chegou e virá pelo webhook/SSE; `blocked` quando o celular indica mais mensagens, mas não entregou uma página que avance (o motivo vem em `error`). request_chat: type: string description: 'Só no modo síncrono: chat do pedido.' has_more: type: - boolean - 'null' description: >- Só no modo síncrono: o que o celular declarou. `true` há mais mensagens, `false` início da conversa, `null` não confirmado. Alguns aparelhos declaram `true` em toda resposta sob demanda, inclusive na vazia: com eles, a paginação termina em `blocked` com `pagination_no_progress`, nunca em `has_more: false`. nullable: true history_access: type: string enum: - available - unavailable - unknown description: >- Só no modo síncrono: `unavailable` quando há mais mensagens sem acesso. received_messages: type: integer description: >- Só no modo síncrono: quantidade de mensagens em `messages`. next_request: type: - object - 'null' additionalProperties: true description: >- Só no modo síncrono: corpo pronto para pedir as mensagens anteriores, ou `null`. nullable: true received: type: boolean description: >- Só no modo síncrono: chegaram mensagens ou o pedido foi concluído. timed_out: type: boolean description: 'Só no modo síncrono: o prazo de `timeoutMs` acabou.' partial: type: boolean description: >- Só no modo síncrono: ainda pode haver mais mensagens (`has_more` diferente de `false`). messages: type: array items: type: object additionalProperties: true description: >- Só no modo síncrono: mensagens do pedido, no formato do evento `history`. error: type: string enum: - pagination_no_progress - anchor_unavailable - history_access_unavailable - cursor_lookup_failed description: >- Com `status: "blocked"` (e `success: false`): por que não há `next_request`. `pagination_no_progress`: a partir da mesma âncora, o celular não entregou uma página que avance nem no maior `count` (a cada página sem avanço, o `next_request` dobra o `count`, até 100): veio vazia, sem mensagem que sirva de âncora ou repetida. É o fim do que o celular entrega a partir dessa âncora, mas o WhatsApp não confirma que é o início da conversa; repetir o pedido dá o mesmo resultado; `anchor_unavailable`: a mensagem de referência não está mais disponível, peça com outra; `history_access_unavailable`: o restante não está acessível; `cursor_lookup_failed`: falha ao montar o próximo pedido, tente de novo. examples: async_padrão: summary: Solicitação de histórico enviada value: success: true request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f message: >- History sync request sent. Messages will be received as history sync events. details: result_timeout_ms: 120000 requested_anchor_messageid: 3EB01234567890ABCDEF anchor_messageid: 3EB01234567890ABCDEF anchor_replaced: false sync_concluido: summary: Modo síncrono com resultado value: success: true sync: true request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f request_chat: 5511999999999@s.whatsapp.net status: completed has_more: true history_access: available received_messages: 1 next_request: number: 5511999999999@s.whatsapp.net count: 50 messageid: 3EB0MAIS_ANTIGA_RECEBIDA timestamp: 1706350400000 fromMe: false received: true timed_out: false partial: true messages: - messageid: 3EB0MAIS_ANTIGA_RECEBIDA chatid: 5511999999999@s.whatsapp.net fromMe: false messageTimestamp: 1706350400000 text: Mensagem antiga request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f '202': description: >- Só com `sync: true`: nada chegou dentro de `timeoutMs`. O pedido segue e o resultado chega pelo webhook/SSE `history` com o mesmo `request_id`. content: application/json: schema: type: object properties: success: type: boolean example: true request_id: type: string description: >- Identifica o pedido. Aparece nas mensagens correlacionadas e no status final do webhook/SSE history. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f message: type: string example: >- History sync request sent. Messages will be received as history sync events. details: type: object additionalProperties: true description: Metadados adicionais da operação properties: result_timeout_ms: type: integer example: 120000 description: Prazo para o resultado final por webhook/SSE. requested_anchor_messageid: type: string description: Referência originalmente solicitada. anchor_messageid: type: string description: Referência efetivamente usada. anchor_replaced: type: boolean description: >- A referência apagada foi substituída por uma mensagem válida posterior. reused: type: boolean description: >- O pedido repete a referência de um pedido em andamento: a API devolve o `request_id` dele e não envia outro pedido ao celular. fallback_mode: type: string enum: - try_alternates - exact description: Modo de envio usado (`fallbackMode`). attempted_chats: type: array items: type: string description: Endereços do chat para os quais o pedido foi enviado. sync: type: boolean description: >- `true` quando a resposta esperou o resultado (`sync: true`). status: type: string enum: - completed - timeout - pending description: >- Só no modo síncrono: resultado do pedido; `pending` quando ainda não chegou e virá pelo webhook/SSE. request_chat: type: string description: 'Só no modo síncrono: chat do pedido.' has_more: type: - boolean - 'null' description: >- Só no modo síncrono: o que o celular declarou. `true` há mais mensagens, `false` início da conversa, `null` não confirmado. Alguns aparelhos declaram `true` em toda resposta sob demanda, inclusive na vazia: com eles, a paginação termina em `blocked` com `pagination_no_progress`, nunca em `has_more: false`. nullable: true history_access: type: string enum: - available - unavailable - unknown description: >- Só no modo síncrono: `unavailable` quando há mais mensagens sem acesso. received_messages: type: integer description: >- Só no modo síncrono: quantidade de mensagens em `messages`. next_request: type: - object - 'null' additionalProperties: true description: >- Só no modo síncrono: corpo pronto para pedir as mensagens anteriores, ou `null`. nullable: true received: type: boolean description: >- Só no modo síncrono: chegaram mensagens ou o pedido foi concluído. timed_out: type: boolean description: 'Só no modo síncrono: o prazo de `timeoutMs` acabou.' partial: type: boolean description: >- Só no modo síncrono: ainda pode haver mais mensagens (`has_more` diferente de `false`). messages: type: array items: type: object additionalProperties: true description: >- Só no modo síncrono: mensagens do pedido, no formato do evento `history`. examples: pendente: summary: Nada chegou no prazo value: success: true sync: true request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f request_chat: 5511999999999@s.whatsapp.net status: pending has_more: null history_access: unknown received_messages: 0 next_request: null received: false timed_out: true partial: true messages: [] message: >- History sync request sent. The final result arrives by webhook/SSE with this request_id. '400': description: >- Payload inválido, modo inválido ou âncora insuficiente. `anchor_unavailable`: a mensagem de referência foi apagada e não há outra utilizável depois dela; envie sem `messageid` para usar a mensagem mais antiga salva. content: application/json: schema: type: object properties: error: type: string example: number is required success: type: boolean status: type: string enum: - anchor_unavailable request_id: type: string request_chat: type: string requested_anchor_messageid: type: string has_more: type: - boolean - 'null' nullable: true next_request: type: - object - 'null' nullable: true examples: payload_invalido: summary: Payload inválido value: error: number is required anchor_unavailable: summary: Mensagem de referência indisponível value: success: false error: anchor_unavailable status: anchor_unavailable request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f has_more: null next_request: null request_chat: 5511999999999@s.whatsapp.net requested_anchor_messageid: 3EB0ANCORA_APAGADA '409': description: >- O `requestId` informado já está em uso por outro pedido. Use um id novo; para repetir o mesmo pedido, reenvie sem `requestId`. content: application/json: schema: type: object properties: error: type: string example: history sync request_id already in use request_id: type: string description: Pedido que já usa esse id. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f '429': description: Limite de pedidos de histórico pendentes na instância. content: application/json: schema: type: object properties: error: type: string example: too many pending history sync requests '500': description: Erro interno ao solicitar o history sync content: application/json: schema: type: object properties: error: type: string example: 'Failed to request history: connection closed' '503': description: A instância está parando; o pedido não foi registrado. content: application/json: schema: type: object properties: error: type: string example: instance is stopping components: securitySchemes: token: name: token type: apiKey in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.