Canali personalizzati #

Collega qualsiasi piattaforma di messaggistica o strumento di comunicazione alla piattaforma utilizzando i canali personalizzati. Questo ti permette di importare messaggi da piattaforme come widget di live chat per siti web, sistemi di posta elettronica, CRM o qualsiasi altro servizio nella tua casella di posta, e di rispondere con il tuo Agente AI.

Cosa sono i canali personalizzati? #

I canali personalizzati estendono la piattaforma oltre le sue piattaforme di messaggistica integrate (WhatsApp, SMS, Instagram, Messenger). Con i canali personalizzati, puoi:

• Ricevere messaggi da qualsiasi piattaforma esterna nella casella di posta unificata della piattaforma.
• Inviare risposte dall’app alla tua piattaforma esterna automaticamente.
• Utilizzare un Agente AI per rispondere ai messaggi da qualsiasi fonte.
• Monitorare tutte le conversazioni insieme agli altri canali in un’unica casella di posta.

Questa è la soluzione ideale per le aziende che utilizzano strumenti di comunicazione specializzati, dispongono di una piattaforma personalizzata o desiderano avere tutti i messaggi dei clienti in un unico posto.

Come funziona #

I canali personalizzati funzionano scambiando messaggi tra la tua piattaforma esterna e la piattaforma utilizzando i webhook (messaggi automatizzati inviati tra sistemi via internet). Ecco il flusso:

Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform

1. Messaggi in arrivo: La tua piattaforma esterna invia messaggi a un indirizzo web (URL). Immaginalo come se la tua piattaforma “pubblicasse” un messaggio nella casella di posta della piattaforma.
2. Elaborazione: La piattaforma crea o aggiorna il contatto, archivia il messaggio e fa sì che un Agente AI generi una risposta (se attivo).
3. Messaggi in uscita: Quando la piattaforma invia una risposta (che provenga dall’AI o sia stata digitata da te), invia il messaggio a un URL sulla tua piattaforma, dove il tuo sistema può recapitarlo all’utente finale. Le risposte possono contenere anche un file: un elemento che l’Agente AI invia dalla sua libreria multimediale, un allegato o un messaggio vocale dalla posta in arrivo, oppure un file inviato tramite API che arriva come link per il download accanto al testo.

Configurazione dei messaggi in arrivo (dalla tua piattaforma all’app) #

Per inviare messaggi dalla tua piattaforma esterna all’app, la tua piattaforma deve inviare dati al seguente URL. Il tuo sviluppatore lo riconoscerà come una richiesta POST standard (un modo comune per un sistema di inviare dati a un altro via internet).

Dove inviare i messaggi #

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY

Sostituisci YOUR_API_KEY con la tua chiave API (un codice privato che dimostra alla piattaforma che la tua piattaforma è autorizzata a inviarle messaggi). Trovala o generala in Impostazioni → Integrazioni → Chiave API.

Funziona anche una chiave con ambito limitato, purché non sia in sola lettura e le sue aree includano Messaggi. I messaggi arrivano sull’account a cui appartiene la chiave, quindi utilizza la chiave dell’account (o sotto-account) la cui casella di posta dovrebbe riceverli.

Formato del messaggio #

Invia i dati del messaggio nel seguente formato (JSON):

{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}

Cosa significa ogni parte:

• messageSid - Un ID univoco per questo specifico messaggio (creato dal tuo sistema). Utilizzato per evitare che lo stesso messaggio venga elaborato due volte.
• fromId - Chi ha inviato il messaggio (può essere un ID utente, un’email o un numero di telefono del tuo sistema).
• toId - Il tuo identificativo aziendale (può essere qualsiasi etichetta tu scelga).
• body - Il testo effettivo del messaggio.
• channel - Un’etichetta che scegli per identificare la provenienza del messaggio (ad es. “website-chat”, “email”). Diventa il nome del canale mostrato per quel contatto nella posta in arrivo e nelle notifiche.

Riferimento completo dei campi #

Reazioni con emoji #

Se la tua piattaforma supporta le reazioni con emoji (ad esempio, un pollice in su su un messaggio), inviale come reazione anziché come messaggio di testo: imposta messageType su "reaction" e inserisci solo l’emoji in customData.body.

{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}

L’assistente la gestirà quindi nel modo previsto:

• Una reazione a una domanda posta dall’assistente (ad esempio “Giovedì va bene?”) viene trattata come risposta e l’assistente risponderà.
• Una reazione a un messaggio di chiusura (ad esempio “A presto!”) termina la conversazione silenziosamente. Non viene inviata alcuna risposta.

