Listagem de números

Liste todos os números da sua conta (o principal e os extras) para consultar id, alias, número de telefone e status de cada um em uma única chamada.

Listar números

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

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

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

import requests

url = "https://api.turbonotify.com/v1/numbers"
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", 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';

$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"
);
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"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .GET()
            .build();

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

Status HTTP: 200

{
  "data": [
    {
      "id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
      "contact_id": "ct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "name": "Turbo Notify",
      "type": "main",
      "alias": "main",
      "number": "5511973117056",
      "description": null,
      "status": {
        "status": "connected",
        "at": "2025-07-16T09:00:00Z",
        "reason": null
      },
      "scheduled_deletion_at": null
    },
    {
      "id": "num_1b2c3d4e5f60718293a4b5c6d7e8f90a",
      "contact_id": "ct_c7abb1f5ee9640bf86a0a20290810ae9",
      "name": "Condomínio Alpha",
      "type": "extra",
      "alias": "condominio_1",
      "number": "5511988887777",
      "description": "Avisos do condomínio 1",
      "status": {
        "status": "connected",
        "at": "2025-07-16T10:01:00Z",
        "reason": null
      },
      "scheduled_deletion_at": "2025-08-16T10:00:00Z"
    },
    {
      "id": "num_2c3d4e5f60718293a4b5c6d7e8f90a1b",
      "contact_id": null,
      "name": null,
      "type": "extra",
      "alias": "condominio_2",
      "number": "5511977776666",
      "description": null,
      "status": {
        "status": "connecting",
        "at": "2025-07-16T10:05:00Z",
        "reason": null
      },
      "scheduled_deletion_at": null
    },
    {
      "id": "num_3d4e5f60718293a4b5c6d7e8f90a1b2c",
      "contact_id": null,
      "name": null,
      "type": "extra",
      "alias": "condominio_3",
      "number": "5511966665555",
      "description": null,
      "status": {
        "status": "pending",
        "at": "2025-07-16T10:10:00Z",
        "reason": null
      },
      "scheduled_deletion_at": null
    }
  ],
  "cursor": null,
  "has_more": false
}

Sem filtros, GET /v1/numbers retorna todos os números cadastrados na organização: o principal primeiro, seguido pelos extras em ordem de criação.

status.at acompanha o status atual

status.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, não um timestamp de conexão desatualizado.

Durante uma reconexão automática (transferência interna da conexão), o número aparece como reconnecting e, se não volta em cerca de um minuto, como disconnected; nos dois casos status.at é o momento em que ele ficou offline. Veja Status.

Um número recém-cadastrado, que ainda não foi pareado (status: "pending", como condominio_3 no exemplo acima), traz em status.at o momento do cadastro.

Um número extra com exclusão agendada (condominio_1 no exemplo acima) não muda de status: ele segue connected e continua funcionando, e a data da exclusão vem em scheduled_deletion_at.

Escopo obrigatório: numbers:read

Filtro

Um filtro opcional na query string reduz a lista:

Parâmetro	Descrição
`status`	Só os números neste status. Aceita um dos valores da Tabela de status, por exemplo `?status=failed`. Um valor fora da tabela responde `422 validation_error`.

O número principal só aparece na lista quando atende ao filtro.

# Números da conta que falharam no pareamento
curl -X GET \
  "https://api.turbonotify.com/v1/numbers?status=failed" \
  -H "Authorization: Bearer SUA_CHAVE"

# O número do seu cliente 4821, pelo alias ou pelo id
curl -X GET \
  "https://api.turbonotify.com/v1/numbers/cliente_4821" \
  -H "Authorization: Bearer SUA_CHAVE"

Para achar um número específico, consulte-o direto: GET /v1/numbers/{ref}, com o alias ou o id (veja Status).

Campos da resposta

Campo	Tipo	Descrição
`data`	array	Lista de números da conta (principal + extras)
`cursor`	string\|null	Sempre `null`: esta rota não pagina
`has_more`	boolean	Sempre `false`: esta rota devolve todos os números em uma única página
`data[].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. Pode ser usado no lugar do alias em qualquer rota `/v1/numbers/{ref}/...`
`data[].contact_id`	string\|null	Identificador público (`ct_…`) do contato próprio do número; `null` enquanto não resolvido
`data[].name`	string\|null	Nome da conta WhatsApp do número (capturado na conexão); `null` enquanto não houver conexão estabelecida
`data[].type`	string	`"main"` para o número principal (sempre o primeiro item) ou `"extra"` para números extras
`data[].alias`	string	Identificador único do número na conta (`"main"` para o principal)
`data[].number`	string	Número de telefone em dígitos E.164 (sem `+`)
`data[].description`	string\|null	Descrição livre definida por você
`data[].status`	object	`{status, at, reason?}`: estado atual do número
`data[].status.status`	string	`pending`, `pairing`, `inactive`, `connecting`, `connected`, `disconnected`, `reconnecting`, `failed` ou `revoked`, veja Tabela de status
`data[].status.at`	string	Timestamp ISO 8601 do momento em que o número entrou no status atual (`data[].status.status`): atualiza a cada transição.
`data[].status.reason`	string\|null	Motivo da falha quando `status.status` é `"failed"` (mesmos valores de Motivos de falha); `null` em qualquer outro status.
`data[].scheduled_deletion_at`	string\|null	Timestamp ISO 8601 da exclusão agendada (veja Remoção); `null` no número principal e em todo número extra sem exclusão agendada. O número continua funcionando, com o `status` de sempre, até essa data

Erros possíveis

GET /v1/numbers não depende do plano: o número principal sempre pode ser listado, e a listagem retorna qualquer número extra que já exista na conta independente do plano atual.

A listagem é a única operação de números extras liberada em qualquer plano. Todas as demais (criar, consultar status, conectar/desconectar e remover) exigem um plano com suporte a números extras e retornam 402 feature_not_available caso contrário. Em uma conta que mudou para um plano sem números extras, você continua enxergando os números extras existentes, mas não consegue gerenciá-los.

Status	Código de erro	Descrição
`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`).
`422`	`validation_error`	O filtro `status` tem um valor que não está na Tabela de status.
`500`	`internal_error`	Erro interno inesperado no servidor.