Skip to main content

CASOS DE USO

Ejemplos reales de uso de las APIs de ZampiBot. Combinan la API de JavaScript , la Web API y algunos ajustes del panel para resolver tareas concretas.

Todos los ejemplos de JavaScript van en la página donde instalaste el chat, después de cargar jQuery (ver «Configuración y uso» en la API de JavaScript).

👤 Registrar un usuario e iniciar su sesión automáticamente

Sirve para que, si tu web ya sabe quién es el visitante (por ejemplo, porque inició sesión en tu tienda), el chat lo reconozca sin pedirle sus datos. Hay tres formas; te recomendamos la 1 o la 2.

Método 1: variable de JavaScript (la más sencilla)

Define la variable SB_DEFAULT_USER en la página antes del código de instalación del chat, con los datos del usuario. El chat lo registra (o lo reconoce) automáticamente y no le pide registrarse.

<script>
    var SB_DEFAULT_USER = {
        first_name: "Juan",
        last_name: "Pérez",
        email: "juan@example.com",
        extra: {
            phone: ["+573001234567", "Phone"],
            city: ["Bogotá", "City"]
        }
    };
</script>
<script id="chat-init" async src="https://chatbot.zampisoft.com/account/js/init.js?id=12345678"></script>

Genera estos valores desde tu servidor con los datos del usuario que inició sesión en tu web.

Si el correo ya existe en ZampiBot (por ejemplo, el cliente ya escribió antes), el chat solo inicia su sesión si añades también password con la contraseña cifrada que guarda ZampiBot: es el campo password que devuelve la función get-user de la Web API. Sin ella, el usuario existente no se identifica. Por eso, si tus clientes vuelven a menudo, el método 2 suele ser más práctico.

Método 2: Web API + JavaScript (el más seguro)

Tu servidor consulta a ZampiBot si el usuario ya existe y escribe en la página el código para iniciar su sesión. La contraseña nunca llega al navegador.

1. Activa la inicialización manual. En el panel, ve a Ajustes > Chat, marca Inicialización manual y guarda. Así el chat espera a que tu código lo inicie.

2. Genera el código desde tu servidor. Este ejemplo en PHP usa la función zampibot_api() de la página Web API (con tu token de API, que nunca se envía al navegador):

<?php
$email = 'juan@example.com';
$sb_user = zampibot_api(['function' => 'get-user-by', 'by' => 'email', 'value' => $email]);
$login_existing_user = '';

if (!empty($sb_user['success']) && !empty($sb_user['response'])) {
    $sb_user = $sb_user['response'];
    $login_existing_user = 'SBF.login("", "", "' . $sb_user['id'] . '", "' . $sb_user['token'] . '", () => { SBChat.initChat(); });';
}
?>
<script>
jQuery(document).on("SBReady", function () {
    SBF.getActiveUser(true, () => {
        if (SBF.activeUser() && SBF.activeUser().email == "<?php echo $email; ?>") {
            SBChat.initChat();
            return;
        }
        SBF.ajax({
            function: "add-user-and-login",
            settings: { first_name: "Juan", last_name: "Pérez", email: "<?php echo $email; ?>" },
            settings_extra: { phone: ["+573001234567", "Phone"], city: ["Bogotá", "City"] }
        }, (response) => {
            if (!SBF.errorValidation(response)) {
                SBF.loginCookie(response[1]);
                SBChat.initChat();
            } else if (response[1] == "duplicate-email") {
                <?php echo $login_existing_user; ?>
            } else {
                SBChat.initChat();
            }
        });
    });
});
</script>

Método 3: solo JavaScript

1. Activa la inicialización manual. En el panel, ve a Ajustes > Chat, marca Inicialización manual y guarda.

2. Registra al usuario e inicia su sesión.

Atención: con este método la contraseña y los datos del usuario quedan visibles en el código de la página. Úsalo solo si eso no es un problema.

jQuery(document).on("SBReady", function () {
    SBF.getActiveUser(true, () => {
        if (SBF.activeUser() && SBF.activeUser().email == "juan@example.com") {
            SBChat.initChat();
            return;
        }
        SBF.ajax({
            function: "add-user-and-login",
            settings: { first_name: "Juan", last_name: "Pérez", email: "juan@example.com", password: "12345678" },
            settings_extra: { phone: ["+573001234567", "Phone"], city: ["Bogotá", "City"] }
        }, (response) => {
            if (!SBF.errorValidation(response)) {
                SBF.loginCookie(response[1]);
                SBChat.initChat();
            } else if (response[1] == "duplicate-email") {
                SBF.login("juan@example.com", "12345678", "", "", () => { SBChat.initChat(); });
            } else {
                console.log(response);
            }
        });
    });
});

