Integre Bots de Einstein en cualquier canal con el nuevo SDK y Framework ☁️

Esta es una traducción que desde EGA Futura ofrecemos como cortesía a toda la Ohana y comunidad de programadores , consultores , administradores y arquitectos de Salesforce para toda Iberoamérica .

El enlace a la publicación original, lo encontrarás al final de este artículo.

…

Einstein Bots es una solución de chatbot conversacional que funciona con Einstein AI Platform de Salesforce. Su trabajo es interactuar con los clientes y brindarles la información que necesitan rápidamente sin intervención humana. También puede manejar tareas simples y repetitivas, lo que libera a los agentes para que manejen casos más complejos.

En Spring '22, lanzamos la API de la plataforma Einstein Bots (Beta) para ayudar a los clientes a aprovechar el poder de Einstein Bots en cualquier canal digital. En Summer '22, pusimos a disposición Java SDK y Channel Connector de código abierto para simplificar la experiencia del desarrollador de bots. Esto le brinda las herramientas que necesita para integrar fácilmente Einstein Bots en cualquiera de sus canales de conversación además de los canales de participación digital existentes que son compatibles con Service Cloud.

En esta publicación, veremos cómo puede usar la API de la plataforma Einstein Bots, y también cubriremos cómo usar el SDK y sus beneficios. Consulte esta publicación de blog anterior para familiarizarse aún más con laAPI de la plataforma Einstein Bots .

Uso de la API de la plataforma Einstein Bots

La API de la plataforma Einstein Bots es una API REST y puede usarla sin el SDK. La Guía del cliente de la API de la plataforma Einstein Bots proporciona instrucciones sobre cómo integrar Einstein Bots con su canal mediante CURL o Postman. Veamos el código Java real necesario para trabajar con la API de la plataforma Einstein Bots.

1. Cree el token web JSON (JWT)

Los Bots de Einstein requieren que las solicitudes se autentiquen mediante OAuth. Se puede usar cualquier flujo de OAuth para obtener el token de acceso. Dado que se trata de una integración de servicio a servicio, utilizaremos el flujo OAuth del portador JWT para acuñar el JWT y obtener el token de acceso OAuth. Use su clave privada que creó en la configuración de su aplicación conectada para crear el algoritmo para firmar el JWT.

 Archivo f = nuevo archivo (archivo de clave privada);
DataInputStream dis = new DataInputStream(new FileInputStream(f));
byte[] keyBytes = new byte[(int) f.length()];
dis.readFully(keyBytes);
revelar(); PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes);
KeyFactory kf = KeyFactory.getInstance("RSA");
PrivateKey privateKey = kf.generatePrivate(spec); Map<String, Object> headers = new HashMap<String, Object>();
headers.put("alg", "RS256");
Algoritmo algoritmo = Algorithm.RSA256(null, (RSAPrivateKey) privateKey);

Luego, cree el JWT con los valores apropiados.

 Instantáneo ahora = Instantáneo. ahora ();
Cadena jwt = JWT.create() .withHeader(encabezados) .withAudience(loginEndpoint) .withExpiresAt(Date.from(now.plus(jwtExpiryMinutes, ChronoUnit.MINUTES))) .withIssuer (identificación de la aplicación conectada) .withSubject (ID de usuario) .sign(algoritmo);

2. Obtenga el token de acceso de OAuth

Envíe una solicitud de publicación HTTP al extremo https://login.salesforce.com/ con services/oauth2/token en el jwt de la solicitud y utilizando los encabezados HTTP adecuados.

 // Crear datos de formulario de publicación Http.
MultiValueMap<String, String> formData= new LinkedMultiValueMap<>();
formData.add("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer");
formData.add("afirmación", jwt); // Crear encabezados HTTP.
HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.setContentType(MediaType.APPLICATION_FORM_URLENCODED); // Crear solicitud HTTP.
HttpEntity<Mapa> oAuthHttpRequest = new HttpEntity<>(formData, httpHeaders); // Enviar solicitud al punto final de OAuth
ResponseEntity<String> respuesta = restTemplate .postForEntity(OAUTH_URL, oAuthHttpRequest, String.class);

Luego, analice la respuesta para obtener access_token :

 nodo ObjectNode = new ObjectMapper().readValue(response.getBody(), ObjectNode. class );
Token de cadena = node.get( "token_de_acceso" ).asText();

Ahora, tenemos el token requerido para la autenticación y estamos listos para realizar solicitudes a la API de la plataforma Einstein Bots.

