Guida all'API della piattaforma di chat

La pagina mostra come utilizzare gli endpoint di chat come descritto in Endpoint API della piattaforma di chat.

Terminologia

Per chiarezza, ecco alcune definizioni importanti da tenere a mente quando utilizzi questo documento.

  • Cliente:il cliente di Contact Center AI Platform (CCAI Platform) che implementa l'API della piattaforma di chat nel proprio software.

  • Consumatore:il software che invia richieste all'API della piattaforma di chat.

  • Utente finale:l'utente del software del cliente che sta tentando di avviare una chat con un agente.

Autenticazione webhook

L'API della piattaforma di chat comunica gli eventi che si verificano durante la chat al consumatore inviando richieste webhook al server del consumatore. I payload e i tipi di webhook sono definiti nella specifica API. Ogni richiesta webhook contiene due intestazioni, X-Signature e X-Signature-Timestamp.

X-Signature contiene una firma webhook con il seguente formato: primary=<primary_signature> secondary=<secondary_signature>

Le firme primaria e secondaria sono un digest sha256 con codifica base64 dei segreti del webhook primario o secondario, rispettivamente, con una stringa concatenata dell'intestazione X-Signature-Timestamp e del payload JSON della richiesta.

Di seguito è riportato un esempio di implementazione dell'autorizzazione per le richieste webhook in un'app Ruby on Rails di esempio:

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

Panoramica

In generale, il flusso di base di una conversazione API della piattaforma di chat dovrebbe essere il seguente. I punti chiave sono numerati e vengono fornite note per un contesto aggiuntivo. Tieni presente che il cliente è responsabile solo dell'implementazione della parte "Cliente" del diagramma, mentre Contact Center AI Platform gestisce le parti del diagramma relative al nostro sistema e all'agente. La loro inclusione nel diagramma ha lo scopo di fornire al lettore il contesto del flusso complessivo di una chat.

Viene mostrato il flusso di una conversazione API della piattaforma di chat.

Creare utenti finali

  • Le chat richiedono un ID utente finale valido al momento della creazione, il che significa che un utente finale deve esistere nel sistema Contact Center AI Platform prima della creazione di una chat.

  • Gli utenti finali vengono identificati in modo univoco dall'attributo identifier, che è un valore stringa fornito dal consumatore. È possibile che un utente finale esista già nel sistema se ha utilizzato gli SDK web o mobile. L'endpoint POST /end_users viene implementato come upsert idempotente, quindi nel caso di un utente finale esistente, il tentativo di crearlo di nuovo aggiornerà tutti i dati modificati e restituirà le informazioni dell'utente finale.

Creare chat

Per creare chat utilizzando l'API della piattaforma di chat, segui questi passaggi:

  1. Gestione dei nuovi payload di chat: il processo di inizializzazione della chat avviene in modo asincrono rispetto alla richiesta POST /chats. Per questo motivo, l'evento chat_created potrebbe essere ricevuto prima o dopo la risposta dell'API dall'endpoint di creazione di POST /chats. Ti consigliamo di gestire l'evento chat_created e la risposta dell'API di creazione della chat in modo idempotente per evitare bug nel consumer.

  2. Creazione di chat con trascrizioni:l'API della piattaforma di chat supporta la creazione di una chat con la trascrizione di una conversazione esistente, per uno scenario in cui una chat si svolge all'interno della piattaforma di un cliente, ad esempio con un chatbot, prima di essere inviata a Contact Center AI Platform. In questo modo, l'agente che risponde alla chat dispone di informazioni aggiuntive sulla sessione di chat e si evita che l'utente finale si ripeta. Per il formato del payload della trascrizione, consulta chat_platform_openapi.yaml.

L'agente virtuale di selezione della coda

Per semplificare la selezione dei menu per i consumer di API, l'API della piattaforma di chat è progettata per essere utilizzata insieme a un agente virtuale Dialogflow per aiutare a posizionare in coda le nuove chat.

Per configurare l'agente virtuale, devi svolgere i seguenti passaggi:

  1. Crea un agente virtuale designato a questo scopo e assegnagli una coda. Tutte le nuove chat create dall'API della piattaforma di chat devono essere create in questa coda. La creazione e la configurazione di un nuovo agente virtuale non rientrano nell'ambito di questo documento.

  2. Quando crei una nuova chat con l'endpoint POST o chats, includi un payload di contesto personalizzato che includa alcune informazioni sulla chat creata che l'agente virtuale può utilizzare per determinare a quale coda deve essere indirizzata la chat. Il payload di contesto può contenere qualsiasi dato personalizzato definito dal cliente, ma deve avere il seguente formato per essere accessibile all'agente virtuale assegnato alla coda.

    • Esempio: "context": {"value": {"foo": "bar" } } consentirebbe all'agente virtuale di leggere $session.params.context.foo con un valore di bar.

  3. Utilizzando i dati contenuti nel campo di contesto, l'agente virtuale (in base alla configurazione del cliente) riassegna la chat alla coda selezionata. Se non è disponibile alcun agente nella coda di destinazione (ad esempio in uno scenario in cui una coda è fuori orario o ha superato la capacità), la riassegnazione viene deviata e il consumatore riceve un webhook che indica il motivo del reindirizzamento e le opzioni di reindirizzamento disponibili.

