Pular para o conteúdo
Turbo Notify

Revenda para seus clientes

Se a sua plataforma (um CRM, um sistema de agendamento, um agente de IA) quer oferecer WhatsApp aos clientes dela, você pode fazer isso com uma única conta Turbo Notify: cada cliente final ganha um número extra na sua conta, pareado pelo celular dele, de dentro da sua tela. Você paga ao Turbo Notify um valor fixo por número e cobra dos seus clientes o que quiser.

Como funciona

EtapaQuem fazComo
Cadastrar o número do clienteSua plataformaPOST /v1/numbers com um alias por cliente; guarde o id da resposta
ParearO cliente, no celular deleDigita o código ou lê o QR code que a sua tela mostra
Enviar e receberSua plataformaAPI REST ou servidor MCP no alias do número, eventos no seu webhook
Cobrar o clienteSua plataformaO preço é seu
RemoverSua plataformaDELETE /v1/numbers/{ref}

O que você precisa

  • Plano Empresarial. Números extras existem nos planos Empresarial e Personalizado. Uma conta comporta até 1.000 números extras; para mais, fale com sales@turbonotify.com sobre o plano Personalizado.
  • Número principal conectado. O pareamento de um número extra só acontece com o número principal da conta conectado; sem ele, o pareamento falha com reason: "main_number_not_connected". Conecte-o como no Começo rápido e acompanhe-o (number.disconnected e number.revoked com alias: "main").
  • Uma chave com o template Revenda. Em API Keys (abre em nova aba) , o template Revenda marca numbers:read, numbers:write, messages:send, messages:read, contacts:read e events:read. A chave fica no servidor da sua plataforma; nunca a entregue a um cliente final. Veja Chave de API.

Quanto custa

Cada número extra custa R$ 34,90 por mês, além do plano Empresarial (R$ 69,90 por mês). Cada número extra tem a cota completa do plano, que no Empresarial é de 50.000 mensagens por ciclo, e não divide cota com os outros números.

Você define quanto cobra de cada cliente. O Turbo Notify não cobra comissão sobre a sua venda.

Ao cadastrar um número no meio do ciclo, a conta paga na hora o valor proporcional aos dias que faltam; a partir do ciclo seguinte, o número entra na fatura pelo valor cheio. O número só é criado se essa cobrança for aprovada. Detalhes em Cobrança de números extras.

1. Cadastre um número por cliente

Cada número tem um id (como num_0a1b2c3d4e5f60718293a4b5c6d7e8f9) que o Turbo Notify gera ao cadastrar e que nunca muda, nem se o alias for renomeado. Guarde na sua base o par id e cliente: o id devolvido no cadastro é a chave. Como endereço de leitura fácil, dê a cada número um alias previsível, por exemplo cliente_4821:

Terminal window
curl -X POST https://api.turbonotify.com/v1/numbers \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+5511988887777",
    "alias": "cliente_4821",
    "description": "Clínica Ana Souza"
  }'

A resposta traz o id do número como primeiro campo.

O mesmo exemplo em Node, Python, Go, PHP, C# e Java está em Inclusão de números extras.

  • alias endereça o número em todas as rotas (/v1/numbers/cliente_4821/messages). Começa com uma letra e tem até 50 caracteres. Não pode começar com num_, prefixo reservado aos ids.
  • O id serve no mesmo lugar do alias, em qualquer rota: /v1/numbers/num_0a1b2c3d4e5f60718293a4b5c6d7e8f9/messages.
  • Para achar o número de um cliente de novo, consulte GET /v1/numbers/cliente_4821 ou GET /v1/numbers/num_0a1b2c3d4e5f60718293a4b5c6d7e8f9. As duas respostas são iguais.
  • O número nasce com status: "pending".

Cada cadastro é uma cobrança real no cartão, então o ritmo de cadastros por conta é limitado: acima dele, a resposta é 429 number_creation_rate_limited com o cabeçalho Retry-After, e nada é cobrado. Detalhes em Inclusão de números extras.

2. Pareie pelo celular do cliente

O cliente conclui o pareamento sozinho, na sua tela, sem falar com você:

  1. Peça o pareamento com POST /v1/numbers/cliente_4821/pair. Sem corpo, a API gera o código; com {"method": "qr"}, gera um QR code.
  2. Consulte GET /v1/numbers/cliente_4821 a cada 2 segundos. Quando o bloco pairing vier preenchido, confira pairing.method. Com pairing_code, mostre pairing.data como texto (o código, como Z5X7-LTYL). Com qr, mostre pairing.data como imagem (<img src>) e troque a imagem a cada consulta, porque o QR code se renova. Nos dois casos, mostre a contagem regressiva até pairing.expires_at.
  3. Mostre ao cliente o caminho no celular. Para o código: WhatsApp > Dispositivos conectados > Conectar dispositivo > Conectar com número de telefone, e digitar o código. Para o QR code: WhatsApp > Dispositivos conectados > Conectar dispositivo, e apontar a câmera para a imagem.
  4. Deixe Gerar novo código (ou Gerar novo QR code) sempre visível. Um código digitado errado é invalidado na hora pelo WhatsApp, sem aviso a ninguém; o botão chama POST .../pair de novo e o novo código ou QR code substitui o anterior.
  5. Encerre pelo resultado: status: "connected" é sucesso; status: "failed" traz o motivo em reason.