3. Enviar una solicitud de inicio de sesión de chat

Envíe una solicitud de publicación HTTP al punto final https://<RUNTIME_BASE_URL>/ v5.0.0/bots/{botId}/sessions con el token de autenticación y el orgId en los encabezados HTTP. El RUNTIME_BASE_URL se puede obtener de la página de descripción general del bot documentada en la guía del cliente .

 // Crear encabezados HTTP
HttpHeaders requestHeaders = new HttpHeaders();
requestHeaders.setContentType(MediaType.APPLICATION_JSON);
requestHeaders.setBearerAuth(token);
requestHeaders.add("X-Org-Id", orgId); Mensaje de cadena = "Hola"; // Crear cuerpo de solicitud en formato TextMessage definido en Schema. // Estamos usando la concatenación de cadenas aquí solo por simplicidad.
// Es probable que cree clases de DTO que puedan ayudar
// con serialización/deserialización JSON en código de producción real.
Cadena de cuerpo de solicitud = "{norte" + " "clave de sesión externa": "" + UUID.UUID aleatorio().toString + "",n" + " "mensaje": {n" + " "texto": "" + mensaje + ""n" + "}, n" + " "forceConfig": {n" + " "punto final": "" + forceConfigEndPoint + ""n" + "}n" + "}"; // Crear solicitud HTTP
HttpEntity<String> httpRequest = new HttpEntity<>(requestBody, requestHeaders); // Crear URL con formato URI v5.0.0/bots/{botId}/sessions
URL de cadena = RUNTIME_BASE_URL + "/v5.0.0/bots/" + ID de bot + "/sesiones" ; // Enviar solicitud de inicio de sesión de chat
ResponseEntity<String> startSessionResponse = restTemplate .postForEntity(url, httpRequest, String.class);

Puede analizar la respuesta para mostrar el mensaje del bot al usuario según el canal. Para este ejemplo, solo enviaremos a la consola, que se verá así:

 { "ID de sesión": "9168d0c9-bbe2-4be1-a1a1-8a3902921e87", "versiónbot": "0X9SB00000007cb0AA", "mensajes" : [ { "id": "c0a95f75-06b2-4269-b88d-c119e038781f", "calendario" : { "RespuestaDelayMilisegundos": 1200 }, "teclee el texto", "texto": "Hola," }, { "id": "d45cdaa8-b278-42d1-b954-53f4db9ea204", "calendario" : { "RespuestaDelayMilisegundos": 1200 }, "teclee el texto", "text" : "Soy un bot de demostración para la guía del usuario". }, { "id": "4c484926-c6c5-4944-b650-cce011b0f3b6", "calendario" : { "RespuestaDelayMilisegundos": 1200 }, "teclee el texto", "texto": "Elija una de las opciones a continuación" }, { "id": "d05f2b3a-2453-4acb-9c33-43774487c76c", "calendario" : { "RespuestaDelayMilisegundos": 1200 }, "tipo": "opciones", "widget": "menú", "opciones" : [ { "etiqueta": "Estado del pedido", "alias": "1", "id": "2319a485-5c5c-4c27-8239-abb8f7366ff6" }, { "etiqueta" : "Preguntas frecuentes", "alias": "2", "id": "664d72d9-2a54-477b-9f9b-da2d01c58552" }, { "etiqueta": "Transferir al agente", "alias": "3", "id": "dccd1287-8fc0-426f-ae0b-0a8b6a41b011" }, { "label": "Finalizar chat", "alias": "4", "id": "c359eaea-f981-49ba-a424-18b8b7572d20" } ] } ], "identificadores de secuencia procesada": [ 0 ], "_Enlaces" : { "sesión" : { "href": "https://runtime-api-na-west.stg.chatbots.sfdc.sh/v5.0.0/sessions/9168d0c9-bbe2-4be1-a1a1-8a3902921e87" }, "uno mismo" : { "href": "https://runtime-api-na-west.stg.chatbots.sfdc.sh/v5.0.0/bots/0XxSB00000007UX0AY/sessions" }, "mensajes" : { "href": "https://runtime-api-na-west.stg.chatbots.sfdc.sh/v5.0.0/sessions/9168d0c9-bbe2-4be1-a1a1-8a3902921e87/messages" } }
}

A continuación, necesitaremos extraer el sessionId de sesión de la respuesta para continuar enviando mensajes a la misma sesión.

 // Imprime el cuerpo de la respuesta que tiene una respuesta de Chatbot.
