Utilizza questa guida per creare un'integrazione di chat lato server con l'API Apps. Al termine, la tua integrazione sarà in grado di:
Autenticati nell'API Apps.
Crea o aggiorna un utente finale.
Avvia una chat per l'utente finale.
Ricevi e verifica gli eventi webhook da Contact Center AI Platform.
Inviare messaggi di testo nella chat.
Gestisci rami facoltativi come l'importazione della trascrizione pre-chat, la selezione della coda, il routing dell'agente virtuale, le deviazioni dell'escalation e gli allegati multimediali.
Termina la chat quando la conversazione è completa.
Questa guida è destinata agli sviluppatori che creano un servizio di backend che connette un'esperienza di chat di proprietà del cliente a CCAI Platform. Presuppone che tu possa creare credenziali API in CCAI Platform, ospitare un endpoint webhook HTTPS, archiviare i segreti in modo sicuro ed effettuare richieste HTTP dal tuo server.
Questa guida integra gli endpoint dell'API Chat di Google Apps. Utilizza il riferimento API per lo schema esaustivo di richiesta e risposta e questa guida per il flusso di implementazione end-to-end consigliato.
Terminologia
Al presente documento si applicano le seguenti definizioni:
Cliente: il cliente della piattaforma CCAI che implementa l'integrazione della chat nel proprio software.
Consumer: l'applicazione lato server di proprietà del cliente che effettua richieste all'API Apps e riceve eventi webhook della piattaforma CCAI.
Utente finale: la persona che utilizza il software del cliente per avviare o continuare una chat con un agente o un agente virtuale.
Chat: la risorsa di conversazione della piattaforma CCAI creata dall'API Apps.
Endpoint webhook: l'endpoint HTTPS nell'applicazione consumer che riceve gli eventi di chat dalla piattaforma CCAI.
Prima di iniziare
Prima di iniziare, assicurati di disporre di quanto segue:
Credenziali API Apps
Crea le credenziali API in CCAI Platform da Impostazioni > Impostazioni sviluppatore > Credenziali API.
Memorizza in modo sicuro il secret delle credenziali. Non esporla nel codice del browser o del client mobile.
Dettagli URL tenant
Identifica il sottodominio e il dominio di CCAI Platform.
L'URL di base dell'API Apps è:
https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1
Endpoint webhook
Ospita un endpoint HTTPS pubblico che può ricevere richieste POST da CCAI Platform.
Configura l'endpoint nelle impostazioni per sviluppatori di CCAI Platform.
Genera e memorizza i secret primario e secondario del webhook.
Configurazione della coda o del menu
Identifica la coda o il menu in cui vengono inserite le nuove chat.
Se utilizzi un agente virtuale di selezione della coda, configura questo agente virtuale e assegnalo alla coda di ingresso prima di creare chat tramite l'API.
Identità utente finale
Decidi quale identificatore stabile utilizzerà il tuo sistema per ogni utente finale.
Memorizza l'ID utente finale della piattaforma CCAI restituito dall'API Apps.
Gestione della limitazione di frequenza
- CCAI Platform limita la frequenza delle API Apps. Integra i tentativi e il backoff nell'integrazione ed evita di inviare raffiche di richieste per un singolo tenant.
Autenticazione e sicurezza dei webhook
L'integrazione utilizza due percorsi di autenticazione:
Autenticazione dell'API Apps per le richieste dal tuo server a CCAI Platform.
Verifica della firma webhook per le richieste da CCAI Platform al tuo server.
Autenticare le richieste API Apps
Le richieste utilizzano l'autenticazione di base HTTP. Crea un token API in CCAI Platform in Impostazioni > Impostazioni sviluppatore > Credenziali API e passalo nel campo password (consigliato). Se il tuo tenant utilizza il percorso di autenticazione legacy, puoi passare la chiave aziendale come nome utente e il segreto aziendale come password. Consulta il riferimento dell'API Apps per la configurazione completa dell'autenticazione. L'esempio seguente mostra come autenticare una richiesta dell'API Apps utilizzando l'autenticazione di base:
curl -X GET \
https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1/chats/{chat_id} \
-u "YOUR_SUBDOMAIN:YOUR_API_TOKEN" \
-H "Accept: application/json"
Archivia le credenziali in un archivio dei secret lato server, ruotale in base alle tue norme di sicurezza e non inviarle mai in browser o app mobile.
Verificare le richieste webhook
CCAI Platform invia gli eventi di chat all'endpoint webhook. Ogni richiesta webhook include:
X-SignatureX-Signature-Timestamp
L'intestazione X-Signature può contenere una firma principale, una firma secondaria
o entrambe:
primary=<primary_signature> secondary=<secondary_signature>
Ogni firma è un digest HMAC-SHA256 con codifica base64. Il valore firmato è l'intestazione del timestamp concatenata con il corpo della richiesta JSON non elaborato:
X-Signature-Timestamp + raw_request_body
Nel gestore webhook:
Leggi
X-SignatureeX-Signature-Timestamp.Rifiuta la richiesta se manca una delle intestazioni.
Rifiuta i timestamp obsoleti per ridurre il rischio di replay.
Leggi il corpo della richiesta non elaborato prima di analizzare JSON.
Calcola la firma prevista utilizzando ogni secret webhook attivo.
Confronta la firma ricevuta e quella prevista utilizzando un confronto a tempo costante.
Accetta la richiesta se viene trovata una corrispondenza con un segreto attivo.
La seguente implementazione di esempio in Ruby mostra come verificare le firme dei webhook UJET:
require "base64"
require "openssl"
require "active_support/security_utils"
def parse_ujet_signature(header)
header.to_s.split(/\s+/).each_with_object({}) do |part, result|
key, value = part.split("=", 2)
result[key] = value if key && value
end
end
def expected_signature(secret, timestamp, raw_body)
Base64.strict_encode64(
OpenSSL::HMAC.digest(
OpenSSL::Digest.new("sha256"),
secret,
"#{timestamp}#{raw_body}"
)
)
end
def secure_match?(received, expected)
return false if received.nil? || expected.nil?
return false unless received.bytesize == expected.bytesize
ActiveSupport::SecurityUtils.secure_compare(received, expected)
end
def verify_ujet_webhook!(request, primary_secret:, secondary_secret:)
signature_header = request.headers["X-Signature"]
timestamp = request.headers["X-Signature-Timestamp"]
return false if signature_header.nil? || timestamp.nil?
# Optional but recommended: reject stale requests.
return false if (Time.now.utc - Time.at(timestamp.to_i).utc).abs > 5.minutes
raw_body = request.body.read
signatures = parse_ujet_signature(signature_header)
expected = [
expected_signature(primary_secret, timestamp, raw_body),
expected_signature(secondary_secret, timestamp, raw_body)
].compact
received = [
signatures["primary"],
signatures["secondary"]
].compact
received.any? do |received_signature|
expected.any? do |expected_signature_value|
secure_match?(received_signature, expected_signature_value)
end
end
end
Se la verifica ha esito positivo, restituisci rapidamente una risposta di esito positivo ed elabora l'evento in modo idempotente. La distribuzione dei webhook e le risposte API possono arrivare in ordini diversi, quindi crea l'integrazione in modo che tolleri la ricezione dello stesso cambiamento di stato più di una volta senza creare record duplicati.
Flusso di integrazione
Il seguente flusso crea un utente finale, avvia una chat, riceve eventi della piattaforma CCAI, scambia messaggi e termina la chat.
Crea o aggiorna l'utente finale
Obiettivo:assicurati che la piattaforma CCAI disponga di un record utente finale prima di creare la chat.
Endpoint
Utilizza il seguente endpoint per creare o aggiornare un utente finale:
POST /apps/api/v1/end_users
Richiesta di esempio
L'esempio seguente mostra un corpo della richiesta per la creazione o l'aggiornamento di un utente finale:
{
"identifier": "customer-user-12345",
"email": "customer.user@example.com",
"name": "Customer User",
"phone": "+15551234567"
}
Cosa archiviare
Memorizza nel tuo sistema l'ID utente finale della piattaforma CCAI dalla risposta. Utilizza questo ID quando crei una chat.
Che cosa aspettarsi
Se l'utente finale non esiste, CCAI Platform crea un nuovo record.
Se esiste già un utente finale con lo stesso identificatore, CCAI Platform aggiorna il record e restituisce le informazioni dell'utente finale esistente.
Creare la chat
Obiettivo:avvia una nuova chat della piattaforma CCAI per l'utente finale.
Endpoint
Utilizza il seguente endpoint per avviare una nuova chat:
POST /apps/api/v1/chats
Richiesta di esempio
Il seguente esempio mostra un corpo della richiesta per la creazione di una chat:
{
"chat": {
"menu_id": 123,
"end_user_id": 456,
"lang": "en"
}
}
Contesto facoltativo per il routing dell'agente virtuale
Se l'agente virtuale di selezione della coda ha bisogno del contesto della tua applicazione, includi un payload di contesto quando crei la chat, come mostrato nel seguente esempio:
{
"chat": {
"menu_id": 123,
"end_user_id": 456,
"lang": "en",
"context": {
"value": {
"customer_tier": "gold",
"issue_type": "billing"
}
}
}
}
Un agente virtuale può utilizzare i valori di questo contesto per decidere a quale coda viene inviata la chat.
Che cosa aspettarsi
L'API Apps restituisce la risorsa di chat.
La piattaforma CCAI invia un evento webhook
chat_createdall'endpoint webhook configurato.La risposta API e l'evento webhook possono arrivare in qualsiasi ordine. Considerali entrambi come aggiornamenti dello stesso record di chat, identificato dall'ID chat.
Elaborare gli eventi webhook della chat
Obiettivo:mantenere l'applicazione consumer sincronizzata con lo stato della chat di CCAI Platform.
L'endpoint webhook gestisce gli eventi del ciclo di vita della chat e dei messaggi dalla piattaforma CCAI. Come minimo, memorizza:
ID chat.
Tipo di evento.
Timestamp dell'evento.
Mittente, tipo e contenuti del messaggio quando l'evento contiene un messaggio.
Eventuali dati di riassegnazione o deviazione quando l'evento descrive il comportamento di routing.
Comportamento consigliato
Verifica ogni firma webhook prima di elaborare l'evento.
Memorizza gli ID evento elaborati o una chiave evento deterministica in modo che i tentativi non creino duplicati.
Restituisci una risposta 2xx dopo aver accettato l'evento.
Elabora gli effetti collaterali a valle in modo asincrono, se possibile.
Che cosa aspettarsi
L'applicazione aggiorna lo stato della chat quando la piattaforma CCAI invia eventi come la creazione della chat, i messaggi in arrivo, i messaggi dell'agente, le modifiche di riassegnazione e il completamento della chat.
Invia un SMS
Obiettivo:invia un messaggio dell'utente finale dall'applicazione consumer alla chat della piattaforma CCAI.
Endpoint
Utilizza il seguente endpoint per inviare un messaggio di testo nella chat:
POST /apps/api/v1/chats/{chat_id}/message
Richiesta di esempio
L'esempio seguente mostra un corpo della richiesta per l'invio di un messaggio di testo:
{
"from_user_id": 456,
"message": {
"type": "text",
"content": "Hello, I need help with my order."
}
}
Che cosa aspettarsi
CCAI Platform accetta il messaggio.
Il messaggio viene visualizzato nella conversazione con l'agente o l'agente virtuale.
L'endpoint webhook riceve un evento messaggio per il messaggio, inclusi i messaggi inviati dalla tua applicazione tramite l'API Apps.
Ricevere e visualizzare i messaggi dalla piattaforma CCAI
Obiettivo: mostrare i messaggi dell'agente o dell'agente virtuale nell'esperienza di chat di proprietà del cliente.
Quando l'endpoint webhook riceve un evento di messaggio:
Verifica la firma del webhook.
Controlla se l'evento è nuovo.
Identifica la chat in base all'ID chat.
Identifica il mittente e il tipo di messaggio.
Visualizza il messaggio nell'interfaccia utente della chat di proprietà del cliente.
Rendi persistente l'evento in modo che gli aggiornamenti o i nuovi tentativi non perdano la cronologia delle conversazioni.
Che cosa aspettarsi
La UI di chat di proprietà del cliente mostra i messaggi inviati da agenti, agenti virtuali e dall'utente finale nell'ordine corretto. Se gli eventi arrivano in ordine sparso, utilizza i timestamp degli eventi e il tuo livello di persistenza per riconciliare l'ordine di visualizzazione.
Riassegnare una richiesta da un agente virtuale a un agente umano
Obiettivo:trasferire la chat dalla gestione dell'agente virtuale a una coda di operatori quando l'utente finale ha bisogno dell'aiuto di un agente.
Se l'integrazione utilizza un agente virtuale di selezione della coda, configura l'agente virtuale in modo da indirizzare le chat alla coda di destinazione. Se il server avvia il riassegnazione direttamente, utilizza l'endpoint di riassegnazione dell'API Apps.
Endpoint
Utilizza il seguente endpoint per riassegnare una chat da un agente virtuale a un agente umano:
POST /apps/api/v1/chats/{chat_id}/escalations
Richiesta di esempio
L'esempio seguente mostra un corpo della richiesta per la riassegnazione di una chat:
{
"reason": "by_end_user_ask",
"force_escalate": false
}
Che cosa aspettarsi
Se la coda di destinazione è disponibile, la chat viene assegnata a un agente.
Se la coda non è disponibile a causa di condizioni di orario non lavorativo o sovraccarico, la piattaforma CCAI può restituire o inviare opzioni di deviazione tramite il flusso della chat.
L'integrazione esegue il rendering delle opzioni di deviazione disponibili per l'utente finale.
Registrare una scelta di riassegnazione
Obiettivo:indica a CCAI Platform quale opzione di deviazione ha selezionato l'utente finale.
Quando la piattaforma CCAI offre opzioni di riduzione dell'escalation, registra la scelta dell'utente finale con l'endpoint di aggiornamento dell'escalation.
Endpoint
Utilizza il seguente endpoint per aggiornare un record di riassegnazione con una scelta di riduzione:
PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}
Valori deflection_channel supportati:
email: l'utente finale sceglie l'opzione di deviazione delle email.virtual_agent: l'utente finale sceglie di continuare con un agente virtuale.human_agent: l'utente finale sceglie di continuare ad attendere un operatore umano. Questo valore si applica solo ai trasferimenti per capacità eccessiva.
Richiesta di esempio
Il seguente esempio mostra un corpo della richiesta per la registrazione di una scelta di deviazione:
{
"deflection_channel": "email"
}
Invia a questo endpoint solo un valore deflection_channel supportato.
external_link non è un valore valido per l'endpoint di aggiornamento dell'escalation; quando
l'utente finale segue un link di deviazione esterno, la chat termina.
Che cosa aspettarsi
CCAI Platform aggiorna il record di riassegnazione e la transizione della chat in base all'opzione selezionata.
Termina la chat.
Obiettivo:chiudere la chat al termine della conversazione.
Endpoint
Utilizza il seguente endpoint per terminare una chat attiva:
PATCH /apps/api/v1/chats/{chat_id}/end
Richiesta di esempio
L'esempio seguente mostra un corpo della richiesta per terminare una chat:
{
"ended_by_user_id": 456
}
Che cosa aspettarsi
CCAI Platform termina la chat.
L'endpoint webhook riceve l'evento di stato della chat finale.
La tua applicazione contrassegna la chat come completata e smette di accettare nuovi messaggi dell'utente finale per quella chat.
Flussi avanzati
I seguenti rami sono facoltativi. Implementa solo i flussi applicabili alla tua integrazione.
Importare una trascrizione pre-chat
Utilizza questo flusso quando l'utente finale ha già avuto una conversazione nel tuo sistema prima di creare la chat della piattaforma CCAI, ad esempio una conversazione con un chatbot.
Aggiungi il payload della trascrizione quando crei la chat. La trascrizione fornisce all'agente il contesto, in modo che l'utente finale non debba ripetere le informazioni.
Il riferimento API Apps include lo schema esatto della trascrizione.
Instradare le chat con un agente virtuale di selezione della coda
Utilizza questo flusso quando la tua applicazione invia tutte le nuove chat a una coda di inserimento e consente a un agente virtuale di decidere la coda di destinazione finale.
Crea un agente virtuale per la selezione della coda.
Assegna l'agente virtuale alla coda di ingresso.
Includi il contesto quando crei la chat.
Configura l'agente virtuale per ispezionare il contesto e riassegnare la chat alla coda corretta.
Gestisci le opzioni di deviazione se la coda di destinazione non è disponibile.
Inviare allegati di foto o video
Utilizza questo flusso quando l'utente finale invia contenuti multimediali dall'interfaccia utente della chat di proprietà del cliente.
Il flusso dei contenuti multimediali è suddiviso in quattro fasi.
Fase 1: richiedi un URL di caricamento pre-firmato
Utilizza i seguenti endpoint per richiedere un URL pre-firmato per caricare una foto o un video:
POST /apps/api/v1/chats/{chat_id}/photos/upload
POST /apps/api/v1/chats/{chat_id}/videos/upload
Fase 2: carica il file nell'URL di archiviazione restituito
Includi il file e tutti i campi restituiti da CCAI Platform nella risposta presigned-upload.
Fase 3: aggiungi il file caricato alla chat
Utilizza i seguenti endpoint per aggiungere una foto o un video caricato alla chat:
POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos
Memorizza il media_id restituito da CCAI Platform. I payload dei messaggi chat fanno riferimento ai contenuti multimediali tramite
l'ID elemento multimediale.
Passaggio 4: invia i contenuti multimediali come messaggio
Utilizza il seguente endpoint per inviare un messaggio multimediale nella chat:
POST /apps/api/v1/chats/{chat_id}/message
Richiesta di esempio
L'esempio seguente mostra un corpo della richiesta per l'invio di un allegato fotografico:
{
"from_user_id": 456,
"message": {
"type": "photo",
"content": {
"media_id": 789
}
}
}
Utilizza il tipo di messaggio video e il video media_id per i messaggi video.
Inviare dati personalizzati durante una chat
Utilizza il seguente endpoint quando l'integrazione deve allegare un contesto definito dal cliente a una chat attiva:
POST /apps/api/v1/chats/{chat_id}/custom_data
Il riferimento API Apps definisce la forma esatta del payload e il comportamento delle chiavi riservate.
Aggiornare l'identità dell'utente finale durante una chat
Utilizza il seguente endpoint quando l'identità dell'utente finale cambia o diventa nota dopo l'inizio della chat:
POST /apps/api/v1/chats/{chat_id}/end_user
Ad esempio, utilizza questo endpoint quando un utente finale anonimo accede durante una chat attiva e la tua integrazione richiede a CCAI Platform di associare la chat all' identità dell'utente finale aggiornata.
Raccogliere dati CSAT o di valutazione
Utilizza i seguenti endpoint di valutazione e CSAT della chat quando l'integrazione è proprietaria dell'esperienza di valutazione post-chat:
GET /apps/api/v1/chats/{chat_id}/csat
GET /apps/api/v1/chats/{chat_id}/rating
PATCH /apps/api/v1/chats/{chat_id}/rating
Per le regole di idoneità e i payload di classificazione esatti, consulta il riferimento API Apps.