Referência da API

A API REST do WallaWhats permite gerenciar telefones, assinaturas de contas do X e histórico de notificações de forma programática — exatamente o que você faria pelo painel.

URL base: https://api.wallawhats.com
Content type: application/json
Autenticação: API key (cabeçalho)
Versionamento: a API é estável. Mudanças incompatíveis são anunciadas com 30 dias de antecedência por e-mail a todas as contas.

Autenticação

Toda requisição deve incluir uma API key no cabeçalho x-api-key:

bash

curl https://api.wallawhats.com/user/profile \
  -H "x-api-key: bws_prod_00000000000000000000000000000000"

As chaves são criadas no painel em Settings → API Keys ou via POST /apikeys. O prefixo da chave começa com bws_ e tem 36 caracteres. As chaves aparecem apenas uma vez, no momento da criação — se perder uma, exclua-a e crie outra.

Escopo e expiração

Uma chave autentica como o usuário que a criou. Tem as mesmas permissões desse usuário e consome as mesmas cotas do plano.
As chaves são válidas por 365 dias. Faça rotação criando uma nova chave, migrando para ela e excluindo a antiga.
Chaves ausentes, mal formatadas ou revogadas retornam 401 Unauthorized.

Limite de chaves por plano

Plano	Chaves permitidas
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Tentar criar mais do que seu plano permite retorna 400 com "error": "api key limit reached".

Erros

Os erros são retornados em JSON com um campo error e um código de status HTTP:

json

{ "error": "phoneNumber is required" }

Status	Significado
`400`	Parâmetros inválidos, cota excedida ou violação de regra de negócio
`401`	API key ausente ou inválida
`402`	Créditos insuficientes para concluir a operação
`404`	Recurso não encontrado
`500`	Erro do servidor — tente novamente com backoff exponencial

Limites de taxa

Padrão: 20 requisições/segundo por API key, com burst de até 40.
Endpoints de listagem retornam até 50 itens por página; use o cursor lastKey para paginar.
Regras do WAF podem retornar 403 em padrões abusivos. Se achar que está sendo limitado de forma inesperada, fale com o suporte.

User

Obter seu perfil

GET /user/profile

Retorna o perfil do usuário autenticado.

Resposta

json

{
  "userId": "5a4cbd70-...",
  "email": "jane@example.com",
  "name": "Jane",
  "plan": "pro_plus",
  "createdAt": 1745000000000
}

Exemplo

bash

curl https://api.wallawhats.com/user/profile \
  -H "x-api-key: bws_prod_..."

Phones

Um telefone é um número de WhatsApp verificado que pode receber alertas. É preciso verificar um telefone antes de assinar uma conta do X nele.

Cadastrar um telefone

POST /phones

Gera um código de 6 dígitos e envia para o número via WhatsApp. O telefone é criado no estado pending_verification.

Requisição

Campo	Tipo	Obrigatório	Notas
`phoneNumber`	string	sim	Formato E.164, por exemplo `+5511987654321`
`displayName`	string	não	Rótulo amigável exibido no painel

Resposta

json

{ "phoneNumber": "+5511987654321", "status": "pending_verification" }

Erros

