Table of Contents
¿Cómo puedo incrustar Spoki, por lo que el chat de WhatsApp en la página de detalles de contacto de mi software?
¿Cómo puedo permitir que mis clientes soliciten una plantilla de WhatsApp directamente desde mi programa de gestión?
Resuelve estas necesidades, y muchas más, integrando Spoki en tu propio software.
Funcionalidades #
Esto es lo que puede incrustar Spoki con el iframe:
- Incrustación Iframe. Permite a tus clientes utilizar las funciones de Spoki sin salir de tu sistema de gestión.
- Inicio de sesión automático mediante token. No es necesario proporcionar credenciales Spoki a tus usuarios, puedes autenticar al usuario del servicio asociado antes de mostrarle el iframe.
- Marca Hide Spoki. El logotipo de Spoki no es visible en el iframe.
- Multisesión. Utiliza Spoki simultáneamente en diferentes pestañas con diferentes sesiones.
- Evitar la navegación. En iframe la barra de navegación no es visible, de esta manera puedes limitar el uso a una página específica.
- Reciba una notificación cuando:
- Cambios en los chats no leídos
- La lista de chats de la página Chats ha cambiado
- Se ha modificado la lista de mensajes de la página de detalles del chat
Cómo #
Para incrustar el iframe Spoki es necesario realizar los siguientes pasos:
- Solicitar las abejas Clave
- Generar el token privado
- Incrustar el iframe
- Suscríbase a los eventos de iFrame
- Obtener la aprobación de la clave Api, y luego disfrutar 🎉.
1. Solicitar la clave API #
- Ir a Integraciones / API / Solicitar clave API
- Inserte la motivación y haga clic en «Request Api Key».
Ej. «Quiero desarrollar la integración de Spoki en mi sistema de gestión para poder incrustar un iframe de chat en el detalle de un contacto.
- Guarde la clave Api generada. No podrá utilizar la API hasta que se apruebe, recibirá un correo electrónico sobre el resultado de la solicitud en un plazo máximo de 48 horas.
2. Generar el token privado #
El Token Privado está asociado a un usuario específico de su cuenta.
Puede obtener un Token Privado por:
- Usuario del servicio – recomendado
- Tu propio usuario
- Pedir a otros usuarios que inicien sesión y te la den – no recomendado, utiliza en su lugar Usuarios del Servicio
Para obtener el Token Privado siga estos pasos:
- Ir a Usuarios y Roles / Añadir
- Seleccione la función, seleccione«Usuario de servicio» como tipo de usuario, introduzca el nombre y haga clic en«Añadir«.
- Haga clic en el icono de la llave a la derecha del usuario del servicio
- Haga clic en«Generar nueva clave privada«.
- Guarde el correo electrónico y la clave privada.
IMPORTANTE: Asegúrate de guardarlo, no podrás volver a acceder a él. Mantén la llave protegida, cualquiera que la tenga puede actuar por ti. Si es así, regenere la clave.
3. Incrustar el iframe #
ATENCIÓN: ¡no estará autorizado a utilizar esta API hasta que disponga de una Clave de API aprobada!
Sí, ya sé que te mueres de ganas… ¡es hora de codificar! 👨💻
Así es como funciona:
- En su página HTML inserte un div vacío para la incrustación Spoki
<body>
...
<div id="spoki-embedding"></div>- Insertar el estilo css en el head
...
<style>
#spoki-embedding iframe {
position: fixed;
bottom: 10px;
right: 10px;
height: 600px;
width: 450px;
border: 2px solid #cccccc;
border-radius: 8px;
}
</style>
</head>- Antes del final del cuerpo inserta este script que te permite hacer el auth usando la Api Key y Private Key, luego insertará el iframe dentro del div. El usuario se registrará automáticamente e irá a la página especificada.
...
<script type="application/javascript">
// Init Spoki iFrame, you can open every Spoki page you need
function initSpokiIframe() {
const headers = new Headers();
headers.append("Content-Type", "application/json");
headers.append("X-Spoki-Api-Key", "{{Api-Key}}");
const body = JSON.stringify({
email: "{{Email}}",
private_key: "{{Private-Key}}"
});
const requestOptions = {
method: "POST",
headers,
body,
redirect: "follow"
};
fetch("https://app.spoki.it/api/1/auth/get_authentication_token/", requestOptions)
.then(response => response.json())
.then(({ token, uid }) => {
// the slug of the Spoki page you want to open
const pageSlug = "chats";
const iframeParent = document.getElementById("spoki-embedding");
const iframeEl = document.createElement("iframe");
iframeEl.setAttribute("frameborder", "0");
iframeEl.setAttribute("src", `https://spoki.app/${pageSlug}?auth_token=${token}&auth_uid=${uid}&language=en`);
iframeParent.appendChild(iframeEl);
})
.catch(error => console.log("Spoki error", error));
}
// Call on startup
(initSpokiIframe)();
</script>
</body>- You can set as page slug all the Spoki routes you want, the most important are:
- Lista de chats:‘chats
- Detalle del chat:’chats/:uuid’ (puedes obtener el chat_link usando la Api de Contactos).
Puede concatenar a la url src los parámetros de consulta de la siguiente manera:
– «&can_view_chat_list=false» = >ocultar el botón atrás para impedir el acceso a la página de chats.
– «&can_reply_in_chat=false» = >ocultar el pie de página del chat para evitar la respuesta desde el iFrame.
– «&can_send_paypal_in_chat=false» = >ocultar la pestaña de PayPal en el pie de página del chat
- Plantillas: ‘templates‘
- Si necesitas abrir el iFrame en un idioma específico puedes pasar como parámetro al src del iFrame el parámetro idioma (los valores admitidos son it, en, es)
¿Quiere saber más sobre la API Get Authentication Token? Consulte la documentación de la API
4. Suscribirse a eventos iFrame #
Con Spoki puedes suscribirte a los Eventos iFrame:
- Cambio de los chats no leídos (pageSlug: funciona en todas las páginas)
- eventType: hasUnreadChatsChanged
- datos: { hasUnreadChats: boolean }
- Se ha modificado la lista de chats de la página Chats (pageSlug: chats)
- eventType: chatsCambiado
- data: { chats: Chat[]; hasFilters: boolean; page: number }
- La lista de mensajes de la página de detalles del chat ha cambiado (pageSlug: chats/:uuid)
- datos: { chat: Chat; página: número; mensajes: Mensaje[] }
...
<script type="application/javascript">
function initSpokiIframe() {
...
.then(({ token, uid }) => {
// Call it if you need to subscribe to Spoki events
subscribeToSpoki();
...
})
...
}
// Subscribe to the Spoki iFrame to get notified about events
function subscribeToSpoki() {
window.addEventListener("message", (event) => {
if (event.origin !== "https://spoki.app") return;
const { eventType, data } = event.data;
switch (eventType) {
case "hasUnreadChatsChanged":
/** Unread chats changed (pageSlug: works on every page)
* hasUnreadChats: boolean
*/
console.log("Spoki", eventType, data);
break;
case "chatsChanged":
/** The list of chats in the Chats Page changed (pageSlug: chats)
* chats: Chat[]
* hasFilters: boolean
* page: number
*/
console.log("Spoki", eventType, data);
break;
case "chatMessagesChanged":
/** The list of messages in the Chat Detail Page changed (pageSlug: chats/:uuid)
* chat: Chat
* page: number
* messages: Message[]
*/
console.log("Spoki", eventType, data);
break;
default:
console.log("Spoki", "Unhandled message event type", eventType, data);
}
},
false
);
...
</script>5. Obtener la aprobación de la clave Api, a continuación, disfrutar 🎉. #
¡Bien hecho! Todo está listo para que tus clientes utilicen Spoki desde tu propio software web.
Sólo tienes que esperar a la aprobación de la Clave Api.
Gracias por su tiempo.
Disfruta Spoki 🎉
