Conexão de números extras

Desconecte um número extra já pareado para parar de usá-lo por um tempo, e reconecte quando quiser voltar, sem parear de novo. Números desconectados continuam cadastrados na conta, mas não podem ser usados como remetente. Para o primeiro vínculo com o WhatsApp, veja o pareamento pelo dashboard ou pela API.

Cobrança

Números extras desconectados continuam sendo cobrados enquanto estiverem cadastrados. Para encerrar a cobrança, é necessário remover o número. Consulte os detalhes em Cobrança de números extras.

Pelo dashboard

Acesse a página de Números (abre em nova aba) no dashboard para desconectar ou reconectar números com um clique.

Reconectar

Para reconectar um número extra desconectado, faça uma requisição POST para o endpoint de conexão informando o alias do número na URL.

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

const response = await fetch('https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/connect', {
  method: 'POST',
  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/connect"
headers = {
    "Authorization": "Bearer SUA_CHAVE"
}

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

package main

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

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

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

$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.PostAsync(
    "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/connect",
    null
);
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/connect"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .POST(HttpRequest.BodyPublishers.noBody())
            .build();

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

Status HTTP: 202

{
  "alias": "vendas_sp",
  "status": "connecting",
  "at": "2026-06-01T12:40:00Z"
}

A resposta (202 Accepted) confirma apenas que o pedido foi aceito: status é connecting e at é o instante em que o pedido foi aceito. O número conecta alguns segundos depois. O status final (connected ou failed) chega via webhook number.connected / number.connect.failed, ou consultando o Status dos números extras, que segue sendo a fonte do status atual do número e do at dele.

Desconectar

Para desconectar um número extra conectado, faça uma requisição POST para o endpoint de desconexão informando o alias do número na URL.

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

const response = await fetch('https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/disconnect', {
  method: 'POST',
  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/disconnect"
headers = {
    "Authorization": "Bearer SUA_CHAVE"
}

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

package main

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

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

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

$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.PostAsync(
    "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/disconnect",
    null
);
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/disconnect"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .POST(HttpRequest.BodyPublishers.noBody())
            .build();

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

Status HTTP: 202

{
  "alias": "vendas_sp",
  "status": "disconnecting",
  "at": "2026-06-01T12:40:00Z"
}

disconnecting aparece só nesta resposta (202 Accepted), como confirmação de que o pedido foi aceito, e at é o instante em que ele foi aceito. Diferente de connecting, disconnecting não é um dos valores da Tabela de status e não aparece em GET /v1/numbers/{ref} (que, logo após esta chamada, ainda mostra o status anterior e o at dele até o Turbo Notify concluir a desconexão). O status final (disconnected) chega via webhook number.disconnected, ou consultando o Status dos números extras.

O número principal tem suas próprias rotas, sem {ref} no path. As quatro rotas desta página respondem do mesmo jeito: 202 Accepted com os campos alias, status e at, com o mesmo significado.

POST /v1/numbers/main/connect → 202 Accepted, {"alias": "main", "status": "connecting", "at": "2026-06-01T12:40:00Z"}
POST /v1/numbers/main/disconnect → 202 Accepted, {"alias": "main", "status": "disconnecting", "at": "2026-06-01T12:40:00Z"}

Nenhuma das duas depende do plano. Ambas retornam 422 no_main_number_configured quando não há número principal cadastrado na conta. No connect: 422 main_number_not_paired quando o número existe mas ainda não concluiu o pareamento (pareie pelo dashboard primeiro), 409 already_connected e 409 already_connecting. No disconnect: 409 already_disconnected quando o número já está desconectado (nada a fazer, o objetivo já foi atingido).

Erros possíveis

Reconectar (`POST /v1/numbers/{ref}/connect`)

Status	Código de erro	Descrição
`402`	`subscription_inactive`	A assinatura da organização está `past_due`, `terminated`, `pending` ou com o período de teste expirado (resposta inclui `details.status`).
`402`	`feature_not_available`	O plano atual não suporta números extras.
`403`	`no_device_link`	O número extra não tem um vínculo ativo com o WhatsApp (estado inconsistente).
`403`	`extra_number_not_paired`	O número extra ainda não concluiu o pareamento. Chame `POST /v1/numbers/{ref}/pair` primeiro.
`404`	`number_not_found`	O alias ou id informado não corresponde a nenhum número cadastrado.
`409`	`already_connected`	O número extra já está conectado.
`409`	`already_connecting`	Já existe uma tentativa de conexão em andamento.
`500`	`internal_error`	Erro interno inesperado no servidor.

Desconectar (`POST /v1/numbers/{ref}/disconnect`)

Status	Código de erro	Descrição
`402`	`feature_not_available`	O plano atual não suporta números extras.
`404`	`number_not_found`	O alias ou id informado não corresponde a nenhum número cadastrado.
`409`	`already_disconnected`	O número extra já está desconectado (nada a fazer).
`500`	`internal_error`	Erro interno inesperado no servidor.

Ambas as rotas também retornam 401 not_authenticated (chave inválida/ausente) e 403 insufficient_scope (falta o escopo numbers:write, resposta inclui required_scope) como qualquer outro endpoint autenticado.