System.out.println("Respuesta de inicio de sesión de Bot: " + startSessionResponse.getBody()); // Obtenga SessionId de Response para enviar un mensaje a la sesión de chat existente.
JsonNode responseNode = asignador .readValue(startSessionResponse.getBody(), JsonNode. class ); String sessionId = responseNode.get( "sessionId" ).asText();

Como puede ver, se requiere una gran cantidad de código repetitivo para usar la API de Einstein Bots Platform directamente. Para simplificar la integración y reducir gran parte del código repetitivo, creamos un SDK de Einstein Bots para Java .

Uso del SDK de Java para simplificar una integración de Bots de Einstein

El SDK es un contenedor de la API de la plataforma Einstein Bots que simplifica la integración al proporcionar características adicionales, como soporte de autorización y administración de sesiones. Veamos un poco de código para implementar el mismo ejemplo usando el SDK de Bots de Einstein.

1. Agregar una dependencia POM

Encuentre la última versión de einstein-bot-sdk-java de Maven Central y agregue esta dependencia a su pom.xml .

 <dependencia> <groupId>com.salesforce.einsteinbot</groupId> <artifactId>einstein-bot-sdk-java</artifactId> <versión>${einstein-bot-sdk-java-versión}</versión>
</dependencia>

2. Crear un cliente de chatbot

El cliente de chatbot proporciona JwtBearerFlow para OAuth, así que cree AuthMechanism con los parámetros apropiados. Luego, cree BasicChatbotClient con el mecanismo de autenticación y basePath de la URL de tiempo de ejecución de Bot.

 //Crear mecanismo de autenticación JwtBearer.
Mecanismo de autenticación oAuth = JwtBearerOAuth.with() .privateKeyFilePath(privateKeyFilePath) .loginEndpoint(loginEndpoint) .connectedAppId(conectadoAppId) .connectedAppSecret(secreto) .userId(usuarioId) .construir(); //Crear cliente de chatbot básico
Cliente de BasicChatbotClient = ChatbotClients.basic() .basePath(basePath) .authMechanism(oAuth) .construir();

3. Enviar solicitud de inicio de sesión de chat

Primero, cree una RequestConfig con su botId , orgId y forceConfigEndPoint . Puede consultar la guía del cliente para encontrar estos valores. Por lo general, desea crear una configuración una vez por bot en su organización y reutilizarla para cada solicitud.

 //Crear configuración de solicitud
RequestConfig config = RequestConfig.with() .botId(botId) .orgId(orgId) .forceConfigEndpoint(forceConfigEndPoint) .construir();

Luego, crea una BotSendMessageRequest con TextMessage .

 // Podemos usar clases Java tipadas estáticamente para el cuerpo de la solicitud.
Mensaje AnyRequestMessage = nuevo TextMessage() .text("Hola") .type(TextMessage.TypeEnum.TEXT) .sequenceId(Sistema.currentTimeMillis()); BotSendMessageRequest botSendInitMessageRequest = BotRequest .withMessage(mensaje) .construir();

Utilice el método startChatSession para iniciar una sesión.

 ExternalSessionId externalSessionKey = nuevo ExternalSessionId(UUID. randomUUID ().toString()); BotResponse respuesta = cliente .startChatSession(config, externalSessionKey, botSendInitMessageRequest); // Obtener ID de sesión de la respuesta. String sessionId = resp.getResponseEnvelope().getSessionId();

Analice el sobre de respuesta y muestre el mensaje al usuario según el canal. El SDK deserializará automáticamente el JSON a un modelo Java para hacerlo más fácil. El siguiente código muestra cómo analizar la respuesta como texto para los tipos TextResponseMessage y ChoiceResponseMessage . Para todos los tipos y códigos admitidos, consulte el esquema .

 List<AnyResponseMessage> mensajes = resp.getResponseEnvelope().getMessages();
StringBuilder sb = nuevo StringBuilder();
for(AnyResponseMessage mensaje: mensajes){ if (instancia de mensaje de TextResponseMessage){ sb.append(((TextResponseMessage) mensaje).getText()) .append("n"); }else if (instancia de mensaje de ChoicesResponseMessage){ List<ChoicesResponseMessageChoices> opciones = ((ChoicesResponseMessage) mensaje) .obtenerOpciones(); para (ChoicesResponseMessageChoices opción: opciones){ sb.append(elección.getAlias()) .adjuntar(".") .append(elección.getLabel()) .append("n"); } } //Maneje de manera similar otros tipos de mensajes de respuesta.
}
Cadena de respuestaMessageAsText = sb.toString();
System.out.println(responseMessageAsText);

