Contact Center AI Platform usa a autenticação do usuário final para identificar com segurança as pessoas que usam seu aplicativo host. Esse mecanismo garante que apenas usuários autorizados possam acessar a API da plataforma CCAI e que as sessões de chat e os dados deles permaneçam vinculados com segurança à identidade específica.
Para identificar um usuário final, o app host precisa fornecer um identificador universal exclusivo (UUID) que represente essa pessoa específica.
Como funciona a autenticação na Plataforma CCAI
A autenticação na plataforma CCAI depende de um handshake seguro usando um JSON Web Token (JWT). Um JWT é um padrão aberto usado para transmitir informações com segurança como um objeto JSON.
Confira o fluxo de autenticação padrão:
A solicitação: quando um usuário final começa a usar o atendimento ao cliente da plataforma CCAI, o SDK da plataforma CCAI solicita um JWT assinado do app host.
A assinatura: seu app host assina o JWT usando o segredo compartilhado da empresa da plataforma CCAI (
company_secret).A troca: o app host transmite o JWT assinado de volta para o SDK da plataforma CCAI. Em seguida, o SDK envia esse JWT para o servidor da plataforma CCAI.
A verificação: o servidor da CCAI Platform verifica a assinatura. Se for válido, a plataforma CCAI vai emitir um token de autenticação, concedendo ao usuário acesso à API e associando-o à conta (ou criando uma nova, se necessário).
Se o app host não fornecer um identificador no payload do JWT, a plataforma CCAI vai criar uma conta de visitante anônima para o usuário.
Pré-requisitos
Antes de implementar a autenticação, você precisa dos elementos exclusivos de autenticação do SDK. Eles identificam sua empresa com segurança para a API da plataforma CCAI.
Faça login na plataforma CCAI com uma conta de administrador.
Acesse Configurações > Configurações do desenvolvedor > Credenciais da API.
Localize o nome da chave do SDK (
sdk_key_name), a chave do SDK (sdk_key) e o segredo da empresa (company_secret).
Mantenha essas credenciais em segurança. Compartilhe apenas com sistemas e desenvolvedores autorizados.
Guia de implementação para desenvolvedores
A seção a seguir descreve como os desenvolvedores devem construir o payload do JWT e inicializar o SDK da plataforma CCAI em diferentes plataformas.
Requisitos de payload do JWT
Para transmitir as informações do usuário final à plataforma CCAI, o app host precisa criar uma carga útil JWT. O método de callback fornece um payload padrão (que pode incluir um token de push e um nome padrão), mas é possível adicionar detalhes específicos do usuário usando as seguintes chaves reservadas:
identifier(UUID opcional, mas altamente recomendado)name(opcional)email(opcional)phone(opcional, precisa usar o formato E.164)iss(opcional, nome da sua empresa)iat(obrigatório, carimbo de data/hora de emissão)exp(obrigatório, carimbo de data/hora de expiração)
Assinatura do lado do servidor (recomendada)
.Exemplo de API no servidor (Ruby on Rails)
Este exemplo mostra como assinar o payload do lado do servidor usando o framework Ruby on Rails com a gem JWT.
O código configura um endpoint de API (/api/ujet/sign) usando a gem jwt para
codificar o payload com um segredo da empresa e retornar o token codificado ao
cliente.
Suponha que o URL base do seu aplicativo host seja https://company.com/api/. Para assinar o payload da plataforma CCAI, adicione outro endpoint de API em https://company.com/api/ujet/sign.
O código adiciona uma nova rota ao arquivo de rotas do aplicativo para processar solicitações POST
para o URL /api/ujet/sign.
O arquivo ujet_controller.rb define a classe UjetController, que tem um único endpoint, sign, usado para assinar uma carga útil para a plataforma CCAI.
No código, COMPANY_SECRET é definido como o secret usado para assinar o
payload. O payload é extraído do corpo da solicitação e, em seguida, vários valores são adicionados a ele, por exemplo, UNIQUE-IDENTIFIER, nome de usuário, e-mail, telefone.
O método JWT.encode é usado para codificar o payload e o ujet_secret em um JSON Web Token (JWT), que é retornado na resposta como um objeto JSON com a chave do 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
Inicialização do lado do cliente
Siga estas diretrizes para inicializar o SDK para dispositivos móveis da plataforma de CCAI.
Assinatura do SDK do iOS
Este exemplo de assinatura de um payload do SDK do iOS faz uma solicitação POST para o servidor no URL https://your.company.com/api/ujet/sign com o payload como corpo da solicitação.
O servidor precisa retornar um token assinado em resposta, que é transmitido ao callback de sucesso na forma da chave "token" em um objeto JSON.
Se houver um erro durante a solicitação, ele será transmitido ao callback de falha.
- (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];
}
}
Assinatura do SDK do Android
Confira a seguir um exemplo de assinatura de um payload de um SDK do Android.
Este exemplo usa o Retrofit, um cliente HTTP para Android, para solicitar o payload assinado do seu servidor. A função usa um payload, um tipo de payload e um callback de token como entrada.
Se o tipo de payload for UjetPayloadType.AuthToken, ele vai criar uma instância do Retrofit, usá-la para fazer uma solicitação ao endpoint da API https://company.com/api para assinar o payload e retornar o token assinado no método onToken da instância tokenCallback.
Em caso de falha, uma mensagem de toast "Authentication failed" é exibida.
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();
}
});
}
}
Assinatura do SDK da Web
O exemplo a seguir demonstra como assinar o payload no SDK da Web fazendo uma solicitação de API ao servidor com o payload.
O servidor precisa ser configurado para processar a solicitação de API e assinar o payload usando um método seguro. O resultado é retornado à página da Web, que transmite o token assinado de volta à plataforma CCAI usando a função de 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
});
});
Autenticação no meio da sessão e reinicialização do SDK
Em alguns casos, um usuário final pode iniciar uma sessão de chat como visitante (sem autenticação) e verificar a identidade no meio da sessão (por exemplo, com um assistente virtual ou uma tela de login no meio do fluxo). Para garantir que a sessão ativa seja atualizada com segurança e associada ao usuário recém-autenticado, siga estas etapas:
Etapas para autenticação no meio da sessão
Inicialize o SDK com um identificador temporário: quando o usuário não estiver autenticado, inicialize o SDK da plataforma CCAI usando um identificador aleatório ou de convidado.
Direcione o usuário para autenticação: guie o usuário para seu fluxo de autenticação, como um assistente virtual (VA) da plataforma CCAI ou a tela de login integrada do seu app.
Atualizar o usuário final via API: depois que o usuário se autenticar (e enquanto ele ainda estiver no agente virtual ou no fluxo de autenticação), seu back-end precisa chamar a API Apps da plataforma CCAI para atualizar a sessão de chat do usuário final com o identificador verdadeiro.
Reinicialize o SDK com um novo JWT: após uma atualização bem-sucedida do back-end, gere um novo JWT para o usuário autenticado. Reinicialize o SDK da plataforma CCAI chamando o método de inicialização novamente com esse novo JWT.
Encaminhe a sessão (se estiver usando um assistente virtual): se o usuário estava se autenticando com um assistente virtual, o agente virtual precisa encaminhar o consumidor para a fila de destino final.
Exemplo (SDK da Web)
Para reinicializar, chame a função UJET.initialize novamente. Isso vai
acionar o manipulador de autenticação para buscar o novo 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
});
Por que isso é necessário?
Isso garante que todas as ações, roteamentos e históricos subsequentes sejam associados de forma segura ao usuário autenticado, em vez de uma sessão de convidado anônimo.
Ele evita o vazamento de dados e mantém registros precisos de CRM e usuários.
Tabela de resumo
| Cenário | Ação necessária |
|---|---|
| O usuário inicia autenticado | Inicialize o SDK com o UUID e o JWT verdadeiros do usuário. |
| O usuário inicia sem autenticação | Inicialize o SDK com um identificador aleatório/de visitante. |
| O usuário se autentica no meio da sessão | Atualize a plataforma de CCAI com a API, gere um novo JWT e reinicialize o SDK. |