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

# Contatos sincronizados

> Evento smb_app_state_sync: a agenda de contatos do celular.

O evento **`smb_app_state_sync`** entrega os contatos da agenda do aplicativo do WhatsApp Business. Ele é usado em dois momentos:

* Na carga inicial, após a sincronização ser solicitada em [Sincronizar contatos](https://developers.datafyapi.com.br/api-reference/whatsapp/sincronizacao/sincronizar-contatos.md).
* No dia a dia, sempre que um contato é adicionado, editado ou removido no celular.

```json theme={null}
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1234567890123456",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5511988887777",
              "phone_number_id": "1234567890123456"
            },
            "state_sync": [
              {
                "type": "contact",
                "contact": {
                  "full_name": "Maria Souza",
                  "first_name": "Maria",
                  "phone_number": "5511999999999"
                },
                "action": "add",
                "metadata": { "timestamp": "1739321024" }
              }
            ]
          },
          "field": "smb_app_state_sync"
        }
      ]
    }
  ]
}
```

## Campos

| Campo | Descrição |
| - | - |
| `state_sync[]` | Lista de alterações. Uma entrega pode conter vários contatos |
| `type` | Sempre `contact` |
| `action` | `add` para contato adicionado ou editado; `remove` para contato excluído |
| `contact.full_name` | Nome completo como está salvo na agenda |
| `contact.first_name` | Primeiro nome |
| `contact.phone_number` | Número do contato |
| `metadata.timestamp` | Unix timestamp da alteração |

> [!NOTE]
>
> A edição de um contato chega como `add`, com os dados já atualizados. Trate o `add` como inclusão ou atualização, usando o `phone_number` como identificador.

> [!WARNING]
>
> Na ação `remove`, o objeto `contact` traz apenas o `phone_number`: os campos `full_name` e `first_name` não são enviados. Identifique o contato pelo número.

## Carga inicial

Na sincronização inicial, todos os contatos chegam com a ação `add`, na lista `state_sync`. Diferente do [histórico de conversas](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/historico.md), não há divisão em blocos nem campo de progresso: a agenda vem junta, em uma única entrega.

> [!NOTE]
>
> Contato na agenda não significa conversa iniciada. Enviar mensagem para esses números continua sujeito à [janela de 24 horas](https://developers.datafyapi.com.br/guias/whatsapp/conceitos/janela-de-24-horas.md), o que exige um [template aprovado](https://developers.datafyapi.com.br/api-reference/whatsapp/templates/enviar-template.md) quando não há conversa aberta.

## Se a entrega falhar

As entregas de `smb_app_state_sync` que falham são reenviadas automaticamente, com intervalos crescentes: `10s`, `1min`, `5min` e `30min`. Enquanto a sua URL responder `200`, a entrega é concluída normalmente.

Como a carga inicial é uma sincronização única, se a URL ficar indisponível além dessa janela a forma garantida de recuperar a agenda é desconectar o número e [refazer a conexão](https://developers.datafyapi.com.br/guias/meta/conexao/coexistencia.md), solicitando a sincronização de novo.

A referência completa está na [documentação do webhook smb\_app\_state\_sync da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/smb_app_state_sync).


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