📄 Mostrar el chat solo en algunas páginas

1. Activa la inicialización manual. En el panel, ve a Ajustes > Chat, marca Inicialización manual y guarda.

2. Inicia el chat solo donde quieras. Usa SBChat.initChat() y la dirección de la página (window.location.href) para decidir:

jQuery(document).on("SBReady", function () {
    // Ejemplo: mostrar el chat solo en la página de contacto
    if (window.location.href.indexOf("/contacto") > 0) {
        SBChat.initChat();
    }
    // Ejemplo: mostrar el chat solo en la página de inicio
    if (window.location.href == "https://tu-sitio.com/") {
        SBChat.initChat();
    }
});

Si solo quieres ocultarlo en unas pocas páginas, no necesitas la inicialización manual: añade <script>var SB_DISABLED = true;</script> antes del código de instalación en esas páginas.

🖱️ Abrir el chat con un botón propio

Añade la clase sb-open-chat (o el ID sb-open-chat) a cualquier botón o enlace de tu página. Al pulsarlo, se abre el chat; si ya está abierto, se cierra.

<a class="sb-open-chat">Habla con nosotros</a>

También puedes usar la función SBChat.open():

<a href="javascript:SBChat.open()">Habla con nosotros</a>

👁️ Mostrar el chat solo cuando se pulsa un botón

El botón del chat no aparece hasta que el visitante pulsa tu botón; entonces se muestra y se abre.

1. En el panel, ve a Ajustes > Chat, marca Inicialización manual y Abrir automáticamente, y guarda.

2. Usa SBChat.initChat() en tu botón. En el móvil, añade también SBChat.open():

<a href="javascript:SBChat.initChat();SBChat.open()">Habla con nosotros</a>

🔄 Mostrar y ocultar el chat con un botón

El primer clic muestra el chat; al cerrarlo, el botón del chat vuelve a ocultarse.

1. En el panel, ve a Ajustes > Chat, marca Inicialización manual y guarda.

2. Añade este código. Cambia button-id por el ID de tu botón.

jQuery("body").on("click", "#button-id", function () {
    SBChat.initChat();
    jQuery(".sb-chat-btn").show();
    setTimeout(function () {
        SBChat.open();
    }, 500);
});

jQuery("body").on("click", ".sb-chat .sb-chat-btn", function () {
    jQuery(this).hide();
});

🏢 Crear una conversación y asignarle un departamento

Crea una conversación nueva en un departamento concreto y la abre. Los IDs de los departamentos están en Ajustes > Misceláneas > Departamentos.

Si quieres que todas las conversaciones que se creen desde una página vayan a un departamento, es más sencillo definir la variable SB_DEFAULT_DEPARTMENT (ver la API de JavaScript).

En este ejemplo la conversación solo se crea si el visitante no tiene ninguna. El quinto parámetro de SBChat.newConversation() es el departamento (aquí, el 2):

jQuery(document).on("SBInit", function () {
    if (SBF.activeUser() && SBF.activeUser().conversations.length == 0) {
        // estado, usuario, mensaje, adjuntos, DEPARTAMENTO, agente, al terminar
        SBChat.newConversation(2, -1, "", [], 2, null, function (conversation) {
            SBChat.openConversation(conversation.id);
        });
    }
});

🕵️ Crear una conversación y asignarla a un agente

Crea una conversación asignada a un agente concreto, de forma que solo ese agente la vea en el panel.

1. En el panel, ve a Ajustes > Misceláneas, activa Ocultar conversaciones de otros agentes y guarda. Con esta opción, cada agente ve solo las conversaciones asignadas a él.

2. Crea la conversación pasando el ID del agente (aquí, el 445) como sexto parámetro de SBChat.newConversation(), y ábrela:

jQuery(document).on("SBInit", function () {
    if (SBF.activeUser() && SBF.activeUser().conversations.length == 0) {
        // estado, usuario, mensaje, adjuntos, departamento, AGENTE, al terminar
        SBChat.newConversation(2, -1, "", [], null, 445, function (conversation) {
            SBChat.openConversation(conversation.id);
        });
    }
});

📌 Usar siempre una conversación concreta

