# Mobile - Sincronizar agenda

`POST /contacts/sync`

Pasta: **Contatos**

## Autenticação

```http
token: {{token}}
```

## Descrição

# Mobile - Sincronizar agenda

Envia uma lista de números/nomes para a agenda da conta no modo **mobile (dispositivo primário)**. Use após conectar a instância mobile, por exemplo antes de depender de status para contatos.

## Endpoint

`POST {{baseUrl}}/contacts/sync`

## Autenticação

Envie o token da instância no header `token: {{token}}`.

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `contacts` | array | Sim | Lista de contatos a sincronizar (não pode ser vazia). |
| `contacts[].phone` | string | Sim | Telefone com DDI (com ou sem `+`). |
| `contacts[].name` | string | Não | Nome na agenda; se vazio, a API usa o próprio número. |

## Exemplo de Requisição

```bash
curl --request POST '{{baseUrl}}/contacts/sync' \
  --header 'token: {{token}}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "contacts": [
    { "phone": "5511999999999", "name": "Cliente A" },
    { "phone": "5511888888888", "name": "Cliente B" }
  ]
}'
```

## Resposta de Sucesso

```json
{
  "success": true,
  "result": {
    "uploaded": 2,
    "items": [
      {
        "phone": "5511999999999",
        "name": "Cliente A",
        "jid": "5511999999999@s.whatsapp.net",
        "lid": "123456789012345@lid",
        "on_whatsapp": true,
        "synced": true
      }
    ]
  }
}
```

## Erros comuns

- `400 Bad Request`: `contacts` ausente ou vazio.
- `500 Internal Server Error` com mensagem `contacts sync upload is for mobile (primary) connection mode`: a instância não está em modo mobile.
- `401 Unauthorized`: token inválido.
- `500 Internal Server Error`: bridge mobile indisponível ou sessão desconectada.

## Observações

- **Somente `connection_mode: mobile`**. Em modo web/companion a rota falha.
- Números fora do WhatsApp retornam `on_whatsapp: false`.

## Corpo (exemplo)

```json
{
  "contacts": [
    { "phone": "5511999999999", "name": "Cliente A" },
    { "phone": "5511888888888", "name": "Cliente B" }
  ]
}
```

## cURL

```bash
curl -X POST "{{baseUrl}}/contacts/sync" \
  -H "token: {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
  "contacts": [
    { "phone": "5511999999999", "name": "Cliente A" },
    { "phone": "5511888888888", "name": "Cliente B" }
  ]
}'
```

---

[Índice da pasta](./index.md) · [Índice geral](../index.md) · [UI](https://gozap.dev/docs?op=contatos/mobile-sincronizar-agenda)