Se la tua piattaforma trasforma le reazioni in testo come “Ha reagito con: 👍”, l’assistente visualizzerà un normale messaggio di testo e deciderà autonomamente se rispondere. L’invio del tipo di reazione evita questo problema.

Cosa si riceve in risposta #

Una richiesta riuscita restituisce:

{
  "success": true,
  "messageId": "1234567890"
}

Se qualcosa va storto, riceverai un messaggio di errore che spiega il problema:

{
  "error": "Message body cannot be empty"
}

Codici di stato #

Se imposti customData.status, l’unico valore accettato è "received" — omettilo completamente per utilizzare il valore predefinito invece di inviare qualcos’altro, altrimenti riceverai un 400.

Invio di allegati multimediali (immagini, video, file) #

Questa sezione riguarda i file in entrata (dalla tua piattaforma all’app). Per i file in uscita con una risposta, vedi Risposte con file.

Puoi includere allegati (immagini, video, audio, documenti) nei tuoi messaggi. Ci sono due modi per farlo:

Opzione 1: Link a un file #

Se il file è già ospitato online, fornisci l’URL (indirizzo web) da cui la piattaforma può scaricarlo:

{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}

Opzione 2: Incorpora il file direttamente (Base64) #

Se il file non è ospitato online, puoi incorporarlo direttamente nel messaggio come testo codificato (formato base64). Questa è una pratica comune nelle integrazioni tecniche in cui il tuo sistema genera file al volo. La piattaforma decodificherà e memorizzerà automaticamente il file:

{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}

Configurazione dei messaggi in uscita (dalla piattaforma alla tua piattaforma) #

Quando la piattaforma invia una risposta su un canale personalizzato (che provenga dall’AI o sia stata scritta da te), invia automaticamente tale risposta a un URL sulla tua piattaforma, affinché il tuo sistema possa recapitarla all’utente finale.

Imposta prima l’URL del webhook. Devi salvare l’URL del webhook del canale personalizzato prima che le risposte possano essere recapitate. Se non viene salvato alcun URL, le risposte vengono comunque generate e archiviate, ma non vengono mai inviate; inoltre, non mostreranno uno stato “Fallito”, quindi nulla nella tua casella di posta segnalerà il problema. Configura sempre l’URL del webhook prima di andare online.

Indica all’app dove inviare le risposte #

1. Nella barra laterale sinistra, clicca su Impostazioni vicino alla parte inferiore.
2. Nella barra laterale delle Impostazioni, sotto Canali, clicca su Canali.
3. Trova la scheda Canale personalizzato in fondo alla pagina (dopo Android SMS Gateway, iMessage, il widget chat del sito web, Account Twilio e Conformità normativa).
4. Inserisci l’URL del Webhook — l’URL sulla tua piattaforma a cui l’IA deve inviare i messaggi in uscita (il tuo sviluppatore lo configura per ricevere ed elaborare le risposte). Deve essere un URL HTTPS pubblico — gli indirizzi http:// e gli host non pubblici vengono rifiutati.
5. Clicca su Salva.

Cosa invia la piattaforma alla tua piattaforma #

Quando la piattaforma invia una risposta, la tua piattaforma riceverà i seguenti dati:

{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat",
  "mediaUrl": null,
  "mediaContentType": null,
  "mediaFileName": null,
  "isVoiceNote": false
}

Cosa significa ogni campo #

La tua piattaforma riceve questi dati e li utilizza per recapitare la risposta all’utente finale tramite il tuo sistema.

Risposte con file #

Una risposta contiene un file quando:

• l’Agente AI invia un elemento dalla sua libreria multimediale (una brochure, un listino prezzi, una foto),
• qualcuno allega un file o registra un messaggio vocale nella posta in arrivo,
• un messaggio viene inviato tramite API con mediaUrl e mediaContentType.

Il file arriva nella stessa chiamata webhook del testo, nei quattro campi media… sopra indicati. Una risposta di solo testo li ha tutti impostati su null (e isVoiceNote su false), quindi un ricevitore che legge solo body continua a funzionare senza modifiche.

{
  "contactId": "abc123",
  "messageId": "msg-789",
  "userId": "your-user-id",
  "body": "Here is our pricing breakdown.",
  "toId": "user-456",
  "channel": "my-live-chat",
  "mediaUrl": "https://storage.googleapis.com/.../Pricing.pdf?X-Goog-Signature=...",
  "mediaContentType": "application/pdf",
  "mediaFileName": "Pricing.pdf",
  "isVoiceNote": false
}

Recupera mediaUrl con una semplice richiesta GET (senza login, senza intestazioni aggiuntive) e inoltra il file all’utente finale tramite il tuo canale. Recapita body come didascalia o come messaggio di testo separato, a seconda di ciò che supporta il tuo canale.

