Status dos números extras

Consulte o status de cada número extra da sua conta para saber se ele está conectado e pronto para envio.

Consultar status

Para verificar o status de um número extra específico, faça uma requisição GET informando o alias ou o id do número.

curl -X GET \
  https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO \
  -H "Authorization: Bearer SUA_CHAVE"

const response = await fetch('https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE'
  }
});

const result = await response.json();
console.log(result);

import requests

url = "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO"
headers = {
    "Authorization": "Bearer SUA_CHAVE"
}

response = requests.get(url, headers=headers)
result = response.json()
print(result)

package main

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

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

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

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

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

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

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

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

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .GET()
            .build();

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

Escopo obrigatório: numbers:read

Status HTTP: 200

{
  "id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "contact_id": "ct_c7abb1f5ee9640bf86a0a20290810ae9",
  "name": "Condomínio Alpha",
  "type": "extra",
  "alias": "condominio_1",
  "number": "5511988887777",
  "status": "connected",
  "at": "2025-07-16T10:01:00Z",
  "description": null,
  "scheduled_deletion_at": null,
  "reason": null,
  "pairing": null
}

O número principal tem sua própria rota de status, GET /v1/numbers/main (mesmo escopo, numbers:read), com uma resposta mais curta: sem os campos description, scheduled_deletion_at, reason e pairing, porque o número principal é pareado só pelo dashboard. O id também vem como primeiro campo:

{
  "id": "num_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "contact_id": "ct_c7abb1f5ee9640bf86a0a20290810ae9",
  "name": "Laboratório Central",
  "type": "main",
  "alias": "main",
  "number": "5511973117056",
  "status": "connected",
  "at": "2026-04-07T10:00:00Z"
}

at acompanha o status atual

at é o momento em que o número entrou no status atual: atualiza a cada transição (pareamento, conexão, queda de conexão, reconexão, falha, revogação). Um número disconnected, failed, reconnecting etc. reporta o instante dessa própria transição, então desconectado desde {at} / falhou em {at} exibem o horário certo diretamente.

Durante uma reconexão automática (a conexão com o WhatsApp caiu, ou o Turbo Notify transferiu a conexão do número internamente), o status é reconnecting e at é o momento em que o número ficou offline, igual ao at do webhook number.disconnected. Se o número não volta em cerca de um minuto, você recebe o webhook number.disconnected com esse mesmo at. Depois de uma queda da conexão com o WhatsApp, o status continua reconnecting enquanto o Turbo Notify tenta reconectar; só depois de uma interrupção do lado do Turbo Notify ele passa a disconnected, com o mesmo at. Se o número volta dentro da janela, at passa a ser o momento da volta e nenhum webhook é enviado.

Um número recém-cadastrado (status: "pending") traz em at o momento do cadastro.

Uma exclusão agendada não altera o status nem o at: o número segue com o status de conexão que tem, e a data da exclusão vem separada, em scheduled_deletion_at.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	Identificador do número (`num_` e 32 caracteres). Gerado pelo Turbo Notify, nunca muda e continua o mesmo se o alias for renomeado
`contact_id`	string\|null	Identificador público (`ct_…`) do contato próprio do número; `null` enquanto não resolvido
`name`	string\|null	Nome da conta WhatsApp do número (capturado na conexão); `null` enquanto não houver conexão estabelecida
`type`	string	`"extra"` para um número extra. Se `{ref}` for o id do número principal, a resposta é a do `GET /v1/numbers/main` e `type` vale `"main"`
`alias`	string	Identificador único do número extra na conta
`number`	string	Número de telefone em dígitos E.164 (sem `+`)
`status`	string	Estado atual, veja Tabela de status
`at`	string	Timestamp ISO 8601 do momento em que o número entrou no status atual (`status`): atualiza a cada transição.
`description`	string\|null	A descrição cadastrada para o número; `null` quando não definida
`scheduled_deletion_at`	string\|null	Timestamp ISO 8601 da exclusão agendada (veja Remoção); `null` quando nenhuma exclusão está agendada. O número continua funcionando, com o `status` de sempre, até essa data
`reason`	string\|null	Motivo da falha quando `status` é `"failed"`, veja Motivos de falha; `null` em qualquer outro status
`pairing`	object\|null	O código ou o QR code do pareamento: presente apenas enquanto o número está em `pairing` e o código ou o QR code está pronto

