Referência da API

A API REST do WallaWhats permite gerir telefones, subscrições de contas de X e histórico de notificações de forma programática — exatamente o que farias a partir do painel.

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

Autenticação

Todos os pedidos têm de 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 por bws_ e tem 36 caracteres. As chaves são apresentadas apenas uma vez, na criação — se perderes uma, elimina-a e cria outra.

Âmbito e expiração

Uma chave autentica como o utilizador que a criou. Tem as mesmas permissões desse utilizador e consome as mesmas quotas do plano.
As chaves são válidas durante 365 dias. Faz rotação criando uma nova chave, migrando para ela e eliminando a antiga.
Chaves em falta, mal formatadas ou revogadas devolvem 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 o teu plano permite devolve 400 com "error": "api key limit reached".

Erros

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

json

{ "error": "phoneNumber is required" }

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

Limites de taxa

Por omissão: 20 pedidos/segundo por API key, com burst até 40.
Os endpoints de listagem devolvem até 50 itens por página; usa o cursor lastKey para paginar.
As regras do WAF podem devolver 403 perante padrões abusivos. Se achares que estás a ser limitado sem motivo, contacta o suporte.

User

Obter o teu perfil

GET /user/profile

Devolve o perfil do utilizador 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. Tens de verificar um telefone antes de subscrever nele uma conta de X.

Registar um telefone

POST /phones

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

Pedido

Campo	Tipo	Obrigatório	Notas
`phoneNumber`	string	sim	Formato E.164, por exemplo `+351912345678`
`displayName`	string	não	Etiqueta amigável apresentada no painel

Resposta

json

{ "phoneNumber": "+351912345678", "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": "+351912345678", "displayName": "Work"}'

Verificar um telefone

POST /phones/verify

Confirma um telefone submetendo o código de 6 dígitos. Os códigos expiram ao fim de 15 minutos.

Pedido

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

Resposta

json

{ "phoneNumber": "+351912345678", "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 os teus telefones

GET /phones

Resposta

json

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

Eliminar um telefone

DELETE /phones/{phoneNumber}

Remove o telefone e desativa quaisquer subscrições que o tivessem como destino. Codifica o + no URL como %2B.

Resposta

json

{ "success": true }

Exemplo

bash

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

Subscriptions

Uma subscrição liga uma conta de X que queres monitorizar a um dos teus telefones verificados. Quando a conta de X publica, o WallaWhats envia um alerta de WhatsApp para esse telefone.

Criar uma subscrição

POST /subscriptions

Pedido

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

Resposta

json

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

Erros

400 "invalid X username format" — a regex falha
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — vê a tabela de planos abaixo
404 "X account not found" — o nome de utilizador não existe em X

Limites por plano

Plano	Subscrições
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Listar as tuas subscrições

GET /subscriptions

Resposta

json

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

Eliminar uma subscrição

DELETE /subscriptions/{xUsername}

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

Resposta

json

{ "success": true }

Notifications

Todos os alertas que o WallaWhats entrega ficam registados aqui, juntamente com o respetivo estado 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 este instante
`to`	number (epoch ms)	Filtra notificações criadas em ou antes deste instante
`lastKey`	string	Cursor de paginação devolvido pela resposta anterior

Resposta

json

{
  "notifications": [
    {
      "notificationId": "a1b2c3d4-...",
      "userId": "5a4cbd70-...",
      "phoneNumber": "+351912345678",
      "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 não aparece, chegaste ao fim.

API keys

Gere as chaves que as tuas aplicações usam para chamar esta API.

Criar uma API key

POST /apikeys

Pedido

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

Resposta (201 Created)

json

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

Valor apresentado apenas uma vez

apiKey é devolvida somente na criação. Guarda-a de imediato no teu gestor de segredos. Chamadas subsequentes só expõem o keyPrefix.

Listar as tuas API keys

GET /apikeys

Resposta

json

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

Eliminar uma API key

DELETE /apikeys/{keyPrefix}

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

Resposta

json

{ "success": true }

Início rápido

bash

# 1. Cria uma chave no painel e exporta-a
export WALLA_API_KEY="bws_prod_..."

# 2. Regista e verifica o teu 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":"+351912345678","displayName":"Mobile"}'
# -> o telefone recebe um código no WhatsApp. Envia-o:
curl -X POST https://api.wallawhats.com/phones/verify \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+351912345678","code":"123456"}'

# 3. Subscreve uma conta de 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":"+351912345678"}'

# 4. Vê os alertas a chegar
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Pronto — assim que a conta de X publicar, o alerta chega ao telefone em cerca de 10 segundos.

Suporte

Perguntas sobre a API, relatos de bugs ou pedidos de aumento de quota: abre um pedido de suporte no separador Support do teu painel, ou escreve para hello@support.wallawhats.com.

Referência da API ​

Autenticação ​

Âmbito e expiração ​

Limite de chaves por plano ​

Erros ​

Limites de taxa ​

User ​

Obter o teu perfil ​

Phones ​

Registar um telefone ​

Verificar um telefone ​

Listar os teus telefones ​

Eliminar um telefone ​

Subscriptions ​

Criar uma subscrição ​

Listar as tuas subscrições ​

Eliminar uma subscrição ​

Notifications ​

Listar notificações ​

API keys ​

Criar uma API key ​

Listar as tuas API keys ​

Eliminar uma API key ​

Início rápido ​

Suporte ​

Referência da API

Autenticação

Âmbito e expiração

Limite de chaves por plano

Erros

Limites de taxa

User

Obter o teu perfil

Phones

Registar um telefone

Verificar um telefone

Listar os teus telefones

Eliminar um telefone

Subscriptions

Criar uma subscrição

Listar as tuas subscrições

Eliminar uma subscrição

Notifications

Listar notificações

API keys

Criar uma API key

Listar as tuas API keys

Eliminar uma API key

Início rápido

Suporte