Riferimento API

L'API REST di WallaWhats ti permette di gestire telefoni, iscrizioni ad account X e cronologia delle notifiche in modo programmatico — esattamente ciò che faresti altrimenti dalla dashboard.

URL base: https://api.wallawhats.com
Content-Type: application/json
Autenticazione: chiave API (header)
Versioning: l'API è stabile. Le modifiche retrocompatibili vengono annunciate con 30 giorni di anticipo via email a ogni account.

Autenticazione

Ogni richiesta deve includere una chiave API nell'header x-api-key:

bash

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

Le chiavi si creano nella dashboard in Settings → API Keys oppure tramite POST /apikeys. Un prefisso di chiave inizia con bws_ ed è lungo 36 caratteri. Le chiavi vengono mostrate una sola volta, alla creazione — se ne perdi una, eliminala e creane una nuova.

Ambito e scadenza

Una chiave si autentica come l'utente che l'ha creata. Ha gli stessi permessi di quell'utente e conta sulle stesse quote del piano.
Le chiavi sono valide 365 giorni. Per la rotazione: crea una nuova chiave, passa a quella nuova ed elimina la vecchia.
Chiavi mancanti, malformate o revocate restituiscono 401 Unauthorized.

Limiti di chiavi per piano

Piano	Chiavi consentite
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	20

Il tentativo di crearne più di quante consentite dal tuo piano restituisce 400 con "error": "api key limit reached".

Errori

Gli errori vengono restituiti in JSON con un campo error e un codice di stato HTTP:

json

{ "error": "phoneNumber is required" }

Stato	Significato
`400`	Parametri non validi, quota superata o violazione di regola di business
`401`	Chiave API mancante o non valida
`402`	Credito insufficiente per completare l'operazione
`404`	Risorsa non trovata
`500`	Errore server — riprova con backoff esponenziale

Limiti di velocità

Predefinito: 20 richieste/secondo per chiave API, con burst fino a 40.
Gli endpoint di listing restituiscono fino a 50 elementi per pagina; usa il cursore lastKey per paginare.
Le regole WAF possono restituire 403 su pattern abusivi. Contatta il supporto se sei limitato in modo inatteso.

Utente

Ottieni il tuo profilo

GET /user/profile

Restituisce il profilo dell'utente autenticato.

Risposta

json

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

Esempio

bash

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

Telefoni

Un telefono è un numero WhatsApp verificato che può ricevere avvisi. Devi verificare un telefono prima di iscrivervi un account X.

Registra un telefono

POST /phones

Genera un codice a 6 cifre e lo invia al numero tramite WhatsApp. Il telefono viene creato in stato pending_verification.

Richiesta

Campo	Tipo	Obbligatorio	Note
`phoneNumber`	string	sì	Formato E.164, ad es. `+34612345678`
`displayName`	string	no	Etichetta descrittiva mostrata nella dashboard

Risposta

json

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

Errori

400 "invalid phone number format" — non è in formato E.164
400 "phone number limit reached" — supera il limite del piano (Free/Pro/Pro+ 1, Business 3, Enterprise 10)

Esempio

bash

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

Verifica un telefono

POST /phones/verify

Conferma un telefono inviando il codice a 6 cifre. I codici scadono dopo 15 minuti.

Richiesta

Campo	Tipo	Obbligatorio
`phoneNumber`	string (E.164)	sì
`code`	string (6 cifre)	sì

Risposta

json

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

Errori

404 "phone not found"
400 "invalid code" — codice errato
400 "code expired" — più di 15 minuti
400 "phone already verified"

Elenca i tuoi telefoni

GET /phones

Risposta

json

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

Elimina un telefono

DELETE /phones/{phoneNumber}

Rimuove il telefono e disattiva le iscrizioni che lo avevano come destinazione. Codifica il + come %2B nell'URL.

Risposta

json

{ "success": true }

Esempio

bash

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

Iscrizioni

Un'iscrizione lega un account X che vuoi monitorare a uno dei tuoi telefoni verificati. Quando l'account X pubblica, WallaWhats invia un avviso WhatsApp a quel telefono.

Crea un'iscrizione

POST /subscriptions

Richiesta

Campo	Tipo	Obbligatorio	Note
`xUsername`	string	sì	1–15 caratteri, alfanumerici + underscore. Il prefisso `@` è accettato e rimosso.
`phoneNumber`	string (E.164)	sì	Deve essere uno dei tuoi telefoni verificati.

