Connetti ogni canale
in un'unica casella.

§ 00Cosa ti serve

Ogni canale richiede 5–20 minuti. Lavorerai in due posti: la console sviluppatore del canale (BotFather di Telegram, Meta Developer Dashboard) e la schermata Canali nel tuo workspace EasyLiveChat su app.livechattools.com/channels.

Tutti e quattro i canali condividono la stessa architettura in EasyLiveChat — una Conversation normalizzata per contatto, una casella, una box di risposta. Le differenze sono nelle credenziali richieste da ciascun provider e nel loro schema di firma webhook.

§ 01Telegram

Il canale più semplice da configurare. Telegram non ha bisogno di un'app sviluppatore né di un account business — solo di un bot. I token bot durano per sempre e l'intera integrazione richiede circa cinque minuti.

1. Crea un bot con BotFather

Apri Telegram e avvia una chat con @BotFather. Invia /newbot, scegli un nome visualizzato e uno username che termini con bot. . BotFather risponde con un token nella forma 1234567890:ABCdefGHI…. Copialo.

2. Connetti in EasyLiveChat

Nel tuo workspace vai a Canali → Bot Telegram → Connetti. Incolla il token del bot. Scegli un nome visualizzato — appare solo nella casella. Invia.

Apri Impostazioni integrazione sulla nuova riga per rivelare il Webhook secret e l'URL di callback dell'integrazione.

3. Punta Telegram al nostro webhook

La Bot API di Telegram non ha UI per i webhook; li imposti via setWebhook. Sostituisci i placeholder qui sotto con il tuo bot token, l'integration ID e il webhook secret, poi eseguilo una volta:

curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.livechattools.com/api/channels/webhook/telegram/${INTEGRATION_ID}",
    "secret_token": "${WEBHOOK_SECRET}",
    "allowed_updates": ["message", "edited_message"]
  }'

Telegram risponde {"ok":true,"description":"Webhook was set"}. . Verifica con getWebhookInfo — — il pending_update_count dovrebbe scendere a 0.

4. Test

Apri t.me/yourbot_username in Telegram, tocca Avvia, invia un messaggio qualsiasi. Dovrebbe apparire nella tua casella EasyLiveChat in meno di un secondo con il nome del mittente e il codice lingua. Rispondi dal dashboard — arriverà sul Telegram del visitatore un attimo dopo.

§ 02WhatsApp Cloud

Meta Cloud API è la scelta giusta per quasi tutti — completamente ospitato, gratis fino a 1.000 service conversation al mese, e l'unico trasporto WhatsApp che non richiede infrastruttura dal tuo lato. La configurazione è più pesante di Telegram perché Meta richiede un'app sviluppatore e un business portfolio verificato per traffico di produzione.

1. Crea un'app sviluppatore Meta

Vai a developers.facebook.com/apps → Create App. Scegli un nome, un'email, poi nella schermata successiva seleziona il caso d'uso “Connect with customers through WhatsApp”. Collega un Business Portfolio — uno esistente o il Test Business integrato di Meta per la valutazione.

Dopo aver creato l'app, apri Use Cases → Connect on WhatsApp → API Setup. Vedrai un Phone Number ID (il numero di test gratuito fornito da Meta, o il tuo una volta aggiunto) e un pulsante Generate access token. Clicca, approva e copia il token risultante. Copia anche il Phone Number ID.

2. Prendi l'App Secret

Nella stessa dashboard Meta, apri App settings → Basic. L'App Secret è nascosto dietro un pulsante Show — rivela e copia. Questa è la chiave HMAC con cui Meta firma ogni POST webhook. Senza, i tuoi messaggi in ingresso saranno rifiutati come BAD_SIGNATURE.

3. Connetti WhatsApp in EasyLiveChat

Canali → WhatsApp Cloud → Connetti. Compila il nome visualizzato (libero), il Phone Number ID, l'Access Token e l'App Secret. Invia. Apri le impostazioni dell'integrazione per copiare il webhook secret auto-generato e l'integration ID.

4. Configura il webhook Meta

Tornato nella dashboard Meta, vai a Use Cases → Connect on WhatsApp → Configuration. Incolla:

Callback URL : https://api.livechattools.com/api/channels/webhook/whatsapp/${INTEGRATION_ID}
Verify token : ${WEBHOOK_SECRET}

Clicca Verify and save. Meta invia un handshake GET — restituiamo la sua challenge se il verify token combacia. Nella stessa pagina, trova la lista Webhook fields e attiva messages su Subscribed. Senza questo toggle Meta accetta l'URL del webhook ma non consegna mai nulla.

5. Aggiungi un destinatario di test (solo sandbox)

Se usi il numero di test gratuito di Meta, devi inserire ogni destinatario in una allow-list prima di poter inviargli. In API Setup → To, aggiungi il numero da cui invierai messaggi — Meta invia un OTP a 6 cifre via SMS per verificare. Fino a cinque destinatari di test. I numeri business reali non hanno questa restrizione.