Busca entre las conversaciones del visitante una con un título determinado; si la encuentra, la abre, y si no, crea una nueva con ese título. Sirve, por ejemplo, para usar una conversación distinta en cada sección de tu web.

(function ($) {
    $(document).on("SBInit", function () {
        if (!SBF.activeUser()) return;
        let conversation_title = "NOMBRE-DE-LA-CONVERSACION";
        let conversations = SBF.activeUser().conversations;
        for (var i = 0; i < conversations.length; i++) {
            if (conversations[i].get("title") == conversation_title) {
                SBChat.openConversation(conversations[i].id);
                return;
            }
        }
        SBF.ajax({
            function: "new-conversation",
            title: conversation_title
        }, (response) => {
            SBChat.setConversation(new SBConversation([], response["details"]));
        });
    });
}(jQuery));

Si tienes activado Ajustes > Chat > Permitir solo una conversación, new-conversation devuelve la conversación abierta que ya tenga el visitante en lugar de crear otra.

🏢 Usar siempre un departamento concreto

Busca una conversación del visitante en el departamento indicado; si la encuentra, la abre, y si no, crea una nueva en ese departamento. Cambia ID-DEL-DEPARTAMENTO por el ID del departamento.

(function ($) {
    $(document).on("SBInit", function () {
        if (!SBF.activeUser()) return;
        let active_department = "ID-DEL-DEPARTAMENTO";
        let conversations = SBF.activeUser().conversations;
        SBChat.default_department = active_department;
        for (var i = 0; i < conversations.length; i++) {
            if (conversations[i].get("department") == active_department) {
                let id = conversations[i].id;
                setTimeout(() => { SBChat.openConversation(id); }, 300);
                return;
            }
        }
        SBChat.open(false);
        SBF.ajax({
            function: "new-conversation",
            department: active_department
        }, (response) => {
            SBChat.setConversation(new SBConversation([], response["details"]));
        });
    });
}(jQuery));

🕵️ Usar siempre un agente concreto

Busca una conversación del visitante asignada al agente indicado en SB_DEFAULT_AGENT; si la encuentra, la abre, y si no, crea una nueva asignada a ese agente.

1. En cada página, antes del código de instalación del chat, añade <script>var SB_DEFAULT_AGENT = 123;</script> y cambia 123 por el ID del agente.

2. Añade este código:

(function ($) {
    if (typeof SB_DEFAULT_AGENT != "undefined") {
        $(document).on("SBInit", function () {
            if (!SBF.activeUser()) return;
            let conversations = SBF.activeUser().conversations;
            for (var i = 0; i < conversations.length; i++) {
                if (conversations[i].get("agent_id") == SB_DEFAULT_AGENT) {
                    let id = conversations[i].id;
                    setTimeout(() => { SBChat.openConversation(id); }, 300);
                    return;
                }
            }
            $(".sb-list").sbLoading(true);
            SBChat.open(false);
            SBF.ajax({
                function: "new-conversation",
                agent_id: SB_DEFAULT_AGENT
            }, (response) => {
                SBChat.clear();
                $(".sb-list").sbLoading(false);
                SBChat.setConversation(new SBConversation([], response["details"]));
            });
        });
    }
}(jQuery));

📨 Enviar un mensaje y abrir el chat

Envía un mensaje del bot al visitante y abre el chat. Antes comprueba con searchMessages() que ese mensaje no esté ya en la conversación, para no repetirlo en cada visita.

jQuery(document).on("SBInit", function () {
    let message = "¿Quieres comprar el producto de esta página?";
    if (SBChat.conversation == false || SBChat.conversation.searchMessages(message).length == 0) {
        SBChat.sendMessage(SBF.setting("bot_id"), message, [], function (response) {
            SBChat.openConversation(response["conversation_id"]);
            if (!SBChat.chat_open) {
                SBChat.open();
            }
        });
    }
});

📜 Mostrar un mensaje emergente al bajar por la página

Muestra un mensaje emergente junto al botón del chat cuando el visitante baja 500 píxeles por la página. El mensaje emergente solo se ve con el chat cerrado.

jQuery(document).on("SBInit", function () {
    var shown = false;
    jQuery(window).scroll(function () {
        if (jQuery(window).scrollTop() > 500 && !shown) {
            SBChat.popup(false, { title: "¿Tienes dudas?", message: "Escríbenos y te ayudamos." });
            shown = true;
        }
    });
});