Come creare un AI companion su WhatsApp: guida 2026

Per lanciare un AI companion su WhatsApp, usa un numero WhatsApp personale, perché l’API Business di Meta esclude gli assistenti AI generalisti nella maggior parte dei mercati. Dai al numero un personaggio nel profilo, offri agli utenti un link per scriverti per primi, rispondi a ogni messaggio da un webhook con una memoria che gestisci tu e prevedi le regole di sicurezza fin dal primo giorno.

Perché creare un companion su WhatsApp, ed è consentito?

Un companion vive o muore in base a quante volte le persone aprono la conversazione. Più di 3 miliardi di persone usano WhatsApp ogni mese, secondo la call sugli utili del primo trimestre 2025 di Meta, riportata da TechCrunch, e il tuo companion arriva come un contatto in un’app che aprono già ogni giorno. Niente installazione, niente scheda sullo store, nessun nuovo permesso per le notifiche. Il discorso completo, con i numeri, ha un articolo tutto suo.

Il problema sono le regole. I termini di WhatsApp Business di Meta, in vigore dal 15 gennaio 2026, vietano gli «AI provider» sulla Business Platform quando l’AI è la funzione principale. La pagina dei prezzi di Meta li definisce come sviluppatori di modelli linguistici, piattaforme di AI generativa e assistenti generalisti. Un companion è l’AI stessa, quindi a nostro avviso rientra nel divieto.

Secondo la pagina di Meta, gli AI provider sono ammessi solo nei mercati in cui la legge lo impone: Italia, Brasile, altri 29 Paesi europei e, dal 15 ottobre 2026, la Turchia. Anche lì i messaggi di servizio si possono inviare solo in risposta agli utenti, dentro una finestra di 24 ore aperta. La pagina non elenca Stati Uniti, Regno Unito, India o Messico. La regola di gennaio 2026 nel dettaglio ha la cronologia.

Resta il numero WhatsApp personale. Puoi gestirne uno tu con una libreria open source (numero, telefono e rischio di ban sono tuoi) oppure usarne uno gestito. Nel resto della guida usiamo whasp, che gestisce il numero su un telefono cloud e ti dà un webhook e una chiamata per inviare.

Come configuri il personaggio e il numero?

Un numero whasp è un unico account WhatsApp reale, quindi porta un solo personaggio: un nome, una riga «info» e una foto. Il nome può arrivare a 25 caratteri e le info a 139, per ora solo ASCII semplice. Il profilo è la prima cosa che vede l’utente, quindi dichiara lì che è un’AI.

curl https://api.whasp.ai/v1/numbers \
  -H "Authorization: Bearer $WHASP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "ava",
    "profile": {
      "name": "Ava",
      "about": "Amica AI. Scrivimi quando vuoi.",
      "photo_url": "https://example.com/ava.jpg"
    }
  }'

Questa chiamata addebita $49. Il numero torna come active (il caso normale) o provisioning, che richiede circa 30 minuti e finisce con un evento number.ready. Poi indica a whasp il tuo server. La risposta contiene il secret di firma, whsec_..., creato una sola volta e poi conservato.

curl -X PUT https://api.whasp.ai/v1/webhook \
  -H "Authorization: Bearer $WHASP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://companion.example.com/whasp" }'

Con più personaggi servono più numeri, uno per profilo.

Come fanno gli utenti a iniziare una chat con il companion?

Gli utenti avviano la chat da soli. Un numero whasp non può aprire una conversazione: un invio a qualcuno che non ha mai scritto restituisce 409 chat_not_open. Quindi il primo contatto avviene nel tuo prodotto. Dopo la registrazione, mostra un pulsante che apre WhatsApp con il messaggio già scritto.

GET /v1/numbers/pick restituisce il numero in salute con più spazio e un wa_link. Metti un codice della registrazione nel testo precompilato, e il primo messaggio in entrata ti dice di chi è quel telefono.

// Chiamata quando un utente autenticato tocca «Parla con Ava» nella tua app.
export async function chatLink(code: string): Promise<string> {
  const text = encodeURIComponent(`Ciao Ava, il mio codice è ${code}`);
  const res = await fetch(`https://api.whasp.ai/v1/numbers/pick?text=${text}`, {
    headers: { Authorization: `Bearer ${process.env.WHASP_API_KEY}` },
  });
  if (res.ok) {
    const { wa_link } = await res.json();
    return wa_link;
  }
  throw new Error(`pick failed with ${res.status}`); // 409 no_capacity: aggiungi un numero
}

