Guida all'integrazione dell'API della piattaforma di chat

Utilizza questa guida per creare un'integrazione di chat lato server con l'API Apps. Al termine, l'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 nella chat.

• Gestisci i rami facoltativi, come l'importazione della trascrizione pre-chat, il routing dell'agente virtuale per la selezione della coda, le deviazioni dell'escalation e gli allegati multimediali.

• Termina la chat quando la conversazione è terminata.

Questa guida è rivolta agli sviluppatori che stanno creando un servizio di backend che connette un'esperienza di chat di proprietà del cliente alla piattaforma CCAI. Si presuppone che tu possa creare credenziali API nella piattaforma CCAI, ospitare un endpoint webhook HTTPS, archiviare i secret in modo sicuro ed effettuare richieste HTTP dal tuo server.

Questa guida integra gli endpoint dell'API Chat di Apps. Utilizza il Riferimento API per lo schema di richiesta e lo schema di risposta esaustivi e questa guida per il flusso di implementazione end-to-end consigliato.

Terminologia

Le seguenti definizioni si applicano a questo documento:

• Cliente: il cliente della piattaforma CCAI che sta implementando l'integrazione della chat nel proprio software.

• Consumer: l'applicazione lato server di proprietà del cliente che effettua richieste all'API Apps e riceve gli 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 del 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 nella piattaforma CCAI da Impostazioni > Impostazioni sviluppatore > Credenziali API.

  • Archivia il secret delle credenziali in modo sicuro. 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 del webhook

  • Ospita un endpoint HTTPS pubblico che può ricevere richieste POST dalla piattaforma CCAI.

  • Configura l'endpoint nelle impostazioni per gli sviluppatori della piattaforma CCAI.

  • Genera e archivia i secret primari e secondari 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 per la selezione della coda, configuralo 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 dell'API Apps. Crea nuovi tentativi e backoff nella tua integrazione ed evita di inviare burst di richieste per un singolo tenant.

Autenticazione e sicurezza dei webhook

La tua integrazione utilizza due percorsi di autenticazione:

• Autenticazione dell'API Apps per le richieste dal tuo server alla piattaforma CCAI.

• Verifica della firma del webhook per le richieste dalla piattaforma CCAI al tuo server.

Autentica le richieste API di 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 secret aziendale come password. Per la configurazione completa dell'autenticazione, consulta il Riferimento API Apps. L'esempio seguente mostra come autenticare una richiesta 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 di secret lato server, ruotale in base alle tue policy di sicurezza e non inviarle mai nelle app mobile o del browser.

Verifica le richieste webhook

La piattaforma CCAI invia gli eventi di chat all'endpoint webhook. Ogni richiesta webhook include:

• X-Signature

• X-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 al corpo della richiesta JSON non elaborato:

X-Signature-Timestamp + raw_request_body

Nel gestore del webhook:

1. Leggi X-Signature e X-Signature-Timestamp.

2. Rifiuta la richiesta se manca una delle intestazioni.

3. Rifiuta i timestamp obsoleti per ridurre il rischio di replay.

4. Leggi il corpo della richiesta non elaborato prima di analizzare il JSON.

5. Calcola la firma prevista utilizzando ogni secret del webhook attivo.

6. Confronta la firma ricevuta e quella prevista utilizzando un confronto a tempo costante.

7. Accetta la richiesta se un secret attivo corrisponde.

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 va a buon fine, restituisci rapidamente una risposta di esito positivo ed elabora l'evento in modo idempotente. La consegna dei webhook e le risposte dell'API possono arrivare in ordini diversi, quindi crea l'integrazione in modo che tolleri la ricezione della stessa modifica di stato più di una volta senza creare record duplicati.

Il 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 dell'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

Esempio di richiesta

L'esempio seguente mostra il corpo di una richiesta per la creazione o l'aggiornamento di un utente finale:

{
  "identifier": "customer-user-12345",
  "email": "[e-mail]",
  "name": "Customer User",
  "phone": "[phone]"
}

Cosa archiviare

Memorizza l'ID utente finale della piattaforma CCAI dalla risposta nel tuo sistema. Utilizza questo ID quando crei una chat.