400 "invalid phone number format" — não está em E.164
400 "phone number limit reached" — excede o limite do plano (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Exemplo

bash

curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: bws_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+5511987654321", "displayName": "Work"}'

Verificar um telefone

POST /phones/verify

Confirma um telefone enviando o código de 6 dígitos. Os códigos expiram em 15 minutos.

Requisição

Campo	Tipo	Obrigatório
`phoneNumber`	string (E.164)	sim
`code`	string (6 dígitos)	sim

Resposta

json

{ "phoneNumber": "+5511987654321", "status": "verified" }

Erros

404 "phone not found"
400 "invalid code" — código incorreto
400 "code expired" — mais de 15 minutos
400 "phone already verified"

Listar seus telefones

GET /phones

Resposta

json

{
  "phones": [
    {
      "phoneNumber": "+5511987654321",
      "status": "verified",
      "displayName": "Work",
      "createdAt": 1745000000000,
      "verifiedAt": 1745000060000
    }
  ],
  "count": 1
}

Excluir um telefone

DELETE /phones/{phoneNumber}

Remove o telefone e desativa quaisquer assinaturas direcionadas a ele. Codifique o + na URL como %2B.

Resposta

json

{ "success": true }

Exemplo

bash

curl -X DELETE "https://api.wallawhats.com/phones/%2B5511987654321" \
  -H "x-api-key: bws_prod_..."

Subscriptions

Uma assinatura vincula uma conta do X que você quer monitorar a um dos seus telefones verificados. Quando a conta do X publica, o WallaWhats envia um alerta de WhatsApp para esse telefone.

Criar uma assinatura

POST /subscriptions

Requisição

Campo	Tipo	Obrigatório	Notas
`xUsername`	string	sim	1–15 caracteres, alfanumérico + underscore. O prefixo `@` é aceito e removido.
`phoneNumber`	string (E.164)	sim	Deve ser um dos seus telefones verificados.

Resposta

json

{
  "xUsername": "elonmusk",
  "xUserId": "44196397",
  "xDisplayName": "Elon Musk",
  "xProfileImage": "https://pbs.twimg.com/...",
  "phoneNumber": "+5511987654321",
  "isActive": true,
  "createdAt": 1745000000000
}

Erros

400 "invalid X username format" — falha na regex
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — veja a tabela de planos abaixo
404 "X account not found" — o nome de usuário não existe no X

Limites por plano

Plano	Assinaturas
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Listar suas assinaturas

GET /subscriptions

Resposta

json

{
  "subscriptions": [ /* mesma estrutura da resposta de POST /subscriptions */ ],
  "count": 3
}

Excluir uma assinatura

DELETE /subscriptions/{xUsername}

Correspondência insensível a maiúsculas/minúsculas em xUsername. Remova o @ antes de enviar.

Resposta

json

{ "success": true }

Notifications

Todo alerta entregue pelo WallaWhats é registrado aqui, junto com seu status de entrega no WhatsApp.

Listar notificações

GET /notifications

Parâmetros de consulta

Parâmetro	Tipo	Descrição
`from`	number (epoch ms)	Filtra notificações criadas em ou após esse instante
`to`	number (epoch ms)	Filtra notificações criadas em ou antes desse instante
`lastKey`	string	Cursor de paginação retornado pela resposta anterior

Resposta

json

{
  "notifications": [
    {
      "notificationId": "a1b2c3d4-...",
      "userId": "5a4cbd70-...",
      "phoneNumber": "+5511987654321",
      "xUsername": "elonmusk",
      "tweetId": "1797123456789000000",
      "tweetText": "...",
      "tweetUrl": "https://x.com/elonmusk/status/...",
      "waMessageId": "wamid.HBgN...",
      "status": "delivered",
      "errorMessage": null,
      "createdAt": 1745000000000,
      "updatedAt": 1745000002000
    }
  ],
  "lastKey": "eyJOT1RJRklDQVRJT05fSUQi..."
}

Valores possíveis de status: queued, sent, delivered, read, failed.

O tamanho de página é 50. Quando lastKey está ausente, você chegou ao final.

API keys

Gerencie as chaves que seus aplicativos usam para chamar esta API.

Criar uma API key

POST /apikeys

Requisição

Campo	Tipo	Obrigatório
`name`	string	não, padrão `"Default"`

Resposta (201 Created)

json

{
  "apiKey": "bws_prod_00000000000000000000000000000000",
  "keyPrefix": "bws_prod_00",
  "keyName": "CI server",
  "createdAt": 1745000000000,
  "expiresAt": 1776536000000
}

Valor exibido apenas uma vez

apiKey é retornada somente na criação. Guarde-a no seu gerenciador de segredos imediatamente. Chamadas posteriores só expõem o keyPrefix.

Listar suas API keys

GET /apikeys

Resposta

json

[
  {
    "keyPrefix": "bws_prod_00",
    "keyName": "CI server",
    "createdAt": 1745000000000,
    "lastUsedAt": 1745086400000,
    "expiresAt": 1776536000000
  }
]

Excluir uma API key

DELETE /apikeys/{keyPrefix}

Use o keyPrefix de 12 caracteres da resposta da listagem — nunca a chave completa.

Resposta

json

{ "success": true }

Início rápido

bash

# 1. Crie uma chave no painel e exporte-a
export WALLA_API_KEY="bws_prod_..."

# 2. Cadastre e verifique seu número de WhatsApp
curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+5511987654321","displayName":"Mobile"}'
# -> o telefone recebe um código no WhatsApp. Envie-o:
curl -X POST https://api.wallawhats.com/phones/verify \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+5511987654321","code":"123456"}'

# 3. Assine uma conta do X
curl -X POST https://api.wallawhats.com/subscriptions \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xUsername":"elonmusk","phoneNumber":"+5511987654321"}'

# 4. Veja os alertas chegando
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

É isso — assim que a conta do X publicar, o alerta chega ao telefone em uns 10 segundos.

Suporte

Dúvidas sobre a API, relatos de bugs ou pedidos de aumento de cota: abra um chamado na aba Support do seu painel, ou escreva para hello@support.wallawhats.com.

Referência da API ​

Autenticação ​

Escopo e expiração ​

Limite de chaves por plano ​

Erros ​

Limites de taxa ​

User ​

Obter seu perfil ​

Phones ​

Cadastrar um telefone ​

Verificar um telefone ​

Listar seus telefones ​

Excluir um telefone ​

Subscriptions ​

Criar uma assinatura ​

Listar suas assinaturas ​

Excluir uma assinatura ​

Notifications ​

Listar notificações ​

API keys ​

Criar uma API key ​

Listar suas API keys ​

Excluir uma API key ​

Início rápido ​

Suporte ​

Referência da API

Autenticação

Escopo e expiração

Limite de chaves por plano

Erros

Limites de taxa

User

Obter seu perfil

Phones

Cadastrar um telefone

Verificar um telefone

Listar seus telefones

Excluir um telefone

Subscriptions

Criar uma assinatura

Listar suas assinaturas

Excluir uma assinatura

Notifications

Listar notificações

API keys

Criar uma API key

Listar suas API keys

Excluir uma API key

Início rápido

Suporte