Agente AI su WhatsApp: come farlo scrivere come una persona

Per far scrivere un agente AI su WhatsApp come una persona, dai al suo system prompt quattro regole: messaggi brevi con un pensiero ciascuno, la formattazione propria di WhatsApp al posto del Markdown, al massimo una domanda per turno e parole semplici, senza il solito frasario da assistente. Poi falle rispettare nel codice: converti il Markdown nella sintassi di WhatsApp e dividi la risposta in due o tre messaggi prima di inviarla.

Perché le risposte di un’AI sembrano sbagliate su WhatsApp?

I modelli di chat tendono a rispondere come documenti: un saluto, un elenco in grassetto, un’offerta finale di altro aiuto. In un fumetto di chat sembra una lettera commerciale, e simboli come # arrivano esattamente come sono stati scritti. Le persone scrivono a raffiche brevi, e una risposta che non somiglia a una raffica tradisce l’agente già dal primo messaggio.

La panoramica dei modelli di Anthropic stessa dice agli sviluppatori che vogliono risposte più brevi di chiederle nel prompt, e vale per qualsiasi modello. Prendi un messaggio, «È andata benissimo, ho preso il lavoro», e due risposte possibili:

Congratulazioni per il nuovo incarico. È un'ottima notizia. Ecco alcuni passi da considerare:

**1. Esamina l'offerta nel dettaglio**
**2. Preparati per la prima settimana**

Fammi sapere se posso aiutarti con uno di questi punti.

Maya, che bella notizia. Congratulazioni.

Raccontami tutto. Come te l'hanno detto?

La seconda sono due messaggi, una domanda e nessuna formattazione. La prima è un blocco unico, con Markdown che non fa parte della sintassi documentata da WhatsApp.

Quale formattazione supporta WhatsApp?

La pagina di aiuto di WhatsApp Come formattare i messaggi documenta otto elementi di sintassi, e le versioni per Android, iPhone e Web elencano gli stessi.

Il grassetto usa un solo asterisco, ed è per questo che i **doppi asterischi** e i # titoli che un modello scrive di default vanno convertiti. La pagina non elenca alcuna sintassi per titoli, tabelle o testo dei link, quindi scrivi gli URL in chiaro e trasforma le righe di tabella in righe brevi.

Una precisazione dalla pagina stessa: la sua versione Web segnala che la formattazione più recente è disponibile solo su Web e sul desktop per Mac, mentre le versioni Android e iPhone mostrano la stessa sintassi senza quella nota. Considera elenchi e citazioni un di più. - voce e 1. voce si leggono bene anche come testo semplice dove non vengono resi.

Poche regole evitano che la formattazione sembri un documento. Usa il grassetto su una parola o una frase per messaggio, al massimo. Usa un elenco solo per tre o più elementi paralleli, come i passaggi. Non inviare mai una tabella. Metti un solo link per messaggio: il riferimento sui messaggi di testo di Meta per la sua API business dice che il client WhatsApp genera l’anteprima solo del primo URL nel corpo del testo.

Cosa deve dire il system prompt?

Il system prompt di un agente WhatsApp deve fissare le regole di stile con numeri ed esempi, perché aggettivi come «conciso» e «cordiale» dicono poco a un modello. Questo modello copre il comportamento descritto sopra, e la riga sul personaggio la compili tu:

Sei Ava, e stai scrivendo su WhatsApp con {{name}}. {{una riga: chi sei, come parli}}

Come scrivi:
- Stai mandando messaggi, non scrivendo un'email. Un pensiero per messaggio, da una a tre frasi.
- Al massimo 3 messaggi per turno. Lascia una riga vuota tra un messaggio e l'altro: ogni paragrafo viene inviato come messaggio a sé.
- Adegua lunghezza ed energia a quelle della persona. Se scrive quattro parole, non rispondere con quaranta.
- Fai al massimo una domanda per turno, e solo quando ti serve la risposta. Non chiudere ogni turno con una domanda.
- Usa parole semplici. Niente «Certamente», niente «Spero di esserti stato utile», niente «Come modello linguistico AI».
- Emoji: al massimo una per turno, e solo se le usa anche la persona. Spesso nessuna.

Formattazione (WhatsApp, non Markdown):
- Il grassetto si fa con *un asterisco per lato*. Il corsivo con _trattini bassi_.
- Mai #, tabelle, **doppi asterischi** o link [testo](url). Scrivi l'URL in chiaro.
- Usa un elenco solo per tre o più elementi paralleli, uno per riga, che inizia con "- " o "1. ".
- Un solo link per messaggio, su una riga a parte.

