Skip to main content

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.
È tutto lo stesso MyFlow, non una copia. Un messaggio mandato dal gestionale compare nella conversazione in MyFlow con la nota «inviato dal gestionale (API)». Un contatto modificato via API è già modificato in MyFlow → Contatti. Una campagna lanciata via API si vede, si mette in pausa e si annulla da MyFlow → Campagne.

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.
Al gestionale che usa solo WhatsApp dai una chiave Solo WhatsApp. Se la chiave finisce nelle mani sbagliate, almeno non serve a far partire chiamate.

Base URL e autenticazione

Come tutta l’API:
La chiave va nell’header 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 header X-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 a data (pagination, duplicate, conversation…). Gli errori hanno la forma {"success": false, "error": {"code": "…", "message": "…"}} e possono portare altri campi utili dentro error, per esempio l’elenco dei numeri quando manca from.
  • code è stabile, message no. Il programma decide guardando code. 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.
    Spazi e trattini nel body vengono ignorati. Nei percorsi (/contacts/{phone}) il numero è di sole cifre, con o senza + davanti (+ oppure %2B).
  • Il numero mittente (from). Se l’account ha un solo numero WhatsApp collegato, from si può omettere. Con più numeri va indicato: senza, la risposta è 400 number_required con l’elenco dei numeri in error.numbers. I numeri sono in GET /v1/whatsapp/numbers.
  • Paginazione. Gli elenchi lunghi sono a cursore: la risposta porta pagination.next_before. Lo passi come before nella richiesta successiva finché has_more non è 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, con duplicate: 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 risponde 403 opted_out e 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

  1. Imposta un webhook con l’evento message.received: a ogni messaggio di un cliente il gestionale riceve testo, numero e nome.
  2. Rispondi con POST /v1/whatsapp/messages e "type": "text", entro 24 ore dall’ultimo messaggio del cliente.
  3. Per mostrare la conversazione intera leggi lo storico.

Mandare avvisi e promemoria

  1. Scegli un template UTILITY approvato con GET /v1/whatsapp/templates, oppure creane uno.
  2. Mandalo con POST /v1/whatsapp/messages e "type": "template", riempiendo le variabili. Usa una Idempotency-Key legata al tuo appuntamento o ordine.
  3. 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 con GET /v1/whatsapp/campaigns/{id}.

Tenere allineata l’anagrafica

Quando nel gestionale cambia un cliente, aggiornalo con PUT /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.