REST API

L’API di Walink permette a uno script, a un backend o a qualsiasi strumento no-code che invia richieste HTTP di fare ciò che fai tu nell’app. Ogni richiesta passa per le regole dell’app, quindi indirizzi, quota e proprietà vengono controllati allo stesso modo, e ogni creazione produce una bozza, tranne nel caso di un link gratis, così nulla va online per sbaglio.

Questa pagina ti porta fino alla prima chiamata. Ogni endpoint e ogni campo sono nel riferimento completo dell’API, che ha anche una console per provare le richieste.

Cosa puoi automatizzare

Qualsiasi account Walink può usare l’API. Le bozze sono gratis. Pubblicare usa la quota del tuo abbonamento e le statistiche richiedono un abbonamento, come nell’app.

Crea un token

1. Accedi a Walink, apri il menu dell’account (il pulsante rotondo in alto a destra) e seleziona Developers (sviluppatori).
2. In API Tokens, seleziona Create token (crea token).
3. Dagli un Name (nome), come "Script dei report", e scegli la scadenza in Expires after (scade dopo): 30 days, 90 days, 1 year (il valore predefinito) o No expiration (nessuna scadenza).
4. In Scopes (ambiti), spunta solo ciò che serve al token. Quick presets (preimpostazioni rapide) compila Read only (sola lettura) o Full access (accesso completo). Gli ambiti non si possono cambiare in seguito.
5. Seleziona Create token. La finestra Save your token (salva il tuo token) lo mostra una sola volta: copialo in un posto sicuro, come un gestore di password, poi seleziona I've saved it (l’ho salvato).

I token iniziano con wlk_live_, e un account può avere 25 token attivi. Nella tabella dei token, Rotate (ruota) ti dà un nuovo token con lo stesso nome e gli stessi ambiti, mentre quello vecchio continua a funzionare per 7 giorni. Revoke (revoca) blocca un token definitivamente, entro 30 secondi.

Ambiti

write include read. Niente include publish, delete o responses:read: ognuno viene concesso a parte, e nessuno è attivo di default.

analytics:read e multilinks:read mostrano anche i nomi dei tuoi link, Smart Links e moduli pubblicati, anche senza il rispettivo ambito di lettura.

La tua prima richiesta

L’URL di base è https://api.walink.com/v1. Invia il token come Authorization: Bearer <token> e i corpi delle richieste in JSON. Gli esempi leggono il token da una variabile d’ambiente WALINK_API_TOKEN, così resta fuori dal tuo codice.

Elenca i tuoi Link Premium (richiede links:read):

curl https://api.walink.com/v1/links \
  -H "Authorization: Bearer $WALINK_API_TOKEN"

{
	"data": [
		{
			"id": "lnk_3f2a9c1e-7b4d-4e8a-9f10-2c6d8e4b1a77",
			"title": "Tienda Luna orders",
			"handle": "tienda-luna",
			"plan": "chat",
			"status": "published",
			"url": "https://wa.link/tienda-luna",
			"created_at": "2026-11-05T14:32:07.000Z",
			"updated_at": "2026-11-05T14:32:07.000Z"
		}
	],
	"has_more": false,
	"next_cursor": null
}

Gli elenchi partono dal più recente. Accettano limit (25 di default, 100 al massimo) e cursor: passa next_cursor per avere la pagina successiva.

Crea una bozza

Una creazione produce sempre una bozza (richiede links:write). Questa apre una chat con un numero statunitense:

curl -X POST https://api.walink.com/v1/links \
  -H "Authorization: Bearer $WALINK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tienda-luna-promo-1" \
  -d '{
    "handle": "tienda-luna-promo",
    "plan": "chat",
    "title": "Tienda Luna promo",
    "phone": "4155550123",
    "country_code": "1",
    "country_alpha": "US",
    "message": "Hello Tienda Luna, I saw your promo"
  }'

La risposta è 201 col record completo, il suo id e "status": "draft".

• handle è l’indirizzo dopo wa.link/. Non si può cambiare dopo la creazione del link, e una bozza non lo blocca: lo ottiene il primo account che pubblica con quell’indirizzo.
• plan è il tipo di link: chat, catalog, channel o group.
• Idempotency-Key rende sicuro un nuovo tentativo per 24 ore: la stessa chiave e lo stesso corpo restituiscono la prima risposta invece di una seconda bozza.

Pubblica

La pubblicazione è una chiamata a parte, e richiede links:publish:

curl -X POST https://api.walink.com/v1/links/lnk_3f2a9c1e-7b4d-4e8a-9f10-2c6d8e4b1a77/publish \
  -H "Authorization: Bearer $WALINK_API_TOKEN"

Come Publish nell’app, usa un’unità della tua quota di Link Premium ($9 USD all’anno per link). Senza un’unità libera la risposta è 402 pool_exhausted, coi numeri in details. Aggiungi quota nella pagina Billing dell’app (come funziona la fatturazione).

• POST .../publish-check è una prova a vuoto: cosa blocca ancora la pubblicazione e quanta quota userebbe.
• POST .../unpublish mette offline il link e libera la sua unità. Il suo indirizzo smette di funzionare, codici QR stampati compresi, e a quel punto un altro account può prenderlo.
• PATCH /v1/links/{id} cambia solo i campi che invii. In un link pubblicato la modifica è subito online, quindi richiede anche links:publish.

Smart Links, moduli e pagine Multilink seguono gli stessi passaggi coi propri percorsi. Gli Smart Links usano gli ambiti links.

Link gratis nell’API

/v1/free-links crea i link gratis che ogni account può avere, fino a 5. Funzionano in modo diverso:

• Un link gratis è online dal momento in cui viene creato, mai una bozza. Per questo crearne uno richiede links:publish, non links:write.
• Walink sceglie il suo indirizzo casuale. Tu invii un numero di telefono o un nome utente WhatsApp, un messaggio facoltativo e un title privato facoltativo, che non si può cambiare in seguito.
• Si può elencare, leggere ed eliminare, mai modificare. Il suo id inizia con fln_, e /v1/links non lo mostra mai.
• Per modificarlo o vedere le sue statistiche bisogna passarlo a Premium nell’app, e questo cambia il suo id in lnk_.

Se ne hai già 5, una creazione risponde 409 free_link_limit_reached, ed eliminarne uno libera il suo posto. Maggiori dettagli in link gratis.

Errori e limiti di frequenza

Ogni errore ha la stessa forma:

{
	"error": {
		"code": "insufficient_scope",
		"message": "This token needs the links:publish scope.",
		"param": null,
		"doc_url": "https://api.walink.com/docs#description/errors",
		"request_id": "req_4f1c9a0b7d2e4c8f9a1b3c5d7e9f0a2b",
		"details": { "required": ["links:publish"] }
	}
}

I limiti sono approssimativi, ed esaurire la quota non dà mai un 429. Tramite l’API, un account può avere fino a 500 bozze per prodotto. Ogni risposta ha un’intestazione Request-Id: citala quando contatti l’assistenza.

Riferimento completo

• Riferimento dell’API: ogni endpoint e ogni campo, con una console.
• Documento OpenAPI 3.1 ed enum e limiti, senza bisogno di un token.
• llms.txt: le regole dell’API, per gli strumenti di IA.

Lo stesso token collega anche gli assistenti IA: vedi Collegare gli assistenti IA.