Atualização de números extras

Atualize o alias (o nome usado nas chamadas de API) ou a descrição de um número extra já cadastrado, sem precisar recriá-lo. O id do número continua o mesmo.

Atualizar pelo dashboard

Acesse a página de Números (abre em nova aba) no dashboard, abra o número desejado e edite o alias e/ou a descrição. Salve para aplicar as mudanças.

Atualizar via API

Faça uma requisição PATCH informando o alias atual (ou o id) do número na URL e, no corpo, apenas os campos que deseja alterar.

cURL

turbo-notify.sh

curl -X PATCH \
  https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "vendas_sp_2",
    "description": "Equipe de vendas SP (novo turno)"
  }'

Node

turbo-notify.js

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

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

Python

turbo_notify.py

import requests

url = "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO"
headers = {
    "Authorization": "Bearer SUA_CHAVE",
    "Content-Type": "application/json"
}
data = {
    "alias": "vendas_sp_2",
    "description": "Equipe de vendas SP (novo turno)"
}

response = requests.patch(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(`{"alias": "vendas_sp_2", "description": "Equipe de vendas SP (novo turno)"}`)
    req, _ := http.NewRequest("PATCH", "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO", 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/ALIAS_DO_NUMERO';

$data = [
    'alias' => 'vendas_sp_2',
    'description' => 'Equipe de vendas SP (novo turno)'
];

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer SUA_CHAVE',
            'Content-Type: application/json'
        ],
        'method' => 'PATCH',
        '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;

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

var payload = new StringContent(
    "{\"alias\": \"vendas_sp_2\", \"description\": \"Equipe de vendas SP (novo turno)\"}",
    Encoding.UTF8,
    "application/json"
);

var request = new HttpRequestMessage(HttpMethod.Patch, "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO")
{
    Content = payload
};
var response = await client.SendAsync(request);
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 request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .header("Content-Type", "application/json")
            .method("PATCH", HttpRequest.BodyPublishers.ofString(
                "{\"alias\": \"vendas_sp_2\", \"description\": \"Equipe de vendas SP (novo turno)\"}"
            ))
            .build();

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

Status HTTP: 200

{
  "id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "alias": "vendas_sp_2",
  "description": "Equipe de vendas SP (novo turno)",
  "status": "connected",
  "at": "2025-07-16T10:00:00Z",
  "scheduled_deletion_at": null
}

Escopo obrigatório: numbers:write

Os campos do corpo são opcionais e independentes: envie apenas o que quiser alterar.

Campo	Tipo	Obrigatório	Descrição
alias	string	Não	Novo alias do número. Precisa começar com uma letra, ter no máximo 50 caracteres e não pode ser "main" nem começar com num_ (reservados). Omita para manter o alias atual.
description	string | null	Não	Nova descrição do número. Envie null explicitamente para apagar a descrição atual; omita o campo para deixá-la como está.

A resposta traz o estado atualizado do número:

Campo	Tipo	Descrição
id	string	Identificador do número (num_ e 32 caracteres), o mesmo de antes da atualização. Nunca muda.
alias	string	Alias atual do número (o novo, se foi alterado). Use-o nas próximas chamadas a este número.
description	string | null	Descrição atual do número.
status	string	Estado atual do número, veja Tabela de status.
at	string | null	Quando o número entrou no status atual (o mesmo at do GET /v1/numbers/{ref}). Renomear não muda esse valor. É null enquanto o número não tem vínculo.
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.

Renomear não afeta a conexão

Alterar o alias ou a description não desconecta, não exige parear de novo e não reinicia o número: a conexão com o WhatsApp continua exatamente como estava. A partir da resposta, use o novo alias em qualquer chamada seguinte para este número.

O id é a chave estável

Renomear o alias não muda o id. Para achar o número de um cliente mesmo depois de uma renomeação, guarde o id e consulte GET /v1/numbers/{ref} com ele. Os eventos também trazem o number_id. O number_alias de um evento mostra o alias que o número tinha no momento em que o evento aconteceu.

Número principal

O número principal não pode ser alterado: PATCH /v1/numbers/main responde 403 main_number_update_not_allowed para qualquer corpo.

Erros possíveis

Status	Código de erro	Descrição
400	reserved_alias	O novo alias é "main" ou começa com num_, ambos reservados.
400	no_changes	Nenhum campo foi enviado, ou o único campo enviado (alias) é igual ao valor atual.
400	invalid_number_id	O valor na URL começa com num_, mas não é um id de número válido (num_ seguido de 32 caracteres).
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:write (resposta inclui required_scope).
403	main_number_update_not_allowed	O número principal (main) não pode ser alterado.
404	number_not_found	O alias ou id informado no path não corresponde a nenhum número cadastrado.
409	alias_already_exists	Já existe outro número extra usando o alias informado.
422	validation_error	alias está vazio, não começa com letra ou tem mais de 50 caracteres, ou algum campo de texto contém caractere inválido. A resposta traz details.errors com o campo e a mensagem específicos.
500	internal_error	Erro interno inesperado no servidor.