> ## 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 contatos

> Solicita o envio da lista de contatos do aplicativo do WhatsApp Business. Os dados chegam pelo webhook `smb_app_state_sync`.

Quando um número é conectado por [coexistência](https://developers.datafyapi.com.br/guias/meta/conexao/coexistencia.md), a agenda de contatos continua apenas no aplicativo do WhatsApp Business, no celular. Esta chamada pede à Meta que envie esses contatos para a sua aplicação.

A resposta apenas confirma o aceite do pedido. **Os dados não vêm nela**: chegam depois, pelo webhook [Contatos sincronizados](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/contatos-sincronizados.md), com a agenda na lista `state_sync`.

```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 os contatos é desconectar o número e refazer a conexão.

## Antes de chamar

O evento `smb_app_state_sync` 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 `smb_app_state_sync` 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": "smb_app_state_sync" }'
```

Os contatos podem ser solicitados **uma única vez**. Repetir a chamada não gera um novo envio.

## O que chega

Cada contato chega com nome completo, primeiro nome e número. Na carga inicial todos vêm com a ação `add`. Depois dela, o mesmo evento continua ativo no dia a dia, informando inclusões, edições e remoções feitas no celular. O formato está detalhado em [Contatos sincronizados](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/contatos-sincronizados.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.

As conversas anteriores são solicitadas separadamente, em [Sincronizar histórico](https://developers.datafyapi.com.br/api-reference/whatsapp/sincronizacao/sincronizar-historico.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-contatos.json POST /v1/{phone_number_id}/smb_app_data
openapi: 3.1.0
info:
  title: Datafy API — Sincronizar contatos
  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 contatos
      description: >-
        Solicita o envio da lista de contatos do aplicativo do WhatsApp
        Business. Os dados chegam pelo webhook `smb_app_state_sync`.
      operationId: sincronizarContatos
      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:
                    - smb_app_state_sync
                  default: smb_app_state_sync
                  example: smb_app_state_sync
                  description: Sempre `smb_app_state_sync`.
            example:
              messaging_product: whatsapp
              sync_type: smb_app_state_sync
      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.