Che cosa aspettarsi

• Se l'utente finale non esiste, la piattaforma CCAI 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.

Crea la chat

Obiettivo: avviare 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

Esempio di richiesta

L'esempio seguente mostra il corpo di una richiesta per la creazione di una chat:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en"
  }
}

Contesto facoltativo per il routing degli agenti virtuali

Se l'agente virtuale di selezione della coda ha bisogno del contesto della tua applicazione, includi un payload del contesto quando crei la chat, come mostrato nell'esempio seguente:

{
  "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 quel contesto per decidere quale coda riceve la chat.

Che cosa aspettarsi

• L'API Apps restituisce la risorsa di chat.

• La piattaforma CCAI invia un evento webhook chat_created all'endpoint webhook configurato.

• La risposta dell'API e l'evento webhook possono arrivare in qualsiasi ordine. Considera entrambi come aggiornamenti allo stesso record della chat, con chiave basata sull'ID chat.

Elabora gli eventi webhook di Chat

Obiettivo: mantenere l'applicazione consumer sincronizzata con lo stato della chat di CCAI Platform.

L'endpoint webhook gestisce il ciclo di vita della chat e gli eventi dei messaggi dalla piattaforma CCAI. Come minimo, archivia:

• ID chat.

• Tipo di evento.

• Timestamp dell'evento.

• Mittente, tipo e contenuto del messaggio quando l'evento contiene un messaggio.

• Eventuali dati di escalation o deviazione quando l'evento descrive il comportamento di routing.

Comportamento consigliato

• Verifica ogni firma del webhook prima di elaborare l'evento.

• Archivia gli ID evento elaborati o una chiave evento deterministica in modo che i nuovi tentativi non creino duplicati.

• Restituisci una risposta 2xx dopo aver accettato l'evento.

• Elabora gli effetti collaterali downstream in modo asincrono, se possibile.

Che cosa aspettarsi

La tua 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 all'escalation e il completamento della chat.

Invia un SMS

Obiettivo: inviare 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

Esempio di richiesta

L'esempio seguente mostra il corpo di una richiesta per l'invio di un messaggio:

{
  "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 del webhook riceve un evento di messaggio per il messaggio, inclusi i messaggi inviati dalla tua applicazione tramite l'API Apps.

Ricevi e visualizza 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 del webhook riceve un evento di messaggio:

1. Verifica la firma del webhook.

2. Controlla se l'evento è nuovo.

3. Identifica la chat tramite l'ID chat.

4. Identifica il mittente e il tipo di messaggio.

5. Esegui il rendering del messaggio nell'interfaccia utente della chat di proprietà del cliente.

6. Rendi persistente l'evento in modo che gli aggiornamenti o i nuovi tentativi non perdano la cronologia delle conversazioni.

Che cosa aspettarsi

La UI della chat di proprietà del cliente mostra i messaggi inviati dagli agenti, dagli 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.

Assegnazione di un caso da un agente virtuale a un agente umano

Obiettivo: spostare la chat dalla gestione dell'agente virtuale a una coda umana quando l'utente finale ha bisogno dell'aiuto di un agente.

Se la tua integrazione utilizza un agente virtuale per la selezione della coda, configuralo per instradare le chat alla coda di destinazione. Se il tuo server avvia l'escalation direttamente, utilizza l'endpoint di escalation dell'API Apps.

Endpoint

Utilizza il seguente endpoint per assegnare una chat da un agente virtuale a un agente umano:

POST /apps/api/v1/chats/{chat_id}/escalations

Esempio di richiesta

L'esempio seguente mostra il corpo di una richiesta per riassegnare una chat:

{
  "reason": "by_end_user_ask",
  "force_escalate": false
}

Che cosa aspettarsi

• Se la coda di destinazione è disponibile, la chat viene spostata verso la gestione da parte dell'agente.

• Se la coda non può accettare la chat e sono configurate alternative di deviazione, CCAI Platform mantiene la chat con l'agente virtuale e invia un evento webhook escalation_deflected contenente le alternative disponibili per l'utente finale. Le alternative non vengono mai visualizzate nella risposta all'escalation.

• La tua integrazione mostra all'utente finale le opzioni di deviazione disponibili.

Registra una scelta di deviazione dell'escalation

Obiettivo: comunica alla piattaforma CCAI l'opzione di deviazione selezionata dall'utente finale.

Quando la piattaforma CCAI offre opzioni di deviazione 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 escalation con una scelta di deviazione:

PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}

Valori deflection_channel supportati:

• email: l'utente finale sceglie l'opzione di deviazione email.

• virtual_agent: l'utente finale sceglie di continuare con un agente virtuale.

• human_agent: l'utente finale sceglie di continuare ad attendere un agente umano. Questo valore si applica solo alle deviazioni per sovracapacità.

Esempio di richiesta

L'esempio seguente mostra il corpo di una richiesta per registrare una scelta di deviazione:

{
  "deflection_channel": "email"
}

Invia solo un valore deflection_channel supportato a questo endpoint. 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 registra la scelta relativa all'escalation. La registrazione di una scelta non instrada la chat: l'integrazione agisce sulla selezione, ad esempio chiudendo la chat per una deviazione email o inviando una nuova escalation con force_escalate: true per una scelta di attesa.

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

Esempio di richiesta

L'esempio seguente mostra il corpo di una richiesta per terminare una chat:

{
  "ended_by_user_id": 456
}

Che cosa aspettarsi

• CCAI Platform termina la chat.

• L'endpoint webhook riceve l'evento finale dello stato della chat.

• La tua applicazione contrassegna la chat come completata e smette di accettare nuovi messaggi dell'utente finale per quella chat.

Se la chat termina perché l'utente finale ha selezionato un'opzione di deviazione, non utilizzare questo endpoint al posto della registrazione della selezione. Registra prima la scelta sull'escalation o registrala e chiudi la chat in un'unica richiesta con PATCH /apps/api/v1/chats/{chat_id}, fornendo escalation_id e deflection_channel insieme allo stato. Una chat che termina senza una scelta registrata lascia la scelta non registrata nell'escalation e assente dai report sui risultati della deviazione.

Flussi avanzati

I seguenti rami sono facoltativi. Implementa solo i flussi applicabili alla tua integrazione.

Importa una trascrizione pre-chat

Utilizza questo flusso quando l'utente finale ha già avuto una conversazione nel tuo sistema prima che tu creassi 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.

Instrada 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 ingresso e consente a un agente virtuale di decidere la coda di destinazione finale.

1. Crea un agente virtuale per la selezione della coda.

2. Assegna l'agente virtuale alla coda di ingresso.

3. Includi il contesto quando crei la chat.

4. Configura l'agente virtuale in modo che esamini il contesto e inoltri la chat alla coda corretta.

5. 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 dalla UI di chat di proprietà del cliente.

Il flusso multimediale prevede 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 dalla piattaforma CCAI nella risposta presigned-upload.

Fase 3: aggiungi il file caricato alla chat

Utilizza i seguenti endpoint per aggiungere una foto o un video caricati alla chat:

POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos

Archivia il media_id restituito dalla piattaforma CCAI. I payload dei messaggi chat fanno riferimento ai contenuti multimediali tramite l'ID elemento multimediale.

Fase 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

Esempio di richiesta

L'esempio seguente mostra il corpo di una richiesta per l'invio di un allegato fotografico:

{
  "from_user_id": 456,
  "message": {
    "type": "photo",
    "content": "Photo of the damaged item",
    "media_id": 789
  }
}

L'endpoint accetta type, content e media_id come valori semplici; un oggetto nidificato fornito in content viene ignorato e il riferimento multimediale viene perso. Utilizza il tipo di messaggio video e il video media_id per i videomessaggi. media_id è un elemento di pari livello di content.

Inviare dati personalizzati durante una chat

Utilizza il seguente endpoint quando la tua 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.

Aggiorna 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 che la piattaforma CCAI associ la chat all'identità dell'utente finale aggiornata.

Raccogli i dati relativi alla CSAT o alla valutazione

Utilizza i seguenti endpoint di valutazione e CSAT della chat quando la tua 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 valutazione esatti, consulta il riferimento API Apps.