La salida se verá así:

 Hola,
Soy un bot de demostración para la guía del usuario.
Elija una de las opciones a continuación
1.Estado del pedido
2.Preguntas frecuentes
3. Transferir al agente
4.Finalizar chat

Tenemos diferentes extremos de la API de la plataforma Einstein Bots para continuar una sesión existente y finalizar una sesión de chat. Para completar, veamos ejemplos de código para ellos.

4. Enviar un mensaje a una sesión de chat existente

El código de ejemplo muestra cómo usar el método sendMessage para enviar un mensaje a una sesión de chat abierta existente.

 // SDK también proporciona métodos de utilidad para crear un mensaje de texto.
// Digamos que queremos responder a la opción del menú con "Estado del pedido".
AnyRequestMessage userInputMessage = RequestFactory . buildTextMessage ( "Estado del pedido" ); // Crear solicitud de envío de mensaje de bot con el mensaje de respuesta del usuario. BotSendMessageRequest botSendMessageRequest = BotRequest .withMessage(mensaje de entrada de usuario) .construir(); //Cree RuntimeSessionId con sessionId que obtuvo al iniciar la sesión de chat Response. RuntimeSessionId runtimeSessionId = new RuntimeSessionId(sessionId); // Enviar un mensaje a la sesión existente con sessionId
BotResponse textMsgResponse = cliente .sendMessage(config, runtimeSessionId, botSendMessageRequest); System.out.println("Respuesta de mensaje de texto:" + textMsgResponse);

Usamos TextMessage en este ejemplo, pero también puede enviar otros tipos (p. ej., ChoiceMessage ) admitidos por Einstein Bot Runtime Open API Schema .

5. Terminar una sesión de chat

Finalmente, aquí hay un código de ejemplo para finalizar la sesión usando el método endChatSession .

 // Solicitud de mensaje de finalización de sesión del bot de compilación
BotEndSessionRequest botEndSessionRequest = BotRequest .withEndSession(EndSessionRason.USERREQUEST).build(); //Cree RuntimeSessionId con sessionId que obtuvo al iniciar la sesión de chat Response.
RuntimeSessionId runtimeSessionId = new RuntimeSessionId(sessionId); // Enviar solicitud para finalizar la sesión de chat
BotResponse endSessionResponse = cliente .endChatSession(config, runtimeSessionId, botEndSessionRequest); System.out.println("Respuesta de finalización de sesión:" + endSessionResponse);

Beneficios de usar el SDK de Bots de Einstein

El SDK de Bots de Einstein proporciona muchas características excelentes que pueden ahorrar tiempo a los desarrolladores.

Abstrae los detalles de la carga de la clave privada y la acuñación de JWT.
Abstrae el intercambio de tokens para obtener el token de acceso OAuth.
Proporciona clases modelo con verificación de tipo estricta.
- No tiene que usar la serialización/deserialización de cadenas JSON complicadas de cuerpos de solicitud/respuesta.
- Usamos TextMessage en este ejemplo. Del mismo modo, las clases de modelo están disponibles para todos los objetos de esquema definidos en Bot Runtime Open API Schema .
El código es más legible debido a los métodos similares a dsl.
Si usa BasicChatbotClient demostrado en el blog, deberá realizar un seguimiento de las sesiones y llamar al método startChatSession o sendMessage de manera adecuada. En su lugar, use SessionManagedChatbotClient , que elimina el método startChatSession . Creará automáticamente una nueva sesión basada en el ExternalSessionId proporcionado por el usuario. Publicaremos una publicación de blog de seguimiento sobre el uso de SessionManagedChatbotClient .

Y hay más: el marco Channel Connector

Además del SDK de Bots de Einstein, también lanzamos el marco Conector de canal de Bots de Einstein para simplificar la creación de un servicio de conector de canal mediante Spring Boot. Configura automáticamente los beans de Spring para los servicios básicos, como el almacenamiento en caché, la autenticación y las métricas, y lo prepara para su uso inmediato.

El marco del conector de canal incluye una aplicación de ejemplo de trabajo y un arquetipo experto para crear una nueva aplicación de conector de canal de bot.

La siguiente imagen resume las herramientas que estamos lanzando y los beneficios que brindan.