Atualizar contato

Pede ao WhatsApp o nome atual de um contato. Cada pedido faz uma consulta real ao WhatsApp e conta no limite de atualizações do seu plano, por isso exige o escopo de escrita, não o de leitura. A resposta 202 é imediata; a consulta termina em alguns segundos e o resultado aparece no próprio contato.

A atualização muda somente o nome. A foto de perfil não é atualizada por este endpoint: ela é reavaliada automaticamente na próxima troca de mensagens entre o número e o contato.

A consulta usa a conexão do número dono do contato (main ou o alias do número extra). Se esse número não estiver conectado, a atualização termina na hora com o resultado number_not_connected.

Endpoint

POST /v1/contacts/{contact_id}/refresh

Para números extras: POST /v1/numbers/{ref}/contacts/{contact_id}/refresh

Escopo obrigatório: contacts:write.

Limite de velocidade

Cada atualização consulta o WhatsApp na hora, por isso tem um limite por minuto que depende do plano:

Plano	Atualizações/min
Gratuito	5
Lobo Solitário	30
Empresarial	120
Personalizado	600

Ao passar do limite, a resposta é 429 refresh_rate_limited com o cabeçalho Retry-After.

Exemplo

cURL

curl -X POST "https://api.turbonotify.com/v1/contacts/ct_.../refresh" \
  -H "Authorization: Bearer SUA_CHAVE"

Node

const id = "ct_a1b2c3d4e5f6789012345678901234ab";

const res = await fetch(`https://api.turbonotify.com/v1/contacts/${id}/refresh`, {
  method: "POST",
  headers: { Authorization: "Bearer SUA_CHAVE" },
});
const { status, requested_at } = await res.json();

Python

import httpx

contact_id = "ct_a1b2c3d4e5f6789012345678901234ab"

r = httpx.post(
    f"https://api.turbonotify.com/v1/contacts/{contact_id}/refresh",
    headers={"Authorization": "Bearer SUA_CHAVE"},
)

Go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest(
        "POST",
        "https://api.turbonotify.com/v1/contacts/ct_.../refresh",
        nil,
    )
    req.Header.Set("Authorization", "Bearer SUA_CHAVE")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

PHP

<?php
$url = 'https://api.turbonotify.com/v1/contacts/ct_.../refresh';

$options = [
    'http' => [
        'header' => ['Authorization: Bearer SUA_CHAVE'],
        'method' => 'POST'
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
?>

C#

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer SUA_CHAVE");

var response = await client.PostAsync(
    "https://api.turbonotify.com/v1/contacts/ct_.../refresh",
    null
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java

import java.net.http.*;
import java.net.URI;

public class RefreshContato {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/contacts/ct_.../refresh"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .POST(HttpRequest.BodyPublishers.noBody())
            .build();

        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Resposta (202)

Status HTTP: 202

{
  "status": "queued",
  "requested_at": "2026-05-10T13:40:00Z"
}

requested_at é o momento do pedido (UTC, precisão de segundos). Ele identifica este pedido no campo refresh do contato.

Acompanhar o resultado

Consulte o contato com GET /v1/contacts/{contact_id} (ou GET /v1/numbers/{ref}/contacts/{contact_id}). O campo refresh mostra o último pedido de atualização que você fez:

"refresh": {
  "requested_at": "2026-05-10T13:40:00Z",
  "completed_at": null,
  "outcome": null
}

Enquanto a consulta está em andamento, completed_at e outcome ficam null. Quando ela termina, os dois são preenchidos:

outcome	O que significa	O que fazer
updated	O nome mudou no WhatsApp e o contato já mostra o nome novo.	Nada. O webhook contact.name_changed também é enviado.
unchanged	O nome do contato já estava atualizado.	Nada.
number_not_connected	O número dono do contato não estava conectado ao WhatsApp.	Reconecte o número e peça a atualização de novo.
unavailable	O WhatsApp não respondeu sobre este contato, ou não foi possível iniciar a consulta.	Tente de novo em alguns minutos.

Um novo pedido substitui o anterior: requested_at passa a ser o do novo pedido e completed_at/outcome voltam a null até ele terminar. Se o nome mudou, você também recebe o webhook contact.name_changed; nenhum outro evento é enviado por causa da atualização.

Veja eventos de contato.