Controlla l’età e fai accettare i tuoi termini prima di mostrare il link. Se un telefono sconosciuto scrive senza codice, rispondi una volta con un link per registrarsi.

Come fa il companion a rispondere, ricordare e sembrare umano?

Il companion risponde da un webhook. Ogni messaggio in entrata arriva in un evento message.received, firmato secondo Standard Webhooks. Verificalo, rispondi 2xx subito, poi fai il lavoro lento: carica la memoria, chiama il tuo modello, invia la risposta.

import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";

declare function linkPhoneToAccount(phone: string, code: string): Promise<void>;
declare function companionReply(chat: string, text: string): Promise<string[]>; // memoria + modello

const wh = new Webhook(process.env.WHASP_WEBHOOK_SECRET ?? ""); // whsec_...
const handled = new Set<string>(); // in produzione usa una tabella del database

async function send(to: string, text: string, key: string) {
  const res = await fetch("https://api.whasp.ai/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WHASP_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": key,
    },
    body: JSON.stringify({ to, text }),
  });
  if (res.ok) return;
  console.error("send failed", res.status, await res.text());
}

async function handle(event: any) {
  const { chat, text } = event.data.message;
  const code = text?.match(/il mio codice è (\w+)/i)?.[1];
  if (code) await linkPhoneToAccount(chat, code);

  const parts = await companionReply(chat, text ?? "");
  for (const [i, part] of parts.entries()) await send(chat, part, `${event.id}:${i}`);
}

createServer(async (req, res) => {
  req.setEncoding("utf8");
  let body = "";
  for await (const chunk of req) body += chunk;

  let event: any;
  try {
    event = wh.verify(body, req.headers as Record<string, string>);
  } catch {
    res.writeHead(401).end();
    return;
  }
  res.writeHead(204).end(); // prima conferma, poi lavora

  const duplicate = handled.has(event.id);
  handled.add(event.id);
  if (event.type === "message.received" && duplicate === false) await handle(event);
}).listen(3000);

Usare l’id dell’evento nell’Idempotency-Key fa sì che un evento ritentato non invii mai due volte. Gli eventi possono arrivare due volte o fuori ordine, da qui il controllo handled.

La memoria è tua. I server di whasp non conservano i messaggi: il contenuto di un messaggio in entrata ti arriva una sola volta, in questo evento. Salva gli ultimi scambi, un riassunto aggiornato e una breve lista di fatti (nome, lavoro, persone, progetti). È questo che permette ad Ava di dire «Com’è andata venerdì?» tre settimane dopo. La memoria della conversazione copre lo schema e i budget di token.

Il tono è da chat, non da saggio. Spezza una risposta in due o tre messaggi brevi, fai una domanda alla volta e rinuncia al Markdown. whasp invia da un numero un messaggio alla volta, a circa un secondo di distanza, quindi il ritmo è già incluso. Il prompt per WhatsApp ha un modello di system prompt.

Maya: È andata benissimo, ho preso il lavoro.

Ava: Maya, che notizia enorme. Congratulazioni.

Ava: Settimana scorsa temevi il secondo colloquio. Alla fine che cosa ti hanno chiesto?

Un numero è un telefono usato come lo userebbe una persona, quindi alcune cose mancano: indicatori di scrittura, conferme di lettura, messaggi vocali in uscita, gruppi e risposte a un messaggio specifico. Un messaggio vocale inviato da un utente arriva come file audio che puoi trascrivere.

Quali regole di sicurezza e di età deve avere un companion al lancio?

Un companion ha bisogno delle sue regole di sicurezza prima del primo utente, perché prima o poi incontrerà una persona in difficoltà. Su WhatsApp contano quattro cose.

