Server MCP per gestire le chat di WhatsApp Business Platform da assistenti IA come Meta Muse e Claude
Resta nell’assistente IA che usi già. Collegalo a TimelinesAI per leggere le tue chat di WhatsApp Business Platform, rispondere ai clienti, inviare modelli approvati e assegnare ed etichettare le chat per il tuo team.
Il server MCP di TimelinesAI funziona con qualsiasi assistente IA che supporta server MCP remoti con accesso OAuth. Non c’è software da installare, nessun server da gestire e nessuna password da condividere. L’assistente può fare solo ciò che il tuo ruolo in TimelinesAI consente.
Cosa può fare il connettore
- Leggere chat, cronologia dei messaggi e stato dei messaggi su tutti i tuoi numeri WhatsApp Business Platform
- Rispondere con testo libero finché la finestra di 24 ore del cliente è aperta
- Inviare modelli approvati da Meta e avviare nuove chat con un modello
- Assegnare e rimuovere l’assegnazione, aprire e chiudere chat, e aggiungere o rimuovere etichette
- Reagire ai messaggi e vedere i membri del tuo team e i tuoi modelli
Cosa ti serve
- Un account TimelinesAI. I nuovi account iniziano con una prova gratuita di 10 giorni, senza carta di credito.
- Almeno un numero WhatsApp Business Platform (Cloud API) collegato al tuo workspace. Nuovo su WhatsApp Business Platform? Collega e attiva un numero WhatsApp Business in Meta Business Portfolio.
- Almeno un modello approvato, se vuoi che l’assistente avvii nuove chat o scriva ai clienti fuori dalla finestra di 24 ore.
Come configurarlo
Passo 1: Aggiungi il connettore.
Nel tuo assistente IA, aggiungi un nuovo connettore (o un server MCP personalizzato) e incolla
https://mcp.services.timelines.ai/mcp/waba.Passo 2: Accedi con TimelinesAI.
L’assistente apre la pagina di accesso di TimelinesAI. Accedi o crea un account.
Passo 3: Approva l’accesso.
Controlla i permessi nella pagina “Authorize timelines-mcp?” e fai clic su Authorize.
Passo 4: Fai la tua prima domanda.
Prova con “Elenca i miei numeri WhatsApp Business” o “Mostra le chat in attesa di risposta”.
Dettagli di connessione
| Impostazione | Valore |
|---|---|
| URL del server MCP | https://mcp.services.timelines.ai/mcp/waba |
| Trasporto | Streamable HTTP |
| Accesso | OAuth 2.1 con PKCE (S256) e registrazione dinamica dei client |
| Server di autorizzazione | https://mcp.services.timelines.ai |
| Scope | openidchats:readchats:writemessages:readmessages:writelabels:readlabels:writeaccounts:readworkspace:readtemplates:read |
Strumenti (18)
Gli strumenti di lettura si limitano a consultare i dati. Gli strumenti di scrittura modificano una chat in TimelinesAI. Gli strumenti di scrittura sensibile inviano qualcosa che il cliente vede, e Meta addebita l’invio dei modelli.
| Strumento | Cosa fa | Accesso |
|---|---|---|
waba_accounts | Elenca i numeri WhatsApp Business Platform da cui puoi inviare | Lettura |
waba_list_chats | Elenca le chat che puoi vedere, con filtri (per esempio, per numero di telefono) | Lettura |
waba_chat_details | Mostra una chat: se la finestra di 24 ore è aperta, l’assegnatario, le etichette e il numero di invio | Lettura |
waba_chat_history | Mostra i messaggi di una chat, dal più recente | Lettura |
waba_message_details | Mostra un messaggio, incluso il motivo se non è andato a buon fine | Lettura |
waba_templates | Elenca i modelli di messaggio che puoi usare | Lettura |
waba_template_details | Mostra un modello: contenuto, variabili, stato e i numeri da cui può essere inviato | Lettura |
workspace_team | Elenca i membri del team, così una chat può essere assegnata a uno di loro | Lettura |
waba_chat_open | Riapre una chat chiusa | Scrittura |
waba_chat_close | Chiude una chat | Scrittura |
waba_chat_assign | Assegna una chat a un membro del team | Scrittura |
waba_chat_unassign | Rimuove l’assegnatario da una chat | Scrittura |
waba_chat_set_label | Aggiunge un’etichetta a una chat | Scrittura |
waba_chat_remove_label | Rimuove un’etichetta da una chat | Scrittura |
waba_chat_send_message | Invia una risposta di testo libero in una chat esistente, solo finché la finestra di 24 ore è aperta | Scrittura sensibile |
waba_chat_send_template | Invia un modello approvato in una chat esistente | Scrittura sensibileMeta addebita i modelli |
waba_start_chat | Avvia una nuova chat con un numero di telefono usando un modello approvato | Scrittura sensibileMeta addebita i modelli |
waba_message_react | Aggiunge o rimuove una reazione emoji su un messaggio | Scrittura sensibileIl cliente lo vede |
Ogni strumento è contrassegnato come di sola lettura o come uno che apporta modifiche, così gli assistenti IA possono chiederti conferma prima di una scrittura.
Input degli strumenti
Ogni strumento restituisce la risposta JSON dell’API di TimelinesAI per quell’azione. Gli input obbligatori sono in grassetto. L’assistente ottiene prima gli id con gli strumenti di elenco (per esempio, l’id di una chat con waba_list_chats).
| Strumento | Input |
|---|---|
waba_accounts | Nessuno |
waba_list_chats | Tutti facoltativi: waba_account_id, responsible (email del membro del team), closed (true o false), whatsapp_phone, with_msg (include l’ultimo messaggio), page (50 chat per pagina) |
waba_chat_details | chat_id |
waba_chat_history | chat_id. Facoltativi: from_me, after e before (data o data e ora ISO), after_message e before_message (id del messaggio), sorting_order (asc o desc), page, size |
waba_message_details | message_uid |
waba_templates | page facoltativo |
waba_template_details | template_id |
workspace_team | Nessuno |
waba_chat_openwaba_chat_closewaba_chat_unassign | chat_id |
waba_chat_assign | chat_id, user_email (un membro del team da workspace_team) |
waba_chat_set_labelwaba_chat_remove_label | chat_id, label |
waba_chat_send_message | chat_id, text |
waba_chat_send_template | chat_id, name e language di un modello approvato. variables facoltativo: liste header e body, nell’ordine del modello |
waba_start_chat | waba_account_id, phone (formato internazionale con + iniziale), name e language di un modello approvato. variables facoltativo, come sopra |
waba_message_react | message_uid, reaction (un emoji, o un valore vuoto per rimuoverla) |
Errori e limiti
Quando una chiamata non va a buon fine, lo strumento restituisce un risultato di errore con lo stato HTTP, il messaggio dell’API di TimelinesAI e, se presente, un codice di errore. L’assistente può quindi spiegare cosa è successo e cosa fare dopo.
| Stato | Cosa significa | Cosa fare |
|---|---|---|
| 400, 409, 422 | La richiesta è stata rifiutata, per esempio per un input mancante o un numero di telefono nel formato sbagliato | Correggi l’input e riprova |
| 401 | L’accesso non è più valido | Ricollega il connettore e accedi di nuovo a TimelinesAI |
| 403 | Il ruolo o il piano dell’utente non consente questa azione | Chiedi a un proprietario o amministratore del workspace |
| 404 | La chat, il messaggio o il modello non è stato trovato | Trova l’id corretto con gli strumenti di elenco |
| 429 | Troppe richieste | Attendi un momento e riprova |
| 5xx, o nessuna risposta entro 15 secondi | Problema temporaneo lato TimelinesAI | Riprova più tardi |
- Finestra di 24 ore: se la finestra è chiusa, una risposta di testo libero viene rifiutata. Invia invece un modello approvato.
waba_chat_detailsewaba_list_chatsmostrano se la finestra è aperta. - Consegna: un invio riuscito significa che Meta ha accettato il messaggio. Se la consegna fallisce in seguito,
waba_message_detailsne mostra il motivo. - Nessun invio doppio: gli strumenti di invio non vengono ritentati automaticamente. Se un invio va in timeout, controlla
waba_chat_historyprima di inviare di nuovo, così il cliente non riceve il messaggio due volte. - Limiti di frequenza: il connettore non aggiunge un proprio limite. I limiti di messaggistica di Meta per il tuo numero WhatsApp Business Platform continuano ad applicarsi ai messaggi modello.
Cosa può vedere l’assistente
L’assistente agisce come l’utente TimelinesAI che ha effettuato l’accesso, con i permessi di quell’utente. Non vede mai più di quanto quell’utente può vedere in TimelinesAI.
- Proprietari e amministratori vedono tutti i numeri WhatsApp Business Platform del workspace e tutte le loro chat.
- Supervisori di team e membri del team vedono i numeri il cui team è il loro, e le chat di quei numeri.
- Agenti vedono i numeri assegnati a loro, e le chat di quei numeri.
- Collaboratori vedono solo le chat assegnate a loro. Possono rispondere lì, ma non possono avviare nuove chat.
- Chat assegnate: chiunque sia assegnato a una singola chat può vederla e rispondere. Questo non dà accesso al resto di quel numero.
Regole dei messaggi
- Dentro la finestra di 24 ore (il cliente ha scritto nelle ultime 24 ore), l’assistente può inviare risposte di testo libero.
- Fuori dalla finestra, o per una nuova chat, si possono inviare solo modelli approvati da Meta. Un modello non riapre la finestra per il testo libero.
- I modelli con intestazione multimediale (immagine, video o documento) non possono ancora essere inviati tramite il connettore. Usa modelli con variabili di testo.
- Consegna: un invio riuscito significa che Meta ha accettato il messaggio. La consegna può comunque fallire in seguito, e l’assistente può verificarne il motivo.
Prezzi
L’uso del connettore è incluso in ogni piano TimelinesAI senza costi aggiuntivi. Meta addebita i messaggi modello alle sue tariffe standard di WhatsApp Business Platform, e l’assistente ti avvisa prima di inviarne uno.
Privacy e sicurezza
- L’accesso usa OAuth, quindi il tuo assistente IA non vede mai la tua password di TimelinesAI.
- L’assistente può usare solo i dati a cui ha accesso l’utente collegato, entro gli scope indicati sopra.
- Per scollegarlo, rimuovi il connettore nel tuo assistente IA.
- Consulta l’informativa sulla privacy di questo connettore (in inglese) e i Termini. Assistenza: support@timelines.ai.
Domande frequenti sul server MCP per WhatsApp Business Platform
Ultimo aggiornamento: