Começo rápido

Este guia leva você do cadastro à primeira mensagem enviada pela API e recebida de volta. São cinco passos, e o segundo (conectar o seu número de WhatsApp) é o que mais gente pula: sem ele, todo envio responde 409 number_not_connected.

Você vai precisar de um celular com WhatsApp no número que vai enviar as mensagens. O Turbo Notify se conecta a ele como um dispositivo conectado, do mesmo jeito que o WhatsApp Web, e o celular continua funcionando.

Por isso não há cadastro na Meta nem aprovação de modelos de mensagem: o Turbo Notify é um serviço independente, sem afiliação com a Meta, e não usa a API oficial do WhatsApp Business. Cada envio segue um ritmo que ajuda a proteger o seu número, e as boas práticas mantêm o número saudável.

1. Crie a conta

Crie uma conta gratuita em dashboard.turbonotify.com. Se já tem conta, entre e siga para o próximo passo.

2. Conecte o número principal

O número principal é o WhatsApp que envia e recebe as mensagens da sua conta. Ele é conectado pelo dashboard:

No dashboard, abra Números (abre em nova aba) e, no cartão Número principal, clique em Conectar número principal.
Escolha QR Code ou Código de pareamento.
No celular, abra o WhatsApp em Dispositivos conectados > Conectar dispositivo. Para o QR code, aponte a câmera para a tela. Para o código, toque em Conectar com número de telefone e digite o código mostrado no dashboard.
O cartão passa a mostrar o número como conectado, e o Turbo Notify aparece em Dispositivos conectados no celular com o nome da sua organização.

Para conferir pela API, GET /v1/numbers/main devolve status: "connected" (veja Status).

3. Gere uma chave de API

No dashboard, abra API Keys (abre em nova aba) e crie uma chave com o template Acesso total. O valor aparece uma única vez: copie e guarde num lugar seguro. Toda requisição leva a chave no cabeçalho Authorization: Bearer SUA_CHAVE (detalhes em Chave de API).

4. Envie a primeira mensagem

Troque SUA_CHAVE pela sua chave e o número de destino por um WhatsApp seu, com código do país:

curl -X POST \
  https://api.turbonotify.com/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "content": {"text": "Seu pedido foi confirmado!"}
  }'

const response = await fetch('https://api.turbonotify.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: { number: '+5511988887777' },
    content: { text: 'Seu pedido foi confirmado!' }
  })
});

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

import requests

url = "https://api.turbonotify.com/v1/messages"
headers = {
    "Authorization": "Bearer SUA_CHAVE",
    "Content-Type": "application/json"
}
data = {
    "to": {"number": "+5511988887777"},
    "content": {"text": "Seu pedido foi confirmado!"}
}

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

package main

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

func main() {
    payload := strings.NewReader(`{"to": {"number": "+5511988887777"}, "content": {"text": "Seu pedido foi confirmado!"}}`)
    req, _ := http.NewRequest("POST", "https://api.turbonotify.com/v1/messages", 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
$url = 'https://api.turbonotify.com/v1/messages';
$data = [
    'to' => ['number' => '+5511988887777'],
    'content' => ['text' => 'Seu pedido foi confirmado!']
];

$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);
?>

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

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

var data = new {
    to = new { number = "+5511988887777" },
    content = new { text = "Seu pedido foi confirmado!" }
};

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

var response = await client.PostAsync(
    "https://api.turbonotify.com/v1/messages",
    content
);
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 json = """
            {
                "to": {"number": "+5511988887777"},
                "content": {"text": "Seu pedido foi confirmado!"}
            }
            """;

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/messages"))
            .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());
    }
}

A resposta 202 diz que o Turbo Notify aceitou a mensagem. A entrega ao WhatsApp acontece em seguida, de forma assíncrona:

Status HTTP: 202

{
  "message_id": "msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "status": {
    "state": "pending",
    "at": "2025-07-16T10:00:00Z",
    "error": null
  }
}

Para acompanhar a entrega, consulte a mensagem pelo message_id:

curl https://api.turbonotify.com/v1/messages/msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 \
  -H "Authorization: Bearer SUA_CHAVE"

const response = await fetch('https://api.turbonotify.com/v1/messages/msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4', {
  headers: { 'Authorization': 'Bearer SUA_CHAVE' }
});
const result = await response.json();
console.log(result.status.state); // 'sent', 'delivered', 'read', ...

