Inclusão de números extras

Com números extras, você envia mensagens de vários números de WhatsApp, além do número principal da conta. Incluir um número tem duas etapas: o cadastro, descrito nesta página, e o pareamento, que vincula o WhatsApp do número ao Turbo Notify, pelo dashboard ou pela API.

O cadastro dispara uma cobrança pro-rata imediata, que cobre os dias restantes do ciclo atual. Veja Cobrança de números extras para o valor, a fórmula e o reembolso. O número só é criado se a cobrança for aprovada.

Cadastro pelo dashboard

Para adicionar um número extra pelo dashboard, abra a página de Números (abre em nova aba) e clique em Adicionar número.

Informe o número de telefone com código do país e um alias: o cadastro é confirmado imediatamente, sem código de pareamento nesse momento. Em seguida, abra o número recém-criado, escolha o método de pareamento (QR code ou código de pareamento) e clique em Vincular número para gerar o código ou QR correspondente. Os passos estão em Pareamento pelo dashboard.

Cadastro via API

Você também pode cadastrar números extras pela API.

cURL

turbo-notify.sh

curl -X POST \
  https://api.turbonotify.com/v1/numbers \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+5511988887777",
    "alias": "vendas_sp",
    "description": "Equipe de vendas SP"
  }'

Node

turbo-notify.js

const response = await fetch('https://api.turbonotify.com/v1/numbers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '+5511988887777',
    alias: 'vendas_sp',
    description: 'Equipe de vendas SP'
  })
});

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

Python

turbo_notify.py

import requests

url = "https://api.turbonotify.com/v1/numbers"
headers = {
    "Authorization": "Bearer SUA_CHAVE",
    "Content-Type": "application/json"
}
data = {
    "phone_number": "+5511988887777",
    "alias": "vendas_sp",
    "description": "Equipe de vendas SP"
}

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

Go

turbo_notify.go

package main

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

func main() {
    payload := strings.NewReader(`{"phone_number": "+5511988887777", "alias": "vendas_sp", "description": "Equipe de vendas SP"}`)
    req, _ := http.NewRequest("POST", "https://api.turbonotify.com/v1/numbers", payload)
    req.Header.Set("Authorization", "Bearer SUA_CHAVE")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

PHP

turbo-notify.php

<?php
$url = 'https://api.turbonotify.com/v1/numbers';
$data = [
    'phone_number' => '+5511988887777',
    'alias' => 'vendas_sp',
    'description' => 'Equipe de vendas SP'
];

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer SUA_CHAVE',
            'Content-Type: application/json'
        ],
        'method' => 'POST',
        'content' => json_encode($data)
    ]
];

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

C#

TurboNotify.cs

using System.Text;
using System.Text.Json;

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

var data = new {
    phone_number = "+5511988887777",
    alias = "vendas_sp",
    description = "Equipe de vendas SP"
};

var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");

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

Java

TurboNotify.java

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

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

        var json = """
            {
                "phone_number": "+5511988887777",
                "alias": "vendas_sp",
                "description": "Equipe de vendas SP"
            }
            """;

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/numbers"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

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

Escopo obrigatório: numbers:write

O cadastro (POST /v1/numbers) e o pareamento (obtenção do código a ser inserido no WhatsApp) são operações separadas.

Campo	Tipo	Obrigatório	Descrição
phone_number	string	Sim	Telefone do número com código do país. Aceita o + inicial.
alias	string	Sim	Nome do número nas rotas /v1/numbers/{ref}/.... Deve começar com uma letra, ter no máximo 50 caracteres e não pode começar com num_.
description	string	Não	Descrição livre do número.

A resposta do cadastro confirma apenas a criação do número: o status sempre nasce "pending" e a resposta não traz código de pareamento. O id é o identificador do número, gerado pelo Turbo Notify, e nunca muda, mesmo que você renomeie o alias. Guarde-o: é a chave estável do número. Ele pode ser usado no lugar do alias em qualquer rota /v1/numbers/{ref}/....

Status HTTP: 201

{
  "id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "alias": "vendas_sp",
  "phone_number": "5511988887777",
  "status": "pending",
  "created_at": "2025-07-16T10:00:00Z",
  "description": "Equipe de vendas SP"
}

O + vale para a requisição, não para a resposta

Repare no phone_number acima: a requisição foi enviada com "+5511988887777", mas a resposta traz "5511988887777", sem o +.

O + é removido na gravação do número. Portanto:

• Requisição: phone_number aceita o + inicial ("+5511988887777").
• Resposta: phone_number nunca traz o +; são sempre dígitos E.164 puros ("5511988887777"), o mesmo formato do campo number em Listagem e Status.

Se você compara o valor enviado com o valor devolvido (para deduplicar ou confirmar cadastro), normalize removendo o + antes de comparar.

Próximo passo: pareamento

O número nasce com status: "pending". Para vinculá-lo ao WhatsApp, siga Pareamento pelo dashboard ou Pareamento pela API: os dois oferecem QR code e código de pareamento.

Regras do cadastro

• Cada número extra deve pertencer a um aparelho com WhatsApp ativo: é nele que o pareamento é concluído.
• alias é obrigatório, deve começar com uma letra e ter no máximo 50 caracteres. Ele identifica o número nas rotas /v1/numbers/{ref}/..., inclusive no envio de mensagens.
• O alias main e qualquer alias que comece com num_ são reservados.
• Um mesmo telefone só pode estar cadastrado uma vez na conta.
• Cada cadastro é uma cobrança real no cartão, por isso os cadastros têm um ritmo máximo por conta. Acima dele, a resposta é 429 number_creation_rate_limited, com o cabeçalho Retry-After dizendo em quantos segundos tentar de novo. Nada é cobrado nesse caso.

Erros possíveis

Status	Código de erro	Descrição
422	validation_error	O corpo é inválido: alias vazio, que não começa com letra ou com mais de 50 caracteres, phone_number ausente, ou algum campo de texto com caractere inválido. A resposta traz details.errors com o campo e a mensagem.
400	reserved_alias	O alias "main" ou um alias que começa com num_ é reservado e não pode ser usado em um número extra.
400	no_payment_method	A organização não tem forma de pagamento cadastrada. Nenhuma cobrança é tentada e nenhum número é criado.
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.
402	extra_numbers_limit_reached	A organização já atingiu o limite de números extras do plano (1.000 nos planos Empresarial e Personalizado). A resposta inclui details.limit e details.current.
402	payment_declined	A cobrança pro-rata de ativação (veja Cobrança de números extras) foi recusada pela forma de pagamento. Nenhum número é criado.
402	payment_requires_authentication	A forma de pagamento exige reautenticação (3DS) e não pode ser cobrada automaticamente. Nenhum número é criado.
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:write (resposta inclui required_scope).
409	number_already_exists	O alias ou o número informado já está cadastrado na conta.
429	number_creation_rate_limited	A sua conta cadastrou números extras mais rápido do que o permitido. Nada foi cobrado. Aguarde os segundos do cabeçalho Retry-After e tente de novo.
500	internal_error	Erro interno inesperado no servidor.
502	integration_error	O processador de pagamento respondeu com erro à cobrança de ativação. Nenhum número é criado; tente novamente em instantes.
503	payment_gateway_unavailable	A cobrança de ativação não pôde ser confirmada a tempo. Nenhum número é criado; tente novamente.