Come la piattaforma traccia la consegna #

Dopo aver inviato la risposta alla tua piattaforma, la piattaforma aggiorna lo stato del messaggio:

• Inviato - La tua piattaforma ha ricevuto il messaggio correttamente.
• Non riuscito - La tua piattaforma ha restituito un errore o non è stato possibile raggiungerla. La piattaforma memorizza i dettagli dell’errore con il messaggio in modo che tu possa risolvere il problema.

Invio di messaggi dal proprio sistema all’App #

Oltre a ricevere messaggi, è possibile inviare messaggi in uscita tramite un canale personalizzato direttamente dal proprio sistema. Questa funzione è utile quando si desidera avviare una conversazione o inviare un messaggio proattivo.

Requisiti del piano. L’invio e la sincronizzazione dei messaggi tramite API richiedono un piano che includa l’accesso alle API e almeno un canale di messaggistica. Se si riceve un errore 403 “permission denied / feature not enabled”, il piano attuale non include questa funzionalità: è necessario eseguire l’upgrade del piano o contattare l’assistenza.

Dove inviare #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY

Formato del messaggio #

{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}

Campi obbligatori #

I campi opzionali (campaignId, firstName, lastName, email) funzionano allo stesso modo dei messaggi in arrivo: aiutano la piattaforma a creare o aggiornare la scheda contatto.

Cosa si riceve in risposta #

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}

Registrazione di messaggi inviati da un altro sistema #

A volte hai già inviato un messaggio a un contatto da uno strumento diverso (ad esempio, un flusso di lavoro in un’altra piattaforma) e vuoi semplicemente che la piattaforma ne sia a conoscenza, in modo che l’AI abbia il contesto completo. Questo è diverso dall’invio: la piattaforma registra il messaggio ma non lo recapita nuovamente al contatto.

Dove inviare #

POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY

Includi customData.fromId (l’ID del contatto sulla tua piattaforma) e customData.body (il testo del messaggio già inviato).

Come si comporta #

• Il messaggio viene registrato, non reinviato. La piattaforma lo archivia nella conversazione solo per contesto.
• L’AI viene messa in pausa su quel contatto per impostazione predefinita. Questo evita che il bot risponda sopra un messaggio già gestito da un umano. Per mantenere il bot attivo, passa customData.pauseAi: false.
• I nuovi contatti possono essere creati automaticamente. Includi customData.customChannel e il contatto verrà creato se non esiste ancora.
• I duplicati vengono ignorati. Se riutilizzi lo stesso messageSid, la piattaforma riconosce che il messaggio è già stato registrato e non apporta modifiche.

Requisito del piano. Come per l’invio, la registrazione dei messaggi tramite API richiede un piano che includa l’accesso alle API e almeno un canale di messaggistica. Un errore 403 “permission denied / feature not enabled” indica che il tuo piano attuale non include questa funzionalità.

Esempi dal mondo reale #

Live Chat sul sito web #

Collega un widget di live chat sul tuo sito web alla piattaforma in modo che il tuo Agente AI possa rispondere alle domande dei visitatori:

1. Un visitatore digita un messaggio nel widget della chat del tuo sito web.
2. Il widget della chat invia il messaggio alla piattaforma.
3. L’Agente IA genera una risposta.
4. La risposta viene inviata al widget della chat, che la mostra al visitatore.

Perché è utile: I visitatori del tuo sito web ottengono risposte istantanee basate sull’IA alle loro domande senza che tu debba essere online.

Email #

Instrada le conversazioni via email attraverso la piattaforma in modo che il tuo Agente IA possa rispondere alle email:

1. Configura un sistema che inoltri le email in arrivo alla piattaforma (utilizzando l’indirizzo del mittente dell’email come fromId, l’oggetto e il corpo dell’email come body, e "email" come channel).
2. L’Agente IA legge l’email e genera una risposta.
3. La risposta viene inviata al tuo sistema di posta elettronica, che la spedisce come una normale risposta email.

Perché è utile: Le domande comuni via email (prezzi, orari, disponibilità) vengono risolte istantaneamente dal tuo Agente IA.

Se il tuo sistema di posta elettronica supporta IMAP/SMTP o OAuth, il canale Email integrato potrebbe essere più semplice di un’integrazione personalizzata.

Integrazione CRM #

Collega il tuo sistema CRM (gestione delle relazioni con i clienti) esistente alla piattaforma:

1. Quando un lead invia un messaggio tramite il tuo CRM, inoltralo alla piattaforma.
2. L’Agente IA risponde e tiene traccia della conversazione.
3. La risposta dell’IA viene inviata al tuo CRM per la consegna.
4. Lo storico completo della conversazione è disponibile sia nella piattaforma che nel tuo CRM.

