Questo servizio utilizza la funzionalità dei dispositivi collegati di WhatsApp e non l’API Business ufficiale di WhatsApp; questa modalità di connessione dell’account non è supportata ufficialmente da WhatsApp. Modifiche al protocollo, revoca del dispositivo o limitazioni dell’account possono causare interruzioni. Collega solo account di tua proprietà, rispetta i termini di WhatsApp e non utilizzarlo per messaggi indesiderati o invii di massa senza consenso.
Distribuzione e autorizzazione personale
- Crea l’applicazione «Proxy dell’account WhatsApp» nella console, attiva l’abbonamento e fai clic su distribuisci. Le risorse dell’istanza vengono configurate automaticamente dalla piattaforma.
- Quando l’istanza è pronta, visualizza il codice QR nella pagina di gestione. Apri WhatsApp sul tuo telefono Impostazioni → Dispositivi collegati → Collega un dispositivo e scansiona il codice. Puoi anche inserire il tuo numero di telefono per richiedere un codice di associazione, quindi confermare sul telefono.
- Dopo che lo stato nella pagina di gestione diventa «Connesso», copia l’indirizzo MCP esclusivo e il token di accesso Bearer.
- La disconnessione dall’account tenterà di revocare il dispositivo collegato e di cancellare la sessione locale e la cronologia. Se il risultato della disconnessione è incerto, revoca prima il dispositivo in «Dispositivi collegati» sul telefono; la distruzione dell’istanza rimuoverà il suo volume persistente.
Autenticazione e funzionalità
Ad eccezione di/health e /readyz, le interfacce REST, MCP, di scansione del codice e di associazione richiedono tutte Authorization: Bearer <token di accesso>. Inserisci il token solo nell’intestazione della richiesta, non nell’URL o nei log. GET /api/capabilities mostra le operazioni effettivamente supportate dall’istanza corrente e i limiti di conservazione.
Attualmente sono supportati: stato dell’account e della connessione, conversazioni e contatti sincronizzati con il dispositivo collegato, eventi di messaggi in tempo reale, lettura dei messaggi conservati localmente, invio e ricezione di testo e contenuti multimediali fino a 10 MiB, risposte con citazione, reazioni emoji, contrassegno come letto, nonché modifica/revoca dei propri messaggi, informazioni sui gruppi e operazioni su singoli membri consentite dalle autorizzazioni dell’account e dalle regole correnti di WhatsApp. Le modifiche ai gruppi vengono comunque verificate da WhatsApp in base alle autorizzazioni dei membri e degli amministratori.
Ambito della cronologia: possono essere letti solo i messaggi effettivamente sincronizzati dal telefono con il dispositivo collegato e i messaggi ricevuti mentre il proxy è online. Non è possibile garantire l’ottenimento di tutti i vecchi messaggi; localmente vengono conservati al massimo gli ultimi 5.000 messaggi e 2.000 eventi. Quando sono presenti metadati multimediali, il contenuto multimediale originale potrebbe comunque non essere più scaricabile.
MCP
La pagina di gestione della distribuzione forniscehttps://whatsapp-bot-<ID istanza>.app.acedata.cloud/mcp. Configura questo indirizzo in un client MCP che supporti Streamable HTTP e intestazioni di richiesta personalizzate, quindi aggiungi lo stesso token Bearer. Gli strumenti MCP includono whatsapp_capabilities, whatsapp_whoami, whatsapp_chats, whatsapp_contacts, whatsapp_messages, whatsapp_events, whatsapp_send, whatsapp_send_status, whatsapp_media, whatsapp_mark_read, whatsapp_group e whatsapp_group_update.
L’Agent può leggere i messaggi in base alle proprie attività; prima di inviare messaggi a terzi, modificare messaggi o apportare modifiche ai gruppi, deve fare confermare all’utente il destinatario e il contenuto specifici. La configurazione di MCP non attiverà autonomamente alcun invio.
Esempi REST
target deve utilizzare il JID restituito da /api/chats o /api/contacts; non è possibile utilizzare numeri di telefono arbitrari per invii a freddo. Fai prima confermare al titolare dell’account il destinatario e il contenuto.
action può essere text, media, edit, revoke o reaction. Per l’invio di contenuti multimediali, passa media_base64 e mime_type; per rispondere, passa reply_to; per modificare e revocare, passa il proprio message_id rintracciabile localmente; per reagire, passa message_id e emoji. È possibile scaricare i contenuti multimediali tramite GET /api/chats/{target}/messages/{id}/media e contrassegnare come letto tramite POST /api/chats/{target}/read.
L’invio deve includere una Idempotency-Key di 8–128 caratteri. Il message_id restituito è fisso e lo stato può essere pending, accepted, unknown, delivered o read. accepted indica solo che la connessione locale ha accettato l’invio, non che il destinatario lo abbia ricevuto. Quando si verifica unknown, consulta GET /api/sends/{Idempotency-Key} e gli eventi dei messaggi; non utilizzare una nuova chiave per inviare nuovamente lo stesso messaggio, per evitare duplicati. Il proxy non ritenterà automaticamente le operazioni incerte.
I record di invio non vengono eliminati automaticamente; dopo aver raggiunto 100.000 record, l’istanza rifiuta nuovi invii (HTTP 507), evitando invii duplicati dopo la pulizia delle vecchie chiavi di idempotenza.
Eventi in tempo reale
GET /api/events?after=<ultimo next_cursor>&wait_ms=25000 supporta il long polling fino a 25 secondi; GET /api/events/stream?after=<cursore> fornisce SSE. Gli eventi contengono un seq monotonicamente crescente. Il next_cursor nella risposta deve essere salvato nello stato persistente dell’Agent; se gap=true, significa che i vecchi eventi sono stati eliminati, pertanto occorre recuperare nuovamente lo stato attuale delle conversazioni e continuare da oldest_cursor. Gli eventi dei messaggi, lo stato di invio e lo stato della connessione vengono riportati separatamente.
Stati comuni
Non è garantita una cronologia illimitata, la disponibilità a lungo termine di tutti i contenuti multimediali o che tutte le operazioni sui gruppi vengano sempre accettate da WhatsApp. Quando devi controllare un’istanza specifica, consulta prima
/api/auth/status e /api/capabilities.