Deviazioni delle riassegnazioni: le riassegnazioni delle chat nell'API della piattaforma di chat supportano le seguenti opzioni di deviazione, se configurate nel portale Contact Center AI Platform:

  • Email: chiedi all'utente finale di inviare un'email all'assistenza e termina la chat. Quando un utente finale seleziona questa opzione, dopo l'invio dell'email, il cliente dovrà contrassegnare la chat come deviata e terminata utilizzando l'endpoint PATCH /chats/:id con i seguenti parametri nel corpo della richiesta: "status": "finished" , "escalation_id": &lt;id of escalation> , e "deflection_channel": "email"

  • Continua con l'agente virtuale: tecnicamente questa è un'opzione di deflezione valida, ma non ha senso utilizzare l'agente virtuale di selezione della coda perché l'agente virtuale cercherebbe di riassegnare la chat.

  • Continua ad attendere l'agente: questa opzione può essere utilizzata solo per le riassegnazioni con motivo over_capacity. Se l'utente finale sceglie questa opzione, aggiorna la deviazione dell'escalation con PATCH chats/:id/escalations/:id with deflection_channel=human_agent

    • Link di self-service esterno: avvisa l'utente finale che la selezione di un link fornito nel self-service terminerà la chat. Se viene selezionato un link, termina la chat e utilizza external_link per il parametro deflection_channel

Inviare e ricevere messaggi

Per inviare o ricevere messaggi:

  1. Contenuto di testo: per inviare messaggi di testo, utilizza l'endpoint POST /chats/:id/message come definito nella documentazione dell'API. Per ricevere messaggi, ascolta l'evento webhook message_received. Tieni presente che il consumer dell'API riceverà un evento message_received per tutti i messaggi inviati utilizzando l'API, inclusi i messaggi inviati dall'utente finale.

  2. Contenuti di foto e video: i contenuti di foto e video vengono inviati recuperando un URL di caricamento pre-firmato per un servizio Cloud Storage configurato da Contact Center AI Platform, caricandoli nel servizio di archiviazione e poi inviando l'URL di archiviazione in un payload del messaggio alla Contact Center AI Platform.

    1. Recupero dell'URL pre-firmato: recupera un URL di caricamento pre-firmato da Contact Center AI Platform utilizzando POST /v1/chats/:chat_id/photos/upload o POST /v1/chats/:chat_id/videos/upload endpoints. Questo endpoint restituisce un URL firmato, insieme a una raccolta di campi da inoltrare al servizio di archiviazione durante il caricamento del file. I caricamenti pre-firmati presentano le seguenti limitazioni:

      • Content-Type è image/jpeg per le foto e video/mp4 per i video.

      • La dimensione massima della foto è 2 MB. La dimensione massima del video è 20 MB.

      • Il tempo di scadenza è di 5 minuti.

      • Il cliente deve ridimensionare e regolare l'orientamento della foto prima del caricamento.

      • Ogni URL pre-firmato è per una singola foto o un singolo video. Per inviare più allegati, devi richiedere un URL pre-firmato per ciascuno.

    2. Caricamento del file multimediale: per caricare il file multimediale, invia una richiesta POST all'URL pre-firmato recuperato nel passaggio 2a con quanto segue nel corpo della richiesta:

      • "file": il file da caricare

      • Tutti i campi restituiti nell'oggetto fields nella richiesta di URL pre-firmato.

    3. Aggiunta del file multimediale alla chat: per aggiungere il file multimediale alla chat, utilizza l'endpoint POST /chats/:id/photos o POST /chats/:id/videos. Tieni presente che l'endpoint delle foto supporta l'invio di un array di foto, mentre l'endpoint dei video supporta un solo video alla volta.

      • Il parametro del corpo della richiesta s3_path deve avere lo stesso valore del campo key della risposta dell'URL pre-firmato.

      • Se la richiesta ha esito positivo, vengono restituiti due campi. Ti consigliamo di salvare o memorizzare nella cache una mappatura di media_id all'URL nel consumer API, poiché tutti i contenuti multimediali nei messaggi di chat faranno riferimento solo a media_id.

        • url: l'URL di S3 o Cloud Storage di sola lettura in cui si trova il file.

        • media_id: l'ID del file multimediale in Contact Center AI Platform. Questo è l'ID con cui verrà fatto riferimento ai contenuti multimediali nei payload della chat.

    4. Invio del file multimediale come messaggio di chat: per inviare il file multimediale come messaggio di chat, invia il seguente payload a POST /chats/:id/message endpoint:

    {
  "from_user_id": <id of end user>,
  "message":
    "type": <"photo" or "video">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}

Aspettati chiavi JSON non riconosciute nelle risposte API

Tutti gli aggiornamenti delle API sono compatibili con le versioni precedenti. Ci riserviamo il diritto di introdurre nuove chiavi JSON nelle risposte API esistenti in qualsiasi momento. Ti consigliamo di gestire le risposte in modo difensivo ignorando le chiavi non riconosciute per mantenere la funzionalità continua.