Risposta

json

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

Errori

400 "invalid X username format" — fallimento della regex
400 "phone not found" / "phone not verified"
400 "subscription limit reached" — vedi la tabella dei piani sotto
404 "X account not found" — lo username non si risolve su X

Limiti per piano

Piano	Iscrizioni
Free	1
Pro	1
Pro+	2
Business	5
Enterprise	50

Elenca le tue iscrizioni

GET /subscriptions

Risposta

json

{
  "subscriptions": [ /* stessa forma della risposta POST /subscriptions */ ],
  "count": 3
}

Elimina un'iscrizione

DELETE /subscriptions/{xUsername}

Corrispondenza case-insensitive su xUsername. Rimuovi la @ prima di inviarla.

Risposta

json

{ "success": true }

Notifiche

Ogni avviso consegnato da WallaWhats viene registrato qui, insieme allo stato di consegna WhatsApp.

Elenca le notifiche

GET /notifications

Parametri query

Parametro	Tipo	Descrizione
`from`	number (ms epoch)	Filtra le notifiche create a partire da questa data
`to`	number (ms epoch)	Filtra le notifiche create fino a questa data
`lastKey`	string	Cursore di paginazione restituito dalla risposta precedente

Risposta

json

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

Valori possibili di status: queued, sent, delivered, read, failed.

La dimensione di pagina è 50. Quando lastKey è assente, hai raggiunto la fine.

Chiavi API

Gestisci le chiavi che le tue applicazioni usano per chiamare questa API.

Crea una chiave API

POST /apikeys

Richiesta

Campo	Tipo	Obbligatorio
`name`	string	no, predefinito `"Default"`

Risposta (201 Created)

json

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

Valore mostrato una sola volta

apiKey viene restituita solo alla creazione. Salvala subito nel tuo secrets manager. Le chiamate successive espongono solo il keyPrefix.

Elenca le tue chiavi API

GET /apikeys

Risposta

json

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

Elimina una chiave API

DELETE /apikeys/{keyPrefix}

Usa il keyPrefix di 12 caratteri della risposta di listing — mai la chiave completa.

Risposta

json

{ "success": true }

Avvio rapido

bash

# 1. Crea una chiave nella dashboard ed esportala
export WALLA_API_KEY="bws_prod_..."

# 2. Registra + verifica il tuo numero WhatsApp
curl -X POST https://api.wallawhats.com/phones \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+34612345678","displayName":"Mobile"}'
# -> il telefono riceve un codice WhatsApp. Invialo:
curl -X POST https://api.wallawhats.com/phones/verify \
  -H "x-api-key: $WALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+34612345678","code":"123456"}'

# 3. Iscriviti a un account 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":"+34612345678"}'

# 4. Guarda arrivare gli avvisi
curl https://api.wallawhats.com/notifications \
  -H "x-api-key: $WALLA_API_KEY"

Ecco fatto — non appena l'account X pubblica, l'avviso arriva sul telefono in circa 10 secondi.

Supporto

Domande sull'API, segnalazioni di bug o richieste di aumento quota: apri un ticket dalla scheda Support della dashboard, oppure scrivi a hello@support.wallawhats.com.

Riferimento API ​

Autenticazione ​

Ambito e scadenza ​

Limiti di chiavi per piano ​

Errori ​

Limiti di velocità ​

Utente ​

Ottieni il tuo profilo ​

Telefoni ​

Registra un telefono ​

Verifica un telefono ​

Elenca i tuoi telefoni ​

Elimina un telefono ​

Iscrizioni ​

Crea un'iscrizione ​

Elenca le tue iscrizioni ​

Elimina un'iscrizione ​

Notifiche ​

Elenca le notifiche ​

Chiavi API ​

Crea una chiave API ​

Elenca le tue chiavi API ​

Elimina una chiave API ​

Avvio rapido ​

Supporto ​

Riferimento API

Autenticazione

Ambito e scadenza

Limiti di chiavi per piano

Errori

Limiti di velocità

Utente

Ottieni il tuo profilo

Telefoni

Registra un telefono

Verifica un telefono

Elenca i tuoi telefoni

Elimina un telefono

Iscrizioni

Crea un'iscrizione

Elenca le tue iscrizioni

Elimina un'iscrizione

Notifiche

Elenca le notifiche

Chiavi API

Crea una chiave API

Elenca le tue chiavi API

Elimina una chiave API

Avvio rapido

Supporto