Perché è utile: Il tuo team di vendita ottiene risposte assistite dall’IA per i lead senza dover abbandonare il proprio CRM.

Sistema di ticket di assistenza #

Utilizza la piattaforma come primo soccorso basato sull’IA per l’assistenza clienti:

1. Il tuo sistema di ticketing inoltra i nuovi ticket di supporto alla piattaforma.
2. L’Agente IA invia una risposta iniziale (ad esempio, confermando la ricezione del ticket e ponendo domande di chiarimento).
3. La risposta viene allegata al ticket nel tuo sistema di supporto.
4. Il tuo team di supporto può rivedere ciò che ha detto l’IA e intervenire quando necessario.

Perché è utile: I clienti ricevono un riscontro immediato e un aiuto iniziale, anche al di fuori dell’orario lavorativo.

Risoluzione dei problemi #

Messaggi non ricevuti dalla piattaforma #

• Verifica che la tua chiave API sia corretta e attiva (controlla Impostazioni → Integrazioni → Chiave API).
• Assicurati di inviare una richiesta POST (non GET). Il tuo sviluppatore conoscerà la differenza.
• Controlla che il campo customData.body non sia vuoto o composto solo da spazi bianchi.
• Verifica che il campo customData.fromId sia incluso.
• Leggi il messaggio di risposta per i dettagli specifici sull’errore.

Risposte non recapitate alla tua piattaforma #

• Assicurati di aver inserito l’URL della tua piattaforma nella scheda Canale personalizzato nella pagina Canali. Se non viene salvato alcun URL, le risposte vengono generate e archiviate ma mai inviate, e non verranno contrassegnate come “Non riuscite”, quindi controlla prima questo aspetto.
• Verifica che l’URL sia accessibile pubblicamente (non dietro un login o un firewall) e che restituisca una risposta di successo.
• Solo le risposte (messaggi in uscita) vengono inviate al tuo URL: i messaggi in arrivo non attivano questa funzione.
• Controlla i dettagli dell’errore sul messaggio nella tua posta in arrivo.
• Una risposta con un file arriva nella stessa chiamata, con il link per il download in mediaUrl. Se il tuo ricevitore inoltra solo body, il file viene scartato dalla tua parte: leggi anche i campi media… (vedi Risposte con file).
• Il link mediaUrl scade dopo un’ora. Scaricalo quando arriva il webhook, non in un secondo momento da una coda.

Contatto non creato #

• Assicurati che il valore fromId sia coerente per lo stesso utente in tutti i suoi messaggi. La piattaforma utilizza questo valore per identificare i contatti — se cambia tra un messaggio e l’altro, la piattaforma creerà un nuovo contatto ogni volta.
• Includi firstName, lastName e email nel primo messaggio di un nuovo contatto per creare una scheda contatto completa.

Allegati multimediali non funzionanti #

• Per i link ai file (URL), assicurati che il file sia accessibile pubblicamente (non è richiesto alcun login per accedervi).
• Includi sempre mediaContentType quando includi mediaUrl.
• Per i file incorporati (base64), verifica che il formato sia data:MIME_TYPE;base64,ENCODED_DATA.
• Assicurati che il tipo di file specificato corrisponda al contenuto effettivo del file.

Best practice #

• Usa valori fromId coerenti. Ogni utente sulla tua piattaforma dovrebbe avere sempre lo stesso fromId. Questo assicura che la piattaforma raggruppi tutti i suoi messaggi in un’unica conversazione invece di creare contatti duplicati.
• Scegli un nome channel chiaro. Scegline uno descrittivo come "website-chat", "email" o "zendesk" in modo da poter facilmente capire da dove provengono i messaggi quando visualizzi la tua casella di posta.
• Includi i dettagli di contatto (firstName, lastName, email) nel primo messaggio di un nuovo contatto. Questo crea immediatamente una scheda contatto completa e utile.
• Implementa una logica di riprova. Fai in modo che la tua piattaforma riprovi a inviare i messaggi se la piattaforma non risponde al primo tentativo (gli intoppi di rete possono capitare).
• Usa valori messageSid univoci per ogni messaggio. Questo impedisce che lo stesso messaggio venga elaborato due volte se il tuo sistema lo invia più di una volta.
• Usa campaignId per instradare i messaggi verso diversi Agenti IA quando hai più casi d’uso (ad esempio, richieste di vendita rispetto a domande di supporto).
• Testa prima di andare live. Invia messaggi di prova in entrambe le direzioni e verifica che contatti, conversazioni e risposte dell’IA funzionino correttamente prima del lancio agli utenti reali.