WhatsApp via API (MyFlow API)
Con MyFlow API il tuo gestionale o CRM lavora sullo stesso WhatsApp di MyFlow, quello che i tuoi operatori usano nel pannello. Il gestionale può:- mandare messaggi ai clienti dai numeri WhatsApp dell’azienda: testo libero per rispondere, template per scrivere per primo;
- ricevere i messaggi dei clienti appena arrivano, con i webhook, insieme agli esiti di consegna e lettura;
- leggere lo storico della conversazione con un cliente, anche quella passata;
- creare template e sapere quando Meta li approva o li rifiuta;
- lanciare campagne marketing verso molti contatti;
- tenere allineati i contatti: nomi, etichette e campi personalizzati;
- gestire gli Agenti AI di MyFlow: crearli, cambiarne istruzioni, orari e conoscenza, accenderli e spegnerli su un numero.
Cosa serve
1
Il piano MyFlow
MyFlow API è compresa in MyFlow: con MyFlow attivo non serve nessun altro modulo. Senza MyFlow l’API non è disponibile.
2
Un numero WhatsApp collegato e le condizioni accettate
Serve almeno un numero WhatsApp collegato a MyFlow, con le condizioni del servizio WhatsApp accettate dal pannello. Lo stesso vale per usare MyFlow dal pannello.
3
Una chiave API con WhatsApp
Vai su Il tuo abbonamento → Chiavi API (
https://cloud.mycentralino.com/account/chiavi-api) → Nuova chiave. In Cosa può fare la chiave scegli Solo WhatsApp oppure Centralino e WhatsApp, poi premi Crea chiave.Cosa può fare la chiave compare solo con MyFlow attivo, e solo al titolare o a un amministratore di MyFlow: una chiave con WhatsApp legge le conversazioni dei clienti. Quando ne nasce una, il titolare dell’account riceve un’email.
Le chiavi e cosa possono fare
Ogni chiave ha un ambito, scelto quando la crei. Non si cambia dopo: per un ambito diverso si crea una chiave nuova.
Tutte le chiavi create prima di MyFlow API valgono come Centralino: non aprono WhatsApp.
Base URL e autenticazione
Come tutta l’API:X-API-KEY di ogni richiesta. Il body, quando c’è, è JSON con Content-Type: application/json e al massimo 64 KB.
Limiti di richieste
Valgono i limiti dell’API: sono per account e li condividono tutte le chiavi, anche quelle Centralino. Gli headerX-RateLimit-* di ogni risposta dicono quante richieste restano. Oltre il limite si riceve 429 con l’header Retry-After.
Per i messaggi c’è anche un tetto giornaliero di invii via API per account: oltre il tetto POST /v1/whatsapp/messages risponde 429 daily_send_limit. Per scrivere a molti contatti si usano le campagne, che hanno i loro limiti e la loro fascia di invio.
Convenzioni
-
Risposte:
{"success": true, "data": …}, a volte con campi in più accanto adata(pagination,duplicate,conversation…). Gli errori hanno la forma{"success": false, "error": {"code": "…", "message": "…"}}e possono portare altri campi utili dentroerror, per esempio l’elenco dei numeri quando mancafrom. -
codeè stabile,messageno. Il programma decide guardandocode.messageè in italiano piano e si può mostrare all’operatore così com’è. -
Numeri di telefono. Nelle risposte sono sempre in formato internazionale con il
+, senza spazi:+393331234567. In ingresso il formato consigliato è lo stesso. Sono accettati anche:- il prefisso
00; - i numeri italiani senza prefisso (
3331234567,0212345678), a cui si aggiunge+39.
/contacts/{phone}) il numero è di sole cifre, con o senza+davanti (+oppure%2B). - il prefisso
-
Il numero mittente (
from). Se l’account ha un solo numero WhatsApp collegato,fromsi può omettere. Con più numeri va indicato: senza, la risposta è400 number_requiredcon l’elenco dei numeri inerror.numbers. I numeri sono in GET /v1/whatsapp/numbers. -
Paginazione. Gli elenchi lunghi sono a cursore: la risposta porta
pagination.next_before. Lo passi comebeforenella richiesta successiva finchéhas_morenon èfalse. -
Idempotency-Key. È un header facoltativo, da 1 a 200 caratteri stampabili, senza spazi. Su POST /v1/whatsapp/messages ripetere la stessa chiamata con la stessa chiave restituisce lo stesso invio, conduplicate: true, invece di mandare un secondo messaggio. Mettila sempre se il tuo programma ripete le richieste dopo un errore di rete.
Le regole di WhatsApp
Le pone Meta e valgono per tutti, dal pannello come dall’API:- La finestra di 24 ore. Puoi scrivere testo libero a un cliente solo entro 24 ore dal suo ultimo messaggio. Fuori finestra, o se il cliente non ti ha mai scritto, serve un template approvato da Meta.
- I template sono messaggi con un testo fisso e variabili (
{{1}},{{2}}…), approvati da Meta prima dell’uso. Possono essere:UTILITY: avvisi e promemoria legati a un servizio già in corso;MARKETING: offerte e promozioni.
- I costi. Meta fa pagare i messaggi template, e soprattutto i
MARKETING, sull’account WhatsApp Business dell’azienda. Il metodo di pagamento si imposta su Meta. - STOP. Chi ha chiesto di non ricevere messaggi promozionali non riceve template
MARKETING: l’invio diretto risponde403 opted_oute le campagne lo saltano.
Endpoint
I messaggi in arrivo, gli esiti di consegna e gli esiti dei template li spedisce MyFlow al gestionale con i webhook. L’indirizzo si imposta nel pannello.
I casi più comuni
Rispondere ai clienti dal gestionale
- Imposta un webhook con l’evento
message.received: a ogni messaggio di un cliente il gestionale riceve testo, numero e nome. - Rispondi con POST /v1/whatsapp/messages e
"type": "text", entro 24 ore dall’ultimo messaggio del cliente. - Per mostrare la conversazione intera leggi lo storico.
Mandare avvisi e promemoria
- Scegli un template
UTILITYapprovato con GET /v1/whatsapp/templates, oppure creane uno. - Mandalo con POST /v1/whatsapp/messages e
"type": "template", riempiendo le variabili. Usa unaIdempotency-Keylegata al tuo appuntamento o ordine. - Segui consegna e lettura con l’evento webhook
message.status.
Una campagna a molti clienti
Crea la bozza, aggiungi i destinatari, poi lanciala dichiarando il consenso dei destinatari e la presa visione dei costi di Meta. L’andamento si legge conGET /v1/whatsapp/campaigns/{id}.
Tenere allineata l’anagrafica
Quando nel gestionale cambia un cliente, aggiornalo conPUT /v1/whatsapp/contacts/{phone}. Per il primo allineamento usa POST /v1/whatsapp/contacts/bulk.
L’agente AI fuori orario
Il gestionale può attivare un Agente AI di MyFlow su un numero a fine giornata e disattivarlo la mattina. L’agente stesso si può creare e tenere aggiornato dal gestionale: istruzioni, orari e conoscenza, per esempio le domande frequenti o il listino del momento.Codici di errore
Questi errori possono arrivare da qualsiasi rotta/v1/whatsapp/*. Gli errori propri di ogni rotta sono nella sua pagina.
