Detalhe do contato

Retorna o payload completo de um contato, incluindo telefone e metadados da foto de perfil.

Endpoint

GET /v1/contacts/{contact_id}

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

Escopo obrigatório: contacts:read.

Parâmetro de rota

Parâmetro	Tipo	Formato
contact_id	string	ct_{hex32}: regex ^ct_[0-9a-f]{32}$

Exemplo

cURL

curl "https://api.turbonotify.com/v1/contacts/ct_a1b2c3d4e5f6789012345678901234ab" \
  -H "Authorization: Bearer SUA_CHAVE"

Node

const id = "ct_a1b2c3d4e5f6789012345678901234ab";

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

Python

import httpx

contact_id = "ct_a1b2c3d4e5f6789012345678901234ab"

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

Go

package main

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

func main() {
    req, _ := http.NewRequest(
        "GET",
        "https://api.turbonotify.com/v1/contacts/ct_a1b2c3d4e5f6789012345678901234ab",
        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_a1b2c3d4e5f6789012345678901234ab';

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

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$contact = json_decode($result, true);
var_dump($contact);
?>

C#

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

var response = await client.GetAsync(
    "https://api.turbonotify.com/v1/contacts/ct_a1b2c3d4e5f6789012345678901234ab"
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java

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

public class DetalheContato {
    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_a1b2c3d4e5f6789012345678901234ab"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .GET()
            .build();

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

Resposta (200)

Status HTTP: 200

{
  "id": "ct_a1b2c3d4e5f6789012345678901234ab",
  "number_alias": "main",
  "phone_number": "+5511988887777",
  "name": "João Silva",
  "is_self": false,
  "first_messaged_at": "2026-05-10T13:25:00Z",
  "last_interaction_at": "2026-05-10T13:42:00Z",
  "verified_on_whatsapp_at": "2026-05-10T13:25:00Z",
  "picture": {
    "kind": "available",
    "url": "https://cdn.example.com/contacts/ct_a1b2.jpg",
    "url_expires_at": "2026-05-10T14:25:00Z",
    "hash": "a3f1c9...",
    "fetched_at": "2026-05-10T13:25:00Z"
  },
  "refresh": {
    "requested_at": "2026-05-10T13:40:00Z",
    "completed_at": "2026-05-10T13:40:06Z",
    "outcome": "updated"
  },
  "created_at": "2026-05-10T13:25:00Z",
  "updated_at": "2026-05-10T13:42:00Z"
}

O number_alias identifica o número do Turbo Notify a que o contato pertence: main ou o alias de um número extra. O mesmo telefone alcançado por dois números gera dois contatos. O phone_number é o E.164 completo, sem máscara, igual ao que aparece em message.from e message.to. O name é o nome que o contato definiu no perfil do WhatsApp (o mesmo trio {id, name, number} dos eventos contact.*). O formato de picture depende de kind (available ou unavailable), como no bloco de mídia dos eventos, e traz fetched_at quando kind é available. O valor pending só aparece em webhooks: este endpoint nunca o retorna.

Datas de interação e atualização

Campo	Significado
first_messaged_at	Quando a primeira mensagem enviada por este número via Turbo Notify chegou ao contato no WhatsApp. null enquanto nenhuma chegou. Um envio que falhou antes de chegar ao WhatsApp não preenche este campo.
last_interaction_at	A última mensagem trocada de fato com o contato, em qualquer direção: recebida, enviada pelo celular ou enviada via Turbo Notify e entregue ao WhatsApp. Um envio que não chegou ao WhatsApp não altera este campo.
refresh	O último pedido de atualização que você fez para este contato. null se você nunca fez. Traz requested_at, completed_at e outcome; os dois últimos ficam null enquanto a atualização está em andamento.

Erros

• 404 contact_not_found: o contato não existe, pertence a outra organização ou a outro número. Um contact_id fora do formato ct_{hex32} retorna 400 invalid_contact_id.

Veja a referência de erros.