Bloco de pareamento (`pairing`)

Presente quando status é pairing e o código ou o QR code está pronto (veja Pareamento de números extras pela API):

Campo	Tipo	Descrição
`method`	string	Método de pareamento: `"pairing_code"` ou `"qr"`
`data`	string	Com `pairing_code`, o código alfanumérico de 8 caracteres a ser inserido no WhatsApp (exibido com hífen, ex.: `Z5X7-LTYL`). Com `qr`, a imagem do QR code em PNG, como data URI (`data:image/png;base64,...`): use como `src` de um `<img>`, nunca como texto
`expires_at`	string	Timestamp ISO 8601 do fim da tentativa inteira, para os dois métodos

Leia method antes de mostrar data. O WhatsApp renova o QR code sozinho e o Turbo Notify mantém data atualizado: consulte de novo e troque a imagem a cada consulta. O bloco some quando a tentativa termina. Uma integração que só trata código deve conferir method e, com "qr", não mostrar data como texto.

Tabela de status

Status	Descrição
`pending`	Número cadastrado; aguardando início do pareamento.
`pairing`	Pareamento em andamento: o código ou o QR code está sendo gerado ou aguardando ser usado no WhatsApp.
`inactive`	Autenticação obtida, mas a conexão ainda não foi estabelecida.
`connecting`	Conexão sendo estabelecida (`POST .../connect` aceito).
`connected`	O número está vinculado e pronto para envio de mensagens.
`disconnected`	Conexão perdida ou desativada; a autenticação é preservada para reconectar.
`reconnecting`	O Turbo Notify está reconectando o número sozinho, depois de uma queda da conexão ou de uma transferência interna. Você não precisa fazer nada. Se o número não volta em cerca de um minuto, você recebe `number.disconnected` e o Turbo Notify continua tentando; depois de uma queda da conexão com o WhatsApp, o status segue `reconnecting` enquanto ele tenta.
`failed`	A vinculação falhou. O motivo vem em `reason`, veja abaixo.
`revoked`	O dispositivo foi desvinculado pelo WhatsApp.

Motivos de falha

Quando status é "failed", o campo reason diz o que aconteceu, para você mostrar a mensagem certa ao seu cliente. O mesmo valor chega no evento number.connect.failed, que traz também uma frase fixa em inglês para cada motivo. Em qualquer outro status, reason é null.

Motivo	O que aconteceu e o que fazer
`pairing_timeout`	O código ou o QR code foi gerado, mas não foi usado a tempo. Peça um novo código ou QR code.
`paired_phone_mismatch`	Outro WhatsApp usou o código ou leu o QR code. Pareie de novo usando o celular do número cadastrado.
`phone_already_bound`	Este número já está em uso na conta.
`main_number_not_connected`	O número principal da conta precisa estar conectado para parear números extras. Reconecte o número principal e pareie de novo.
`code_generation_failed`	Não foi possível obter o código ou o QR code do WhatsApp naquele momento. Tente de novo em instantes.
`connection_lost`	O número perdeu a conexão com o WhatsApp e precisa ser pareado de novo.
`pairing_failed`	Qualquer outra falha. Pareie de novo.

Novos motivos podem ser adicionados. Trate um valor que você não conhece como pairing_failed. Para montar a tela de pareamento do seu cliente, veja Pareamento de números extras pela API.

Erros possíveis

Status	Código de erro	Descrição
`402`	`feature_not_available`	O plano atual não suporta números extras.
`401`	`not_authenticated`	A chave de API está inválida ou ausente.
`403`	`insufficient_scope`	A chave de API não possui o escopo `numbers:read` (resposta inclui `required_scope`).
`404`	`number_not_found`	O alias ou id informado não foi encontrado na conta.
`500`	`internal_error`	Erro interno inesperado no servidor.