> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datafyapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronizar histórico

> Solicita o envio do histórico de conversas do aplicativo do WhatsApp Business. Os dados chegam pelo webhook `history`.

Quando um número é conectado por [coexistência](https://developers.datafyapi.com.br/guias/meta/conexao/coexistencia.md), as conversas anteriores continuam apenas no aplicativo do WhatsApp Business, no celular. Esta chamada pede à Meta que envie esse histórico para a sua aplicação.

A resposta apenas confirma o aceite do pedido. **Os dados não vêm nela**: chegam depois, pelo webhook [Histórico de conversas](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/historico.md), divididos em várias entregas.

```json theme={null}
{
  "messaging_product": "whatsapp",
  "request_id": "7a3b2c1d-e5f6-4a8b-9c0d-1e2f3a4b5c6d",
  "success": true
}
```

> [!WARNING]
>
> A chamada precisa ser feita em até **24 horas** após a conexão do número. Passado esse prazo, o pedido não tem efeito, e a única forma de recuperar o histórico é desconectar o número e refazer a conexão.

## Antes de chamar

O evento `history` precisa estar marcado para a sua URL **antes** do disparo, senão os dados são enviados e não há para onde entregar. No [painel da Datafy](https://app.datafyapi.com.br), na aba **Webhooks** do número, marque `history` na URL que vai receber.

```bash theme={null}
curl -X POST 'https://cloud.datafyapi.com.br/v1/{phone_number_id}/smb_app_data' \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "messaging_product": "whatsapp", "sync_type": "history" }'
```

O histórico pode ser solicitado **uma única vez**. Repetir a chamada não gera um novo envio.

## O que chega

As conversas são entregues em **vários blocos** pelo webhook `history`, com até 180 dias de mensagens, acompanhados dos campos `phase`, `chunk_order` e `progress` para o progresso. Mensagens que continham mídia chegam apenas como marcador: o arquivo não é sincronizado.

Os blocos podem chegar **fora de ordem** e em grande volume — milhares de entregas em poucos minutos —, e uma entrega que falha é reenviada automaticamente. Por isso a sua aplicação deve responder `200` de imediato, tratar as entregas de forma idempotente pelo `x-datafy-delivery-id` e reordenar pelo `chunk_order` e pelo `timestamp` de cada mensagem.

O formato completo, o acompanhamento do progresso e o comportamento de reentrega estão em [Histórico de conversas](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/historico.md).

> [!NOTE]
>
> Guarde o `request_id` da resposta. Ele é o identificador do pedido junto à Meta, necessário caso seja preciso abrir um chamado por dados que não chegaram.

Os contatos da agenda são solicitados separadamente, em [Sincronizar contatos](https://developers.datafyapi.com.br/api-reference/whatsapp/sincronizacao/sincronizar-contatos.md).

O procedimento completo está na [documentação de onboarding da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users).


## OpenAPI

````yaml api-reference/whatsapp/specs/sincronizar-historico.json POST /v1/{phone_number_id}/smb_app_data
openapi: 3.1.0
info:
  title: Datafy API — Sincronizar histórico
  version: 1.0.0
servers:
  - url: https://cloud.datafyapi.com.br
    description: Produção
security:
  - bearerAuth: []
paths:
  /v1/{phone_number_id}/smb_app_data:
    post:
      summary: Sincronizar histórico
      description: >-
        Solicita o envio do histórico de conversas do aplicativo do WhatsApp
        Business. Os dados chegam pelo webhook `history`.
      operationId: sincronizarHistorico
      parameters:
        - name: phone_number_id
          in: path
          required: true
          schema:
            type: string
          description: ID do número conectado por coexistência. Descubra com `GET /me`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messaging_product
                - sync_type
              properties:
                messaging_product:
                  type: string
                  enum:
                    - whatsapp
                  default: whatsapp
                  example: whatsapp
                  description: Sempre `whatsapp`.
                sync_type:
                  type: string
                  enum:
                    - history
                  default: history
                  example: history
                  description: Sempre `history`.
            example:
              messaging_product: whatsapp
              sync_type: history
      responses:
        '200':
          description: Sincronização aceita. Os dados chegam pelos webhooks.
          content:
            application/json:
              example:
                messaging_product: whatsapp
                request_id: 7a3b2c1d-e5f6-4a8b-9c0d-1e2f3a4b5c6d
                success: true
        '400':
          description: Prazo de 24 horas expirado ou número sem coexistência.
          content:
            application/json:
              example:
                error:
                  message: Invalid parameter
                  type: OAuthException
                  code: 100
                  fbtrace_id: AbCdEfGhIjK
        '401':
          description: Token ausente ou inválido.
          content:
            application/json:
              example:
                statusCode: 401
                message: Token inválido ou não encontrado.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Token gerado no painel da Datafy ao criar o canal. Formato:
        `sk_live_xxx`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.