Con i webhook, l'API Apps invia alla tua applicazione una notifica in tempo reale ogni volta che si verifica un evento pertinente durante una sessione di chat, ad esempio quando viene creata una chat, viene ricevuto un messaggio o una chat viene trasferita o riassegnata. Utilizza i webhook per reagire all'attività della chat man mano che si verifica, anziché eseguire il polling dell'API.
I webhook sono limitati alle sessioni di chat nell'API Apps. Contact Center AI Platform invia
tutti gli eventi webhook di chat API delle app supportate come richieste HTTP POST a un singolo
URL webhook che configuri. Non è previsto un abbonamento per evento.
Prima di iniziare
- Per configurare i webhook, devi essere un amministratore (o disporre di un ruolo con l'autorizzazione per modificare le impostazioni sviluppatore).
- Prepara un endpoint che possa ricevere richieste HTTP
POST. L'URL del webhook deve utilizzare HTTPS.
Attivare i webhook
Quando attivi i webhook, Contact Center AI Platform invia gli eventi webhook all'URL configurato e vengono visualizzati i campi URL e segreto. Quando i webhook sono disattivati, non vengono inviati eventi.
Per attivare i webhook, segui questi passaggi:
- Nel portale della piattaforma CCAI, fai clic su Impostazioni > Impostazioni sviluppatore. Se non vedi il menu Impostazioni, fai clic su Menu.
- Vai al riquadro Webhook e fai clic sul pulsante di attivazione/disattivazione Webhook per attivarlo.
Configura l'URL webhook
- In URL, inserisci l'endpoint webhook.
- Verifica che l'endpoint utilizzi HTTPS e possa ricevere richieste
POST. Contact Center AI Platform invia tutti gli eventi supportati a questo singolo URL.
Generare i secret di firma
Contact Center AI Platform firma ogni richiesta webhook in modo che la tua applicazione possa confermare che la richiesta proviene da Contact Center AI Platform. Invia la firma nell'intestazione della richiesta X-Signature e il timestamp della firma in X-Signature-Timestamp.
Puoi configurare fino a due secret di firma:
- Secret principale: il token principale utilizzato per firmare le richieste webhook.
- Segreto secondario: un secondo token facoltativo. Quando viene impostato un secret secondario, Contact Center AI Platform firma ogni richiesta con entrambi i secret, il che ti consente di ruotare i secret senza perdere eventi.
Genera ogni secret separatamente. Per generare un secret:
- Nel portale della piattaforma CCAI, fai clic su Impostazioni > Impostazioni sviluppatore. Se non vedi il menu Impostazioni, fai clic su Menu.
- Vai al riquadro Webhook.
- Nella sezione Secret principale, fai clic su Genera. Fai clic su Copia per copiare un secret e memorizzarlo in modo sicuro. Il secret completo viene mostrato solo subito dopo la generazione. Dopodiché viene mascherato.
- (Facoltativo) Nella sezione Secondary Secret (Secret secondario), fai clic su Generate (Genera). Fai clic su Copia per copiare un secret e memorizzarlo in modo sicuro.
- Conferma nella finestra di dialogo di avviso. Un nuovo secret ha effetto immediato, quindi tutto ciò che utilizza ancora un secret sostituito non funziona.
Ruota i secret di firma
Quando esiste un secret principale, diventa disponibile l'azione Ruota secret. La rotazione periodica dei segreti è una best practice per la sicurezza. Poiché Contact Center AI Platform firma ogni richiesta con i secret primario e secondario, puoi eseguire la rotazione senza interrompere la distribuzione:
- Nel portale della piattaforma CCAI, fai clic su Impostazioni > Impostazioni sviluppatore. Se non vedi il menu Impostazioni, fai clic su Menu.
- Assicurati che siano impostati sia un secret principale sia uno secondario.
- Fai clic su Ruota segreti per scambiare i segreti primario e secondario.
- Aggiorna l'applicazione per verificare le firme rispetto al nuovo segreto attivo. Durante la sovrapposizione, Contact Center AI Platform firma ogni richiesta con entrambi i segreti configurati, quindi accetta uno dei due e la pubblicazione non viene interrotta.
Salvare la configurazione
Seleziona Salva per applicare lo stato abilitato e l'URL del webhook. La generazione o la rotazione di un secret ha effetto immediato e non richiede un'operazione di salvataggio. Contact Center AI Platform inizia a pubblicare eventi dopo l'attivazione dei webhook e l'impostazione di un URL webhook e di un secret principale.
Cosa riceve la tua applicazione
Dopo aver abilitato i webhook, Contact Center AI Platform invia una richiesta HTTP POST per
ogni evento di chat supportato, come modifiche del ciclo di vita, attività dei partecipanti,
messaggi, trasferimenti, riassegnazioni, moduli web e avvisi di chiusura. Ogni
corpo della richiesta è un envelope JSON con event_type, timestamp, chat_id e
un body specifico per l'evento.