✈️ Configurazione Telegram Bot
Guida completa per integrare Telegram con AI4CALL: invia notifiche e messaggi automatici al team o utenti specifici tramite bot Telegram durante o dopo le chiamate
Vai in "MARKET" → "Marketplace Plugin" e clicca su Acquista di "Telegram" → FREE
Vai in "MARKET" → "I Miei Plugin" e clicca su Configura di "Telegram"
🚀 Navigazione rapida:
⚠️ Servizi di terze parti
Le integrazioni descritte fanno riferimento a servizi di terze parti.
Rate limit, modalità di autenticazione, configurazioni tecniche, costi e policy sono definiti esclusivamente dai rispettivi provider e possono variare nel tempo.
I costi dei servizi esterni sono sostenuti direttamente dall’utente finale a favore dei fornitori dei servizi stessi e non sono in alcun modo gestiti o intermediati dal nostro portale (es. Meta o altri fornitori per WhatsApp, Zapier, Calendly, ecc.).
Vantaggi:
- ✅ completamente GRATUITO - nessun costo per messaggio
- ✅ nessun limite messaggi giornalieri/mensili
- ✅ messaggi liberi - NO template pre-approvati
- ✅ setup rapidissimo (5 minuti con @BotFather)
- ✅ supporto formattazione Markdown/HTML nativo
- ✅ invio foto, documenti, file fino 50MB
- ✅ developer-friendly con API aperte
Svantaggi:
- ⚠️ meno diffuso tra clienti consumer (vs WhatsApp)
- ⚠️ alcuni utenti non hanno Telegram installato
Quando usare Telegram: notifiche interne team, alert urgenze, riepiloghi supervisori, comunicazioni B2B
Quando usare WhatsApp: comunicazioni clienti finali consumer (conferme appuntamenti, ordini)
Cos'è un Telegram Bot e come funziona
Un Telegram Bot è un account automatizzato controllato via software tramite Telegram Bot API che può inviare/ricevere messaggi, gestire gruppi e fornire servizi agli utenti.
→ username termina con "bot" (es. @ai4call_assistant_bot)
→ appare come contatto normale in chat Telegram
→ può inviare messaggi text, foto, file, location, etc.
→ può ricevere messaggi da utenti (se configurato)
Controllo programmabile:
→ controllato via API HTTP (Telegram Bot API)
→ non c'è interfaccia app - solo codice/software
→ autenticazione tramite Bot Token univoco
→ operazioni asincrone - nessuna connessione persistente richiesta
Gratuito e senza limiti:
→ creazione bot: gratuito
→ invio messaggi: gratuito, nessun costo
→ rate limit: 30 msg/sec globale, 1 msg/sec per utente
→ nessuna quota mensile, nessuna approvazione richiesta
[Cliente chiama AI4CALL]
↓
[Assistente AI gestisce chiamata]
↓
[Rileva evento importante: problema critico, richiesta urgente]
↓
[Assistente invoca send_telegram o send_telegram_bulk]
↓
[POST a Telegram Bot API con Bot Token]
↓
[Telegram valida token e destinatario]
↓
[Telegram consegna messaggio]
↓
[Utenti ricevono notifica push su smartphone/desktop]
↓
[Team vede alert in tempo reale su Telegram]
Use case comuni:
- 🚨 alert urgenze a team tecnico
- 📊 riepiloghi chiamate a supervisore
- ✅ conferme operazioni a manager
- 📢 broadcast annunci a gruppo lavoro
- ❌ inviare messaggi a utenti che non hanno avviato il bot (mai fatto /start)
- ❌ vedere messaggi in gruppi dove non è membro
- ❌ accedere a conversazioni private di altri utenti
- ❌ bypassare blocco utente (se utente blocca bot, bot non può contattarlo)
Regola chiave: utente DEVE avviare conversazione con bot (inviare /start) prima che bot possa inviare messaggi. Soluzione: sistema "Invito via Email" in AI4CALL invia link diretto che apre Telegram e avvia bot automaticamente.
Crea bot Telegram con BotFather
BotFather è il bot ufficiale Telegram per creare e gestire altri bot. Creazione richiede solo 5 minuti.
- Apri Telegram (app mobile, desktop o web.telegram.org)
- Cerca @BotFather nella barra ricerca Telegram
- Avvia conversazione: clicca "START" o invia
/start - Crea nuovo bot: invia comando
/newbot - Scegli nome bot: BotFather chiede nome visualizzato
→ esempio:AI4CALL Assistant
→ può contenere spazi, emoji, qualsiasi carattere
→ questo è il nome che utenti vedranno - Scegli username bot: BotFather chiede username univoco
→ DEVE finire con "bot" (obbligatorio)
→ esempio:ai4call_assistant_bot
→ solo lettere, numeri, underscore (no spazi, caratteri speciali)
→ username diventa handle Telegram: @ai4call_assistant_bot - Ricevi Bot Token: BotFather conferma creazione e fornisce token
→ formato:123456789:ABCdefGHIjklMNOpqrsTUVwxyz
→ lunghezza ~45 caratteri
→ COPIA IMMEDIATAMENTE - è la credenziale API del bot
→ conserva in luogo sicuro (password manager) - Configura bot (opzionale):
/setdescription- descrizione mostrata quando utente cerca bot/setabouttext- info nel profilo bot/setuserpic- foto profilo bot (immagine quadrata min 512x512px)
- ✅ Nome bot: es. "AI4CALL Assistant"
- ✅ Username bot: es. @ai4call_assistant_bot
- ✅ Bot Token: stringa lunga tipo
123456789:ABC-DEF... - ✅ Bot visibile su Telegram - puoi cercarlo e avviarlo con /start
Test rapido: cerca il tuo bot su Telegram, invia /start, dovresti ricevere messaggio conferma da BotFather. Bot è pronto per essere configurato in AI4CALL!
Protezione:
- 🔒 NON condividere pubblicamente (forum, chat, social)
- 🔒 NON committare in repository Git pubblici
- 🔒 conserva in password manager aziendale
- 🔒 se condividi screenshot, censura token
Se token compromesso:
- Apri @BotFather
- Invia
/revoke→ seleziona bot compromesso - Token vecchio viene invalidato
- Invia
/token→ seleziona bot → ricevi nuovo token - Aggiorna token in AI4CALL configurazione
Configura bot in AI4CALL
Inserisci il Bot Token in AI4CALL per permettere all'assistente di inviare messaggi Telegram.
- Accedi al pannello AI4CALL del tuo assistente
- Vai alla sezione "Integrazioni MCP" o "MCP Servers"
- Seleziona "Telegram" dall'elenco
- Nella sezione "Bot Telegram":
- Campo "Bot Token": incolla il token completo ricevuto da @BotFather
- Formato:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz - Verifica nessuno spazio extra all'inizio/fine
- Formato:
- Clicca "SALVA CONFIGURAZIONE"
- Sistema valida token con Telegram API
- Se valido: ✅ configurazione salvata
Verifica: nella dashboard AI4CALL dovresti vedere:
- ✅ Bot Token inserito (mascherato con asterischi: ************)
- ✅ Status: "Configurazione attiva" o simile
Prossimo step: aggiungi utenti autorizzati per permettere loro di ricevere messaggi!
Metodo 1 - Test manuale:
- Apri Telegram e cerca il tuo bot (@ai4call_assistant_bot)
- Invia
/startal bot - Bot dovrebbe rispondere (se hai configurato risposte) o rimanere silenzioso (normale)
Metodo 2 - Test da AI4CALL:
- Chiama assistente AI4CALL
- Chiedi: "Inviami un messaggio Telegram di test"
- L'assistente dovrebbe invocare send_telegram
- Verifica ricezione su Telegram
Gestisci utenti autorizzati
Configura la lista di utenti che possono ricevere messaggi dal bot, specialmente per send_telegram_bulk.
Ideale quando conosci già ID Telegram o username utente.
Procedura:
- Apri Telegram, cerca
@userinfobot - Invia
/start- ID Telegram: ID numerico univoco (es. 123456789)
→ trova ID con @userinfobot o @getidsbot su Telegram
→ permanente, non cambia mai - Username: handle Telegram (es. @mario_rossi)
→ opzionale se fornisci ID
→ può cambiare - meglio usare ID - Nome: nome descrittivo per tua reference
→ es. "Mario Rossi - Tecnico"
→ solo interno, non visibile in Telegram
- ID Telegram: ID numerico univoco (es. 123456789)
- Bot risponde con tuo ID:
Id: 123456789 - Utente appare in lista "Utenti Autorizzati" sotto
METODO 2 - Invito via Email:
Ideale quando utente non sa il proprio ID Telegram.
Procedura:
- Cerca
@getidsbotsu Telegram - Invia qualsiasi messaggio
- Bot risponde con ID e altre info
- Utente clicca link → Telegram si apre automaticamente
- Utente vede bot, invia /start
- Sistema registra automaticamente utente in lista autorizzati
- Utente riceve conferma registrazione
Nota: sistema rimane in ascolto 5 minuti dopo invio email - non serve tenere pagina aperta.
Metodo 1 - @userinfobot:
- Apri Telegram, cerca
@userinfobot - Invia
/start - Bot risponde con tuo ID:
Id: 123456789
Metodo 2 - @getidsbot:
- Cerca
@getidsbotsu Telegram - Invia qualsiasi messaggio
- Bot risponde con ID e altre info
Metodo 3 - Telegram Web:
- Vai su
web.telegram.org - Clicca sul tuo profilo
- URL contiene ID:
web.telegram.org/#/im?p=u123456789
- 📊 Count totale utenti (es. badge "2" accanto a "Utenti Autorizzati")
- 👤 ID Telegram numerico di ogni utente
- ✏️ Nome/username descrittivo
- 🗑️ Icona cestino per rimuovere utente dalla lista
Uso:
- send_telegram: può inviare a QUALSIASI utente Telegram (non limitato a lista)
- send_telegram_bulk: invia SOLO a utenti in questa lista
Best practice: aggiungi team members che devono ricevere alert/notifiche regolari.
Istruisci l'assistente per workflow Telegram
Configura il prompt dell'assistente per utilizzare correttamente send_telegram e send_telegram_bulk.
"Se cliente segnala problema CRITICO o URGENTE (parole chiave: 'emergenza', 'non funziona', 'bloccato'), invia IMMEDIATAMENTE alert Telegram a tutto il team tecnico usando send_telegram_bulk. Messaggio formato: '🚨 URGENZA: [descrizione problema breve], Cliente: [nome], Tel: [numero]'."
2. Riepilogo supervisore (singolo utente):
"Al termine di ogni chiamata >3 minuti, invia riepilogo conciso a supervisore Mario (ID Telegram: 123456789) usando send_telegram. Formato: 'Chiamata completata - Cliente: [nome], Durata: [X] min, Esito: [breve sintesi azione/decisione]'. Usa parse_mode='Markdown' per formattazione."
3. Conferma azioni critiche:
"Quando cliente conferma ordine/prenotazione importante (>€500 o richiesta speciale), notifica manager vendite (@manager_sales) su Telegram con dettagli: importo, cliente, note speciali. Usa send_telegram con formattazione *grassetto* per importo."
4. Escalation automatica:
"Se non riesci a risolvere richiesta cliente dopo 2 tentativi, escalation automatica: invia messaggio Telegram a supervisore tecnico (ID: 987654321) con: problema riportato, tentativi effettuati, dati cliente per callback. Tool: send_telegram."
- Assicurati di aver fatto /start al bot su Telegram
- Chiama assistente AI4CALL
- Chiedi: "Inviami un messaggio Telegram di test"
- L'assistente dovrebbe invocare send_telegram con tuo ID
- Verifica ricezione messaggio su Telegram smartphone/desktop
Test 2 - Broadcast team:
- Aggiungi almeno 2 utenti in lista "Utenti Autorizzati"
- Entrambi devono aver fatto /start al bot
- Chiama assistente, simula urgenza: "C'è un'emergenza critica"
- L'assistente dovrebbe invocare send_telegram_bulk
- Verifica TUTTI utenti autorizzati ricevono messaggio
Test 3 - Formattazione:
- Chiedi: "Invia messaggio formattato con grassetto e emoji"
- Verifica messaggio contiene formattazione Markdown corretta
- Esempio:
*Urgente*appare grassetto, emoji 🚨 visibili
🛠️ Tool Reference Telegram
Specifiche tecniche dei 2 tool MCP per invio messaggi Telegram.
send_telegram
Parametri:
user_id(obbligatorio, string): ID numerico (es. "123456789") O username (es. "@mario")text(obbligatorio, string): testo messaggiophoto_url(opzionale, string): URL immagine HTTPS (diventa caption se fornito)parse_mode(opzionale, string): "Markdown" o "HTML" per formattazione
Esempio:
send_telegram({
user_id: "123456789",
text: "*Urgenza*: cliente richiede supporto",
parse_mode: "Markdown"
})
send_telegram_bulk
Parametri:
text(obbligatorio, string): testo messaggio da inviare a tutti
Nota: invia automaticamente a TUTTI utenti nella lista "Utenti Autorizzati" configurata. NO user_id richiesto.
Esempio:
send_telegram_bulk({
text: "🚨 Alert: sistema in manutenzione ore 22-24"
})
Use case: alert team, annunci, emergenze che richiedono notifica broadcast
❓ Domande Frequenti
Risposte alle domande più comuni su Telegram Bot integration
Procedura: (1) apri Telegram e cerca @BotFather, (2) invia comando /newbot, (3) scegli nome bot (es. "AI4CALL Assistant"), (4) scegli username bot (deve finire con "bot", es. "ai4call_assistant_bot"), (5) BotFather genera Bot Token (stringa tipo 123456:ABC-DEF1234ghIkl...), (6) COPIA token immediatamente e salvalo - è la credenziale API del bot, (7) configura bot: /setdescription, /setabouttext, /setuserpic opzionali.
send_telegram: invia a SINGOLO utente specifico usando user_id (ID numerico o @username). Usa per notifiche personali, riepiloghi individuali, messaggi privati. send_telegram_bulk: invia STESSO messaggio a TUTTI utenti nella lista "Utenti Autorizzati" (broadcast). Usa per avvisi team, alert emergenze, annunci generali. send_telegram_bulk NON richiede user_id - invia automaticamente a lista configurata.
Metodo 1: usa bot @userinfobot - invia /start e ti risponde con ID. Metodo 2: usa bot @getidsbot - invia qualsiasi messaggio. Metodo 3: apri Telegram Web (web.telegram.org), clicca profilo, URL contiene ID dopo #id. ID numerico è stringa tipo 123456789 (9 cifre tipicamente). Username (@mario) può cambiare, ID è permanente - meglio usare ID per affidabilità.
Sì, usa parametro parse_mode. Opzioni: (1) parse_mode="Markdown": *grassetto*, _corsivo_, [link](url), `code`, ```blocco code```. (2) parse_mode="HTML": grassetto, corsivo, link, code. Esempio: send_telegram con text="*Urgente*: cliente richiede supporto" e parse_mode="Markdown" rende "Urgente" grassetto. Default senza parse_mode: testo plain.
Sì, tool send_telegram supporta parametro photo_url. Fornisci URL pubblico HTTPS dell'immagine (es. https://example.com/photo.jpg). Telegram scarica e invia immagine. Formati supportati: JPG, PNG, GIF, WebP. Max dimensione: 10MB per foto, 50MB per file. Se photo_url fornito, text diventa caption immagine. Per inviare solo foto senza testo: usa text="" o ometti. Esempio: photo_url="https://cdn.com/alert.png".
Il bot PUÒ ricevere messaggi (se utente scrive al bot), ma AI4CALL attualmente usa Telegram in modalità SEND-ONLY (solo invio). Bot NON legge risposte utenti in tempo reale durante chiamata. Per gestire risposte: configura webhook Telegram separato con n8n/Zapier che processa messaggi in arrivo, salva su database/CRM, notifica team. Use case AI4CALL: notifiche outbound, non conversazioni bidirezionali.
Bot Token garantisce controllo completo del bot. Protezione: (1) NON condividere token pubblicamente, (2) NON committare in repository Git pubblici, (3) conserva in password manager sicuro, (4) se compromesso: revoca token via @BotFather comando /revoke e genera nuovo con /token, (5) usa HTTPS per comunicazioni API, (6) limita utenti autorizzati a ricevere messaggi. Se token leaked: chiunque può inviare messaggi a nome tuo bot.
Sì, ma richiede setup aggiuntivo. Procedura: (1) crea gruppo Telegram, (2) aggiungi bot al gruppo come membro, (3) ottieni group_id (negativo, es. -123456789) usando @getidsbot nel gruppo, (4) usa send_telegram con user_id=group_id (numero negativo). Tutti membri gruppo vedono messaggio. Alternativa: usa canale Telegram (broadcast one-way), aggiungi bot come admin, invia a channel_id.
Checklist troubleshooting: (1) verifica Bot Token corretto (formato 123456:ABC-DEF...), (2) testa token con @BotFather comando /mybots, (3) verifica user_id corretto (ID numerico o @username esistente), (4) controlla utente ha avviato bot (inviato /start) - Telegram blocca bot che non sono stati avviati dall'utente, (5) verifica bot non bloccato da utente, (6) controlla log AI4CALL per errori API, (7) testa manualmente con curl/Postman API Telegram.
Attualmente send_telegram supporta text e photo_url. Per documenti: workaround (1) carica file su storage cloud (Google Drive, Dropbox), (2) genera link pubblico/temporaneo, (3) invia link tramite Telegram text con messaggio "Documento disponibile: [link]". Alternativa: estendi tool send_telegram con parametro document_url (richiede modifica backend) che usa Telegram sendDocument API. Max size documenti: 50MB.
Configurazione via @BotFather: (1) Nome bot: impostato durante creazione con /newbot, modificabile con /setname, (2) Username bot: impostato con /newbot (fisso, non modificabile dopo), (3) Foto profilo: /setuserpic carica immagine quadrata min 512x512px, (4) Descrizione: /setdescription testo mostrato quando utente cerca bot, (5) About: /setabouttext info mostrate in profilo bot. Nome visualizzato appare sopra messaggi inviati dal bot.
Telegram Bot API non ha scheduling nativo - invia immediatamente. Per scheduling: (1) integra con n8n/Zapier che supporta delay/cron, (2) assistente salva dati + timestamp, (3) n8n attende o esegue cron giornaliero, (4) n8n invoca send_telegram al momento desiderato. Esempio: reminder giornaliero ore 9:00 a team via send_telegram_bulk - cron job n8n alle 9:00 chiama tool automaticamente. AI4CALL workflow: invio immediato durante/dopo chiamata.
Tecnologia e persone:
insieme, zero attese e mille soluzioni.
Pronto a trasformare
le tue chiamate?
Richiedi una demo gratuita e scopri come AI4CALL può rivoluzionare il tuo business