import requests

response = requests.get(
    'https://api.turbonotify.com/v1/messages/msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    headers={'Authorization': 'Bearer SUA_CHAVE'}
)
print(response.json()['status']['state'])

package main

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

func main() {
    req, _ := http.NewRequest("GET",
        "https://api.turbonotify.com/v1/messages/msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", nil)
    req.Header.Set("Authorization", "Bearer SUA_CHAVE")
    resp, _ := http.DefaultClient.Do(req)
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

<?php
$ch = curl_init('https://api.turbonotify.com/v1/messages/msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer SUA_CHAVE']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
echo $result['status']['state'];
?>

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer SUA_CHAVE");
var response = await client.GetAsync(
    "https://api.turbonotify.com/v1/messages/msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4");
Console.WriteLine(await response.Content.ReadAsStringAsync());

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

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/messages/msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .GET()
            .build();
        var response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Status HTTP: 200

{
  "id": "msg_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "organization_id": "org_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "number_alias": "main",
  "number_id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "from": {
    "contact_id": "ct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "name": "Minha Empresa",
    "number": "5511977776666",
    "alias": "main"
  },
  "to": {
    "number": "5511988887777"
  },
  "preview": "Seu pedido foi confirmado!",
  "content_expired": false,
  "text": "Seu pedido foi confirmado!",
  "content_type": "text",
  "direction": "outbound",
  "channel": "whatsapp",
  "origin": "tn",
  "at": "2025-07-16T10:00:00Z",
  "status": {
    "state": "delivered",
    "at": "2025-07-16T10:00:05Z"
  }
}

Os estados de entrega estão em Status da mensagem.

5. Receba as respostas

Quando alguém responde, o Turbo Notify gera um evento message.received. Você o recebe de um destes dois jeitos:

Forma	Como funciona	Quando usar
Webhook	O Turbo Notify faz um `POST` assinado no seu endpoint a cada evento. Configure a URL no dashboard, em Webhooks (abre em nova aba) . Disponível a partir do plano Lobo Solitário.	Você tem um endpoint HTTPS público e quer reagir na hora.
Polling de eventos	Você consulta `GET /v1/events` de tempos em tempos (escopo `events:read`). Disponível em todos os planos.	Você não tem endpoint público, está testando ou está no plano gratuito.

Os dois entregam os mesmos eventos, com o mesmo formato. Para escolher, veja Quando usar polling.

O que pode dar errado

Resposta	O que significa	O que fazer
`409 number_not_connected`	O número que envia não está conectado ao WhatsApp.	Volte ao passo 2 e conecte o número principal. Se ele já estava conectado, veja se o Turbo Notify não foi removido de Dispositivos conectados no celular.
`401 not_authenticated`	A chave está ausente, errada ou revogada.	Confira o cabeçalho `Authorization: Bearer SUA_CHAVE`.
`403 insufficient_scope`	A chave não tem o escopo da operação (`required_scope` diz qual).	Use uma chave com o escopo indicado, ou o template Acesso total.
`400 invalid_phone_number`	O destino não é um telefone válido.	Envie o número com código do país, como `+5511988887777`.
`429 send_rate_spacing`	Você enviou antes do intervalo mínimo entre mensagens do seu plano.	Espere os segundos do cabeçalho `Retry-After`. Esse ritmo protege o seu número.
`429 messages_quota_exceeded` ou `402 contact_quota_exceeded`	A cota de mensagens ou de contatos do ciclo acabou.	Veja Cota e uso.
Mensagem com `state: "failed"`	O WhatsApp não aceitou a mensagem.	O campo `status.error` traz o código e uma dica. Veja Status da mensagem.

Todos os códigos estão em Códigos de erro.

Próximos passos

Construa um agente de IA: o seu agente lê e responde no WhatsApp pelo servidor MCP, entrando com a sua conta ou com uma chave.
Revenda para seus clientes: um número por cliente, pareado de dentro da sua plataforma.
Envio de mídia, reações e indicador de digitação: além do texto.
Referência da API: todos os endpoints, com teste de requisição pelo navegador.
Proteja o seu número: o ritmo de envio e as boas práticas que mantêm o número saudável.