Os pedidos de pareamento são limitados por número e por conta, para que o próprio WhatsApp não bloqueie novos códigos. Em um 429 pairing_rate_limited, mostre o tempo do cabeçalho Retry-After em vez de repetir. O passo a passo completo, com exemplos, está em Pareamento pela API.

Depois de pareado, o número aparece em Dispositivos conectados no celular do cliente com o nome da sua organização.

O que dizer ao cliente quando falha

reasonMensagem para o cliente
pairing_timeoutO código ou o QR code não foi usado a tempo. Gere um novo e use em seguida.
paired_phone_mismatchO código foi digitado, ou o QR code lido, em outro WhatsApp. Use o celular do número cadastrado.
phone_already_boundEste número já está em uso. Fale com o suporte da plataforma.
main_number_not_connectedEstamos com uma instabilidade. Tente de novo em alguns minutos. (Para você: reconecte o número principal.)
code_generation_failedNão foi possível obter o código ou o QR code agora. Tente de novo em instantes.
connection_lostA conexão caiu durante o pareamento. Pareie de novo.
pairing_failedNão foi possível concluir. Tente de novo.

Trate um reason que você não conhece como pairing_failed. O mesmo motivo chega no webhook number.connect.failed.

3. Um webhook para todos os clientes

Cadastre um único webhook da conta em Webhooks (abre em nova aba) . Ele recebe os eventos de todos os números, e cada evento diz de qual número veio:

  • Todo evento de um número traz o number_id no envelope, logo depois do number_alias. Encaminhe cada evento ao cliente certo pelo number_id, com a sua tabela de id e cliente.
  • Os eventos number.* (conectado, desconectado, revogado, falha de pareamento, remoção) trazem o mesmo id em data.id.
  • O number_alias de um evento é o alias que o número tinha quando o evento aconteceu. Se você renomear um número, um evento antigo ainda mostra o alias antigo, e um alias antigo deixa de existir nas rotas. Por isso, compare sempre pelo number_id, que não muda: o alias serve só para leitura.

Para acompanhar a sua base, GET /v1/numbers?status=failed ou ?status=disconnected lista os números que precisam de atenção. Quando um número é revogado no celular (number.revoked), avise o cliente e ofereça parear de novo.

4. Envie e receba em nome do cliente

Toda rota de mensagens, contatos e grupos fica debaixo do alias do número: POST /v1/numbers/cliente_4821/messages. Pelo servidor MCP, as ferramentas aceitam number_alias. As cotas são de cada número, então o uso de um cliente não consome a cota de outro.

5. Remova quando o cliente sair

Remova o número: DELETE /v1/numbers/cliente_4821. Desconectar antes não é necessário.

Se você remover um número logo depois de cadastrá-lo, antes de usá-lo, a cobrança do cadastro pode ser reembolsada automaticamente. Nos outros casos, a remoção é agendada para o fim do período já pago: até lá o número continua funcionando e a remoção pode ser cancelada com POST /v1/numbers/{ref}/cancel-deletion. Ele não entra na fatura do período seguinte. A resposta do DELETE diz o que aconteceu (refund_eligible, refund_amount_cents, refund_status, scheduled_deletion_at). Dúvidas sobre reembolso: billing@turbonotify.com. Veja Remoção.

Depois da remoção, a entrada do número pode continuar na lista Dispositivos conectados do celular do cliente como Desconectado, ocupando uma das 4 vagas de aparelhos do WhatsApp. Avise o cliente que, para liberar a vaga, ele abre essa lista, toca na entrada e escolhe Remover dispositivo.

Boas práticas para os seus clientes

Cada número segue o ritmo de envio do plano, que ajuda a protegê-lo, e números novos têm o volume limitado nos primeiros dias. Quem decide sobre restrições é o WhatsApp, então vale orientar os seus clientes a:

  • Enviar só para quem conhece o número e aceitou receber mensagens.
  • Começar devagar com um número novo.
  • Evitar a mesma mensagem para muitos destinatários em sequência.

Antes de conectar o número de um cliente, conte a ele que o Turbo Notify é um serviço independente, sem afiliação com a Meta, e que o WhatsApp pode restringir números. Os Termos de serviço (abre em nova aba) pedem esse aviso. As práticas completas estão em Proteja o seu número.

Próximos passos