§ 03Facebook Messenger

Messenger usa la stessa Meta App, App Secret e idraulica webhook di WhatsApp — ma parla con una Pagina Facebook invece di un numero di telefono, e gli access token sono Page Access Token, non token WhatsApp Business.

1. Aggiungi Messenger alla tua app Meta

Nella stessa app usata per WhatsApp (o una nuova), apri Use cases → Add use cases → filtra Business messaging → Engage with customers on Messenger from Meta. Salva. L'app ora ha due prodotti affiancati.

2. Collega una Pagina Facebook

Apri Messenger from Meta → Messenger API Settings. Sotto Generate access tokens, clicca Connect accanto a No FB pages yet. Meta chiede a quali Pagine dare accesso — scegli quella su cui ricevere messaggi, accetta i permessi, salva.

La Pagina ora appare con un Page Access Token one-click e un Page ID. Copia entrambi. Il Page ID è anche il valore che incollerai come pageId in EasyLiveChat.

3. Connetti Messenger in EasyLiveChat

Canali → Messenger → Connetti. Compila Page ID, Page Access Token e lo stesso App Secret usato per WhatsApp. Invia e copia il webhook secret + ID della nuova integrazione.

4. Sottoscrizione webhook a due livelli

Messenger ha una stranezza che WhatsApp non ha: serve due sottoscrizioni per consegnare qualcosa. Prima la sottoscrizione a livello di app — in Messenger API Settings → Configure webhooks incolla:

Callback URL : https://api.livechattools.com/api/channels/webhook/messenger/${INTEGRATION_ID}
Verify token : ${WEBHOOK_SECRET}

Clicca Verify and save, poi espandi Webhook fields e attiva messages. Poi la sottoscrizione a livello di Pagina, che non puoi fare da UI — esegui questo curl:

curl -X POST "https://graph.facebook.com/v20.0/${PAGE_ID}/subscribed_apps" \
  -d "subscribed_fields=messages,messaging_postbacks,message_deliveries,message_reads" \
  -d "access_token=${PAGE_ACCESS_TOKEN}"

Senza la sottoscrizione a livello di Pagina, Meta restituisce {"success":true} sulla sottoscrizione di app ma non spara mai il webhook. Puoi confermare che tutto è cablato interrogando:

curl "https://graph.facebook.com/v20.0/${APP_ID}/subscriptions?access_token=${APP_ID}|${APP_SECRET}"

La risposta deve elencare un oggetto di tipo page con un array fields non vuoto che include messages.

§ 04Instagram DM

La messaggistica Instagram viaggia sulle stesse tubature Messenger Platform ma aggiunge due requisiti: l'account Instagram deve essere un account Business (non personale né Creator), e deve essere connesso a una Pagina Facebook nello stesso Business Portfolio. Quando entrambi sono veri, il tuo Page Access Token è anche il tuo access token Instagram.

1. Converti l'account IG a Business

Nell'app mobile Instagram: Impostazioni → Account → Passa a un account professionale → Azienda. Categoria qualsiasi. La conversione è reversibile.

2. Aggiungi l'account IG al tuo Business Portfolio

In Meta Business Suite Settings → Accounts → Instagram accounts → Add → accedi con le credenziali IG. Meta conferma e mostra l'Instagram Business Account ID dell'account IG — un numero di 17 cifre che inizia con 1784…. Copialo; questo è il tuo pageId per l'integrazione EasyLiveChat.

3. Collega IG alla Pagina Facebook

Questo è il passo più trascurato. Apri la casella della Pagina Facebook in Meta Business Suite — business.facebook.com/latest/inbox?asset_id={page_id}. Un banner dice “Connect to Instagram” con un pulsante Connect. Clicca, accedi a Instagram, concedi i permessi richiesti, conferma. Dopo questo la Graph API di Meta inizierà a rispondere alle domande sull'account IG nello scope dell'access token della Pagina.

4. Connetti Instagram in EasyLiveChat

Canali → Instagram DM → Connetti. Usa l'Instagram Business Account ID del passo 2 come pageId, lo stesso Page Access Token usato per Messenger come pageAccessToken, e lo stesso App Secret di prima.

5. Sottoscrivi a entrambi i livelli

Instagram usa object=instagram per i webhook a livello di app (Messenger usava object=page. ). Aggiungi questo curl in cima alla sottoscrizione Messenger esistente:

curl -X POST "https://graph.facebook.com/v20.0/${APP_ID}/subscriptions" \
  -d "object=instagram" \
  -d "callback_url=https://api.livechattools.com/api/channels/webhook/instagram/${INTEGRATION_ID}" \
  -d "verify_token=${WEBHOOK_SECRET}" \
  -d "fields=messages,messaging_postbacks,message_reactions" \
  -d "access_token=${APP_ID}|${APP_SECRET}"

§ 05Risoluzione problemi