Se la persona manda un messaggio vocale, una foto o un file, ricevi una trascrizione o una descrizione tra parentesi quadre. Rispondi come se l'avessi ascoltato o visto.
Se ti chiede se sei un'AI, rispondi di sì in una frase e vai avanti.
Se ti chiede di smettere di scriverle, conferma una volta con un breve messaggio.

Contano quattro scelte. La regola della riga vuota dà al tuo codice un punto affidabile in cui dividere. I numeri («da una a tre frasi», «al massimo 3 messaggi») sono verificabili, a differenza di un vago «sii breve». La riga sull’AI nasce da una questione di sicurezza, non di stile: scrivere come una persona è un modo di scrivere, non il permesso di negare di essere un’AI, e le regole di sicurezza per gli AI companion spiegano dove dichiararlo è un obbligo di legge. Infine, il nome: l’evento message.received porta sender_name, il nome che la persona si è data su WhatsApp. È un testo che controlla lei, quindi trattalo come dato e mai come istruzione.

Come fai rispettare le regole nel codice?

Fai rispettare le regole del prompt nel codice, perché i modelli deviano. Questo file TypeScript converte il Markdown nella sintassi di WhatsApp, divide sulle righe vuote e invia ogni parte con POST /v1/messages:

// Trasforma il Markdown che il modello ama scrivere nella sintassi di WhatsApp.
export function toWhatsApp(md: string): string {
  return md
    .replace(/\r\n/g, "\n")
    .replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, "$1 $2") // [etichetta](url) -> etichetta url
    .replace(/^#{1,6}\s+(.+)$/gm, (_, t: string) => `*${t.replace(/\*/g, "")}*`) // # Titolo -> *Titolo*
    .replace(/\*\*(.+?)\*\*/g, "*$1*") // **grassetto** -> *grassetto*
    .replace(/__(.+?)__/g, "*$1*") // __grassetto__ -> *grassetto*
    .replace(/^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/gm, "") // linee orizzontali
    .replace(/\n{3,}/g, "\n\n")
    .trim();
}

// Un paragrafo = un messaggio. I paragrafi lunghi si spezzano a fine frase.
export function splitReply(text: string, maxParts = 4, maxChars = 700): string[] {
  const parts: string[] = [];
  for (const para of text.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean)) {
    if (para.length <= maxChars) {
      parts.push(para);
      continue;
    }
    let current = "";
    for (const sentence of para.split(/(?<=[.!?])\s+/)) {
      if (current && current.length + sentence.length + 1 > maxChars) {
        parts.push(current);
        current = sentence;
      } else {
        current = current ? `${current} ${sentence}` : sentence;
      }
    }
    if (current) parts.push(current);
  }
  // Oltre il limite: accorpa la coda nell'ultimo messaggio consentito, fino a 4.000 caratteri.
  while (parts.length > maxParts && parts.at(-2)!.length + parts.at(-1)!.length < 4000) {
    parts.splice(-2, 2, `${parts.at(-2)}\n\n${parts.at(-1)}`);
  }
  return parts.flatMap((p) => p.match(/[\s\S]{1,4000}/g) ?? []); // il limite di testo di whasp è 4.096
}

