Contact Center AI Platform utilizza l'autenticazione dell'utente finale per identificare in modo sicuro le persone che utilizzano la tua app host. Questo meccanismo garantisce che solo gli utenti autorizzati possano accedere all'API CCAI Platform e che le loro sessioni di chat e i loro dati rimangano collegati in modo sicuro alla loro identità specifica.
Per identificare un utente finale, l'app host deve fornire un identificatore univoco universale (UUID) che rappresenti quella persona specifica.
Come funziona l'autenticazione in CCAI Platform
L'autenticazione nella piattaforma CCAI si basa su un handshake sicuro che utilizza un token web JSON (JWT). Un JWT è uno standard aperto utilizzato per trasmettere in modo sicuro informazioni come oggetto JSON.
Ecco il flusso di autenticazione standard:
La richiesta: quando un utente finale inizia a utilizzare il servizio clienti della piattaforma CCAI, l'SDK della piattaforma CCAI richiede un JWT firmato dalla tua app host.
La firma: l'app host firma il JWT utilizzando il segreto aziendale condiviso della piattaforma CCAI (
company_secret).Lo scambio: l'app host passa il JWT firmato all'SDK CCAI Platform. L'SDK invia quindi questo JWT al server della piattaforma CCAI.
La verifica: il server CCAI Platform verifica la firma. Se è valido, CCAI Platform emette un token di autenticazione, concedendo all'utente l'accesso all'API e associandolo al suo account (o creandone uno nuovo se non esiste).
Se l'app host non fornisce un identificatore nel payload JWT, CCAI Platform creerà un account ospite anonimo per l'utente.
Prerequisiti
Prima di implementare l'autenticazione, devi disporre degli elementi di autenticazione SDK unici. Identificano in modo sicuro la tua azienda nell'API CCAI Platform.
Accedi a CCAI Platform con un account amministratore.
Vai a Impostazioni > Impostazioni sviluppatore > Credenziali API.
Individua il nome della chiave SDK (
sdk_key_name), la chiave SDK (sdk_key) e il segreto dell'azienda (company_secret).
Conserva queste credenziali in modo sicuro. Condividili solo con sistemi e sviluppatori autorizzati.
Guida all'implementazione per gli sviluppatori
La sezione seguente descrive come gli sviluppatori devono costruire il payload JWT e inizializzare l'SDK CCAI Platform su piattaforme diverse.
Requisiti del payload JWT
Per trasmettere le informazioni dell'utente finale a CCAI Platform, la tua app host deve creare un payload JWT. Il metodo di callback fornisce un payload predefinito (che può includere un token push e un nome predefinito), ma puoi aggiungere dettagli specifici dell'utente utilizzando le seguenti chiavi riservate:
identifier(facoltativo, ma UUID vivamente consigliato)name(facoltativo)email(facoltativo)phone(facoltativo, deve utilizzare il formato E.164)iss(facoltativo, nome della tua azienda)iat(obbligatorio, emesso al momento del timestamp)exp(obbligatorio, timestamp di scadenza)
Firma lato server (opzione consigliata)
Esempio di API sul server (Ruby on Rails)
Questo esempio mostra come firmare il payload lato server utilizzando il framework Ruby on Rails con la gemma JWT.
Il codice configura un endpoint API (/api/ujet/sign) utilizzando il gem jwt per codificare il payload con un segreto aziendale e restituire il token codificato al client.
Supponiamo che l'URL di base dell'applicazione host sia https://company.com/api/. Per firmare il payload per la piattaforma CCAI, puoi aggiungere un altro endpoint API all'indirizzo https://company.com/api/ujet/sign.
Il codice aggiunge una nuova route al file delle route dell'applicazione per gestire le richieste POST
all'URL /api/ujet/sign.
Il file ujet_controller.rb definisce la classe UjetController, che ha un singolo endpoint, sign, utilizzato per firmare un payload per la piattaforma CCAI.
Nel codice, COMPANY_SECRET è definito come il secret utilizzato per firmare il
payload. Il payload viene estratto dal corpo della richiesta e poi vengono aggiunti vari valori, ad esempio UNIQUE-IDENTIFIER, nome utente, email, telefono.
Il metodo JWT.encode viene utilizzato per codificare il payload e ujet_secret in
un JSON Web Token (JWT), che viene poi restituito nella risposta come oggetto JSON
con la chiave del token.
# routes.rb
post 'ujet/sign' => "ujet#sign"
# ujet_controller.rb
class UjetController
def sign
# In production, securely store and call your secret (e.g., via environment variables)
ujet_secret = "COMPANY_SECRET"
payload = body["payload"]
payload["identifier"] = "UNIQUE-IDENTIFIER"
payload["name"] = "user name"
payload["email"] = "test@email.com"
payload["phone"] = "" # E.164 format
payload["iss"] = "YOUR_COMPANY_NAME"
payload["iat"] = Time.now.to_i
payload["exp"] = Time.now.to_i + 10.minutes # Valid for 10 minutes
token = JWT.encode(payload, ujet_secret)
render json: {token: token}
end
end
Inizializzazione lato client
Segui queste linee guida per inizializzare l'SDK mobile di CCAI Platform.
Firma dall'SDK iOS
Questo esempio di firma di un payload dall'SDK per iOS invia una richiesta POST al server all'URL https://your.company.com/api/ujet/sign con il payload come corpo della richiesta.
Il server dovrebbe restituire un token firmato in risposta, che viene poi trasmesso al callback di successo sotto forma di chiave "token" in un oggetto JSON.
Se si verifica un errore durante la richiesta, questo viene passato al callback di errore.
- (void)signPayload:(NSDictionary *)payload payloadType:(UjetPayloadType)payloadType success:(void (^)(NSString *))success failure:(void (^)(NSError *))failure
{
if (payloadType == UjetPayloadAuthToken) {
NSURLSessionConfiguration *sessionConfiguration = [NSURLSessionConfiguration defaultSessionConfiguration];
NSURLSession *session = [NSURLSession sessionWithConfiguration:sessionConfiguration];
NSMutableURLRequest *mutableRequest = [[NSMutableURLRequest alloc] init];
mutableRequest.URL = [NSURL URLWithString:@"https://your.company.com/api/ujet/sign"];
mutableRequest.HTTPMethod = @"POST";
NSError *error;
NSDictionary *data = @{@"payload": payload};
mutableRequest.HTTPBody = [NSJSONSerialization dataWithJSONObject:data options:0 error:&error];
NSURLSessionDataTask *task = [session dataTaskWithRequest:mutableRequest completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if(error) {
failure(error);
}
else {
NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
success(json[@"token"]);
}
}];
[task resume];
}
}
Firma dall'SDK Android
Di seguito è riportato un esempio di firma di un payload da un SDK Android.
Questo esempio utilizza Retrofit, un client HTTP per Android, per richiedere il payload firmato dal tuo server. La funzione accetta un payload, un tipo di payload e un callback del token come input.
Se il tipo di payload è UjetPayloadType.AuthToken, crea un'istanza Retrofit, la utilizza per inviare una richiesta all'endpoint API https://company.com/api per firmare il payload e restituisce il token firmato nel metodo onToken dell'istanza tokenCallback.
In caso di errore, viene visualizzato un messaggio di notifica "Authentication failed".
public void onSignPayloadRequest(Map<String, Object> payload, UjetPayloadType ujetPayloadType, final UjetTokenCallback tokenCallback) {
if (ujetPayloadType == UjetPayloadType.AuthToken) {
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://company.com/api/")
.addConverterFactory(GsonConverterFactory.create())
.build();
AuthService authService = retrofit.create(AuthService.class);
Call<AuthToken> authenticate = authService.authenticate(new AuthRequest(payload));
authenticate.enqueue(new Callback<AuthToken>() {
@Override
public void onResponse(Call<AuthToken> call, Response<AuthToken> response) {
if (response.isSuccessful()) {
AuthToken authToken = response.body();
tokenCallback.onToken(authToken.getToken());
} else {
Toast.makeText(ExampleApplication.this, "Authentication failed", Toast.LENGTH_SHORT).show();
}
}
@Override
public void onFailure(Call<AuthToken> call, Throwable t) {
Toast.makeText(ExampleApplication.this, "Authentication failed", Toast.LENGTH_SHORT).show();
}
});
}
}
Firma dall'SDK web
L'esempio seguente mostra come firmare il payload nell'SDK web effettuando una richiesta API al server con il payload.
Il server deve essere configurato per gestire la richiesta API e firmare il payload utilizzando un metodo sicuro. Il risultato viene poi restituito alla pagina web, che passa il token firmato alla piattaforma CCAI utilizzando la funzione di callback.
$(function() {
UJET.initialize({
// ... other parameters
handlers: {
authentication(callback) {
$.ajax({
type: 'POST',
url: 'https://company.com/api/ujet/sign',
data: JSON.stringify({
payload: {
identifier: 'UNIQUE-Identifier',
name: 'Test user'
}
}),
success: function(result) {
callback({
token: result.token,
user: {
identifier: 'UNIQUE-IDENTIFIER',
name: 'Test user'
}
});
}
});
}
}
}).then(function() {
// successfully initialized
}).catch(function(error) {
// Handle initialization error
});
});
Autenticazione a metà sessione e reinizializzazione dell'SDK
In alcuni casi, un utente finale può avviare una sessione di chat come ospite (non autenticato) e verificare la propria identità a metà sessione (ad es. tramite un assistente virtuale o una schermata di accesso a metà flusso). Per assicurarti che la sessione attiva venga aggiornata in modo sicuro e associata all'utente appena autenticato, segui questi passaggi:
Passaggi per l'autenticazione a metà sessione
Inizializza l'SDK con un identificatore temporaneo: quando l'utente non è autenticato, inizializza l'SDK CCAI Platform utilizzando un identificatore casuale o ospite.
Indirizza l'utente all'autenticazione: guida l'utente nel flusso di autenticazione, ad esempio un assistente virtuale (VA) di CCAI Platform o la schermata di accesso integrata della tua app.
Aggiorna l'utente finale tramite l'API: dopo che l'utente ha eseguito l'autenticazione (e mentre si trova ancora nell'agente virtuale o nel flusso di autenticazione), il backend deve chiamare l'API CCAI Platform Apps per aggiornare la sessione di chat dell'utente finale con il suo vero identificatore.
Reinizializza l'SDK con un nuovo JWT: dopo un aggiornamento del backend riuscito, genera un nuovo JWT per l'utente autenticato. Inizializza nuovamente l'SDK CCAI Platform chiamando di nuovo il metodo di inizializzazione con questo nuovo JWT.
Riassegna la sessione (se utilizzi l'agente virtuale): se l'utente si è autenticato utilizzando un assistente virtuale, l'agente virtuale deve ora riassegnare il consumatore alla coda di destinazione finale.
Esempio (SDK web)
Per reinizializzare, chiama di nuovo la funzione UJET.initialize. In questo modo
il gestore dell'autenticazione recupererà il nuovo token.
// Call this after successful authentication and the CCAI Platform Apps API update
UJET.initialize({
// ...include your existing parameters
handlers: {
authentication(callback) {
// Fetch the new JWT for the newly authenticated user
$.ajax({
type: 'POST',
url: 'https://your.company.com/api/ujet/sign',
data: JSON.stringify({
payload: {
identifier: 'AUTHENTICATED-USER-UUID',
name: 'Authenticated User Name'
}
}),
success: function(result) {
callback({
token: result.token,
user: {
identifier: 'AUTHENTICATED-USER-UUID',
name: 'Authenticated User Name'
}
});
}
});
}
}
}).then(function() {
// SDK successfully reinitialized with the authenticated user
}).catch(function(error) {
// Handle reinitialization errors
});
Perché è necessario?
In questo modo, tutte le azioni, il routing e la cronologia successivi vengono associati in modo sicuro all'utente autenticato, anziché a una sessione ospite anonima.
Impedisce la perdita di dati e mantiene accurati i record CRM e utente.
Tabella riepilogativa
| Scenario | Azione richiesta |
|---|---|
| L'utente inizia l'autenticazione | Inizializza l'SDK con l'UUID e il JWT reali dell'utente. |
| L'utente inizia senza autenticazione | Inizializza l'SDK con un identificatore ospite/casuale. |
| L'utente si autentica a metà sessione | Aggiorna CCAI Platform con l'API, genera un nuovo JWT e reinizializza l'SDK. |