¿Cómo puedo incrustar Spoki 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 puedes incrustar con Spoki mediante iframe:
- Incrustación por iframe: permite a tus clientes usar las funciones de Spoki sin salir de tu sistema de gestión.
- Inicio de sesión automático mediante token: no necesitas compartir credenciales de Spoki; puedes autenticar al usuario de tu servicio antes de mostrar el iframe.
- Ocultar marca (“Hide Spoki”): el logotipo de Spoki no es visible dentro del iframe.
- Multisesión: utiliza Spoki en varias pestañas al mismo tiempo, cada una con su sesión.
- Evitar la navegación: en iframe no se muestra la barra de navegación, así limitas el uso a una página concreta.
Recibe una notificación cuando:
- Cambien los chats no leídos.
- Se actualice la lista de chats en la página “Chats”.
- Se modifique la lista de mensajes en la página de detalles del chat.
Cómo #
Para incrustar el iframe de Spoki es necesario realizar los siguientes pasos:
- Solicitar las Clave API
- Generar el token privado
- Incrustar el iframe
- Suscríbirse a los eventos de iFrame
- Obtener la aprobación de la clave API, y luego disfrutar 🎉.
1. Solicitar la clave API #
- Ve a Integraciones > API > Solicitar clave API.
- Inserta la motivación y haz clic en «Request API Key». Ejemplo: “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.”
Guarda la clave API generada.
Nota: no podrás utilizar la API hasta que se apruebe. Recibirás un email sobre el resultado en un plazo máximo de 48 horas.
2. Generar el token privado #
El Token Privado está asociado a un usuario específico de tu cuenta. Puedes obtenerlo de:
- Usuario de servicio – recomendado
- Tu propio usuario
- Otros usuarios que inicien sesión y te lo entreguen (no recomendado)
Pasos:
- Ve a Usuarios y Roles > Añadir.
- Selecciona la función, elige “Usuario de servicio” como tipo de usuario, introduce el nombre y haz clic en “Añadir”.
- Haz clic en el icono de la llave a la derecha del usuario de servicio.
- Pulsa “Generar nueva clave privada”.
- Guarda el email y la clave privada.
⚠️ IMPORTANTE:
- No podrás volver a ver la clave.
- Mantén la clave protegida: cualquiera que la tenga puede actuar en tu nombre.
- Si se filtra, regenera de inmediato.
3. Incrustar el iframe #
ATENCIÓN: ¡no estará autorizado a utilizar esta API hasta que disponga de una Clave API aprobada!
¡Es hora de codificar! 👨💻 #
Ejemplo de integración:
En tu HTML añade un div vacío para la incrustación de 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 de cerrar el
</body>, añade este script para hacer la autenticación usando API Key y Private Key, y luego inserta el iframe:
...
<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>4. Configuración avanzada #
Puedes usar diferentes pageSlug:
- Lista de chats →
chats - Detalle de chat →
chats/:uuid(conchat_linkde la Api de Contactos) - Plantillas →
templates
Parámetros de URL opcionales:
&can_view_chat_list=false→ Oculta el botón atrás.&can_reply_in_chat=false→ Oculta el footer del chat.&can_send_paypal_in_chat=false→ Oculta la pestaña de PayPal.
Idiomas disponibles → language=it | en | es.
5. Suscripción a eventos iFrame #
Puedes escuchar eventos del iFrame:
window.addEventListener("message", (event) => {
if (event.origin !== "https://spoki.app") return;
const { eventType, data } = event.data;
switch (eventType) {
case "hasUnreadChatsChanged":
console.log("Unread chats changed", data);
break;
case "chatsChanged":
console.log("Chats list updated", data);
break;
case "chatMessagesChanged":
console.log("Messages updated", data);
break;
default:
console.log("Unhandled event", eventType, data);
}
}, false);
6. Obtener la aprobación de la API #
Una vez aprobada tu Clave API, ¡ya podrás disfrutar de Spoki en tu software! 🎉
👉 Ahora tus clientes podrán usar Spoki directamente dentro de tu sistema web.
¿Quiere saber más sobre la API Get Authentication Token? Consulte la documentación de la API
Gracias por tu tiempo.
Disfruta Spoki 🎉