export async function sendReply(to: string, reply: string, eventId: string): Promise<void> {
  const parts = splitReply(toWhatsApp(reply));
  for (const [i, text] of parts.entries()) {
    const res = await fetch("https://api.whasp.ai/v1/messages", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.WHASP_API_KEY}`,
        "Content-Type": "application/json",
        // Stesso evento e stessa parte danno sempre la stessa chiave, quindi un retry non invia due volte.
        "Idempotency-Key": `${eventId}:${i}`,
      },
      body: JSON.stringify({ to, text }),
    });
    if (res.status !== 202) {
      const { error } = (await res.json()) as { error: { code: string; message: string } };
      throw new Error(`${error.code}: ${error.message}`); // chat_opted_out, number_unavailable...
    }
  }
}

Il ciclo attende ogni invio, quindi le parti arrivano a whasp in ordine, e whasp poi invia i messaggi di un numero uno alla volta, in ordine. L’Idempotency-Key è costruita con l’id dell’evento webhook e l’indice della parte. whasp conserva una chiave per 7 giorni e restituisce il primo messaggio se la chiave si ripete, quindi il retry di un webhook non può inviare due volte la stessa parte. Un invio rifiutato (un 4xx) non consuma la propria chiave.

Regola maxChars e maxParts sul personaggio: un assistente asciutto potrebbe usare 300 e 3, un narratore 900 e 5. Una regex non ripara tutto. Se un modello scrive una tabella Markdown, il convertitore qui sopra la lascia stare, e la correzione va nel prompt. Il *corsivo* di Markdown diventa grassetto in WhatsApp, un motivo in più per cui il modello di prompt dice di usare i trattini bassi. Collega sendReply al flusso del webhook di creare un agente con l’API di OpenAI e mantieni il controllo della firma preso dalla documentazione di whasp.

Quanto velocemente deve rispondere l’agente?

Un agente su whasp deve rispondere in fretta e senza ritardi artificiali, perché un numero non può mostrare l’indicatore di scrittura. Gli indicatori di scrittura non sono supportati, quindi una risposta che impiega 40 secondi sembra silenzio, e un ritardo aggiunto di proposito fa lo stesso effetto. Usa un modello veloce per i turni di chat normali. Per i lavori lenti per natura, come una chiamata a un tool o una ricerca, manda un breve messaggio di attesa («dammi un minuto, controllo») e la risposta subito dopo.

Anche una risposta divisa serve a dare il ritmo. whasp invia i messaggi di un numero uno alla volta, a circa un secondo di distanza, quindi tre parti arrivano come una breve raffica, ed è così che scrivono le persone.

Tratta le parti come un budget. Un numero whasp può inviare 1.500 messaggi in 24 ore ed è pensato per circa 100 utenti attivi. In media fanno circa 15 messaggi inviati per utente al giorno, e una risposta in quattro parti ne consuma un quarto in un solo turno. Oltre il limite, gli invii falliscono con 429 number_daily_limit. Scalare su più numeri spiega i conti sulla capacità.

Quale tono sembra quello di una persona?

Un agente WhatsApp sembra una persona quando segue il ritmo dell’altro e non recita. Poche abitudini fanno quasi tutto il lavoro:

• Rispecchia la lunghezza. A un messaggio di una parola si risponde con una riga. A un messaggio lungo su una brutta giornata si risponde più a lungo, sempre in paragrafi brevi.
• Rispondi nella sua lingua. Se la persona passa dall’italiano all’inglese, lo fa anche l’agente.
• Salta il congedo. Niente «Fammi sapere se ti serve altro» alla fine di ogni turno.
• Non fare l’eco. Non riformulare il suo messaggio prima di rispondere.
• Chiedi una cosa sola. Due domande in un messaggio ricevono una risposta, di solito la più facile.
• Saluta una volta. Dì ciao nel primo messaggio di una conversazione, o dopo una pausa di giorni, non a ogni turno.
• Scegli, non elencare. Se gli chiedi cosa cucinare, un amico dice «pasta, hai tutto per farla», non cinque opzioni.
• Ammetti i vuoti in poche parole. «Non ne ho idea, sinceramente» batte tre frasi di giri di parole.
• Usa il nome con parsimonia. Ripetere il nome in ogni messaggio suona come il copione di un call center.

I companion hanno bisogno di più dello stile: un personaggio stabile, la memoria di ciò che la persona ha detto la settimana scorsa e regole per i momenti delicati. Lanciare un AI companion su WhatsApp copre l’intero percorso, e la memoria della conversazione copre la parte che rende possibile «la settimana scorsa».

Per verificare il risultato, leggi trascrizioni reali, non solo il prompt. Tieni cinque messaggi di prova fissi e rilanciali ogni volta che cambi il modello o il prompt: un messaggio di una parola, un messaggio lungo su una brutta giornata, una richiesta che richiede dei passaggi, «sei un’AI?» e un messaggio in un’altra lingua. Aiuta anche un controllo automatico veloce: conta quante volte una risposta contiene **, un titolo con # o più di quattro parti, e tieni traccia della lunghezza mediana dei messaggi. Questi numeri cambiano ogni volta che cambia il modello.

Cosa fare adesso

Collega tutto a un numero reale. Costruisci il webhook e la chiamata al modello con l’API di OpenAI, aggiungi messaggi vocali e foto così che l’agente possa rispondere a ciò che le persone mandano davvero, e salva tu la cronologia, perché i server di whasp non conservano i messaggi. Il quickstart nella documentazione di whasp mette in piedi un numero, un webhook e una prima risposta, e la pagina pricing elenca quanto costa un numero.