1. Dichiara che è un’AI. Scrivilo nelle info del profilo e nel primo messaggio. La SB 243 della California, firmata a ottobre 2025, obbliga chi gestisce chatbot companion a dire chiaramente che il chatbot è un’AI ogni volta che una persona ragionevole potrebbe credere di parlare con un essere umano, e sempre agli utenti che sa essere minorenni.
2. Verifica l’età prima del link. I Termini di servizio di WhatsApp fissano un minimo di 13 anni, o più dove lo richiede la legge locale. whasp non può verificare l’età. Tu sì, alla registrazione, prima di mostrare il link. Lo stesso riepilogo sulla California aggiunge promemoria di pausa per i minori e il divieto di mostrare loro immagini sessualmente esplicite.
3. Gestisci l’autolesionismo. La SB 243 richiede anche protocolli per l’ideazione suicidaria. Rilevala, esci dal gioco di ruolo e indica una linea di aiuto del Paese dell’utente. Il prefisso internazionale del numero in chat ti dice quale.
4. Rispetta lo STOP. Un STOP, UNSUBSCRIBE, OPTOUT, CANCEL, END, QUIT in entrata, o qualsiasi grafia di «opt out», disiscrive la chat in automatico, e gli invii restituiscono 403 chat_opted_out finché l’utente non riscrive. Le richieste gentili («per favore smettila») spetta a te intercettarle. Manda una sola conferma con "override_optout": true.

Le regole di sicurezza per gli AI companion nel 2026 trasformano le leggi in una checklist. Non è una consulenza legale.

Come far tornare gli utenti senza messaggi a freddo?

Su un numero che non può scrivere per primo, la retention nasce da tre fonti, e nessuna è un messaggio a freddo.

Questioni in sospeso nella conversazione. Chiudi la sessione su qualcosa che ha un seguito: il colloquio di venerdì, il libro appena iniziato, la discussione che vogliono chiarire. Salvalo. Quando l’utente riscrive, la prima risposta di Ava lo riprende. Le persone tornano per finire una storia.

Canali che controlli tu. La tua app, un’email o una notifica push possono portare lo stesso wa_link con un testo precompilato tipo «Ciao Ava, sono Maya». L’utente tocca e scrive per primo, quindi non c’è nessun messaggio a freddo. Raccogli un’email alla registrazione, per questo e per il caso del ban descritto sotto.

Richieste fatte dentro la chat. Se Maya scrive «venerdì sera chiedimi come sto», il tuo sistema può inviare quel messaggio più tardi. whasp accetta l’invio a chiunque abbia scritto al numero e rifiuta tutti gli altri. Tieni questi messaggi pochi, specifici e chiaramente richiesti. Non costruire il prodotto su messaggi che nessuno ha chiesto.

Non promettere mai agli utenti che il companion «ti scrive per primo». Non può, e i casi d’uso che funzionano meglio partono tutti dall’utente.

Come monetizzi il companion e come gestisci la crescita?

Fai pagare fuori da WhatsApp. Vendi l’abbonamento sul tuo sito o nella tua app, collega il telefono all’account con il codice di registrazione e controlla il piano nel gestore del webhook. A un telefono che non ha pagato basta una risposta con un link per abbonarsi. whasp non gestisce i pagamenti degli utenti finali.

Sul costo: un numero whasp costa $49 ogni 30 giorni da un saldo prepagato, per circa 100 utenti attivi (persone che hanno scritto negli ultimi 30 giorni). Fa meno di 50 centesimi per utente attivo al mese. Il conto del modello è la voce più grande e meno prevedibile, quindi metti un tetto ai messaggi per utente al giorno.

Ogni numero consente 100 chat attive in 30 giorni, 40 nuove chat in 24 ore e 1.500 messaggi inviati in 24 ore. Un numero oltre l’80% di un limite passa a at_risk; i passaggi tra healthy, at_risk e critical arrivano in eventi number.status_changed. Aggiungi un numero prima di arrivarci: /numbers/pick manda i nuovi utenti a quello con più spazio, e chi torna resta sul suo.

Se WhatsApp banna un numero, whasp lo ritira e ti passa a un sostituto con la stessa etichetta, lo stesso profilo e lo stesso periodo pagato, annunciato da number.replaced. Il nuovo numero parte vuoto e le chat non si spostano. Mandi a ogni utente il nuovo wa_link per email o nell’app, e loro scrivono di nuovo per primi. Il tuo archivio della memoria rende tutto indolore: stesso utente, stessa cronologia.

Cosa fare adesso?

1. Scrivi il personaggio e le regole di sicurezza, in questo ordine.
2. Aggiungi un numero e imposta il webhook. POST /v1/webhook/test verifica il tuo endpoint.
3. Invita cinque persone che conosci e leggi ogni conversazione.
4. Guarda cos’altro funziona bene su WhatsApp prima di aggiungere funzioni.

Il quickstart contiene l’intero flusso e la pagina pricing elenca le opzioni di ricarica.