Skip to main content

JAVASCRIPT API

La API de JavaScript reúne las funciones, objetos y eventos del chat de ZampiBot que puedes usar desde tu propia página web: abrir el chat, crear conversaciones, enviar mensajes, reaccionar cuando el visitante escribe, etc. Funciona en cualquier página donde hayas instalado el chat.

La API de JavaScript actúa en nombre del visitante que tiene la página abierta. Para tareas de administración (consultar todos los usuarios, leer cualquier conversación…) usa la Web API desde tu servidor.

⚙️ Configuración y uso

1. Instala el chat

Copia el código de instalación desde el portal: https://chatbot.zampisoft.com/app/portal/ > Instalación, y pégalo en tu página. Tiene esta forma (con tu propio número en lugar de 12345678):

<script id="chat-init" async src="https://chatbot.zampisoft.com/account/js/init.js?id=12345678"></script>

2. Carga jQuery antes del chat

Los eventos del chat se escuchan con jQuery. El chat carga jQuery por su cuenta si no lo encuentra, pero lo hace más tarde que tu código; para que tus funciones estén listas desde el principio, carga jQuery antes del código de instalación. Si tu página ya usa jQuery, no hace falta añadirlo de nuevo.

<script src="https://chatbot.zampisoft.com/script/js/min/jquery.min.js"></script>
<script id="chat-init" async src="https://chatbot.zampisoft.com/account/js/init.js?id=12345678"></script>

3. Escribe tu código dentro del evento SBInit

Pon tu código dentro del evento SBInit, que se dispara cuando el chat terminó de cargarse:

<script>
(function ($) {
    $(document).on("SBInit", function () {
        // Tu código aquí
    });
}(jQuery));
</script>

Si el chat usa inicialización manual (ver SBChat.initChat()), SBInit no se dispara hasta que lo inicializas; en ese caso usa el evento SBReady.

Parámetros de las funciones

Pasa los parámetros en el mismo orden en que aparecen en esta página. Por ejemplo: SBChat.sendMessage(user_id, message, attachments). Si quieres dejar un parámetro con su valor por defecto y dar valor al siguiente, escribe el valor por defecto en su lugar.

Depuración

Si algo no funciona, abre la consola del navegador (F12): ahí aparecen los errores y avisos del chat.

📦 Objetos

Estos son los objetos que usa el chat. Algunas funciones los reciben o los devuelven.

👤 SBUser

Representa a un usuario.

Uso: new SBUser(details, extra)

  • details: datos del usuario, por ejemplo { id: "", first_name: "", last_name: "", profile_image: "", email: "", user_type: "" }.
  • extra: datos adicionales del usuario, por ejemplo { phone: "", city: "", language: "", country: "" }.

Propiedades de solo lectura:

  • id: el ID del usuario.
  • type: el tipo de usuario: visitor, lead, user, agent o admin.
  • email: el correo del usuario.
  • name: el nombre completo (nombre y apellido).
  • nameBeautified: el nombre completo si existe; si no, el nombre de visitante por defecto.
  • image: la foto de perfil.
  • language: el idioma del usuario.

Métodos:

  • get(key): devuelve un dato del usuario, o una cadena vacía si no existe. Ejemplo: get("email").
  • getExtra(key): devuelve un dato adicional del usuario, o una cadena vacía si no existe. Ejemplo: getExtra("phone").
  • set(key, value): cambia o añade un dato del usuario (solo en la página, no en la base de datos).
  • setExtra(key, value): cambia o añade un dato adicional (solo en la página).
  • update(onSuccess): vuelve a leer los datos del usuario desde el servidor. Opcionalmente ejecuta una función al terminar.
  • getConversations(onSuccess, exclude_id): lee las conversaciones del usuario desde el servidor (cada una con un extracto del último mensaje). exclude_id excluye una conversación.
  • getConversationsCode(conversations): devuelve el HTML de la lista de conversaciones. Opcionalmente recibe una lista de objetos SBConversation.
  • getFullConversation(conversation_id, onSuccess): lee una conversación completa, con todos sus mensajes, y la pasa a onSuccess.
  • getConversationByID(conversation_id, index): devuelve la conversación con ese ID, o false. Con index en true devuelve su posición en la lista.
  • addConversation(conversation): añade un objeto SBConversation a la lista del usuario (solo en la página).
  • removeConversation(conversation_id): quita una conversación de la lista (solo en la página).
  • getLastConversation(): devuelve la última conversación, o false.
  • isConversationsEmpty(): devuelve true si el usuario no tiene conversaciones visibles en el chat.
  • isExtraEmpty(): devuelve true si no hay datos adicionales cargados.
  • delete(onSuccess): elimina al usuario y todas sus conversaciones y mensajes de forma permanente.

Variables:

  • details: los datos del usuario.
  • extra: los datos adicionales.
  • conversations: las conversaciones del usuario (cada una con solo su último mensaje).

✉️ SBMessage

Representa un mensaje.

Uso: new SBMessage(details)

  • details: datos del mensaje, por ejemplo { "id": "2319", "user_id": "377", "message": "¡Hola!", ... }.

Propiedades de solo lectura:

  • id: el ID del mensaje.
  • attachments: la lista de adjuntos.
  • message: el texto del mensaje.

Métodos:

  • get(key): devuelve un dato del mensaje, o una cadena vacía.
  • set(key, value): cambia o añade un dato del mensaje (solo en la página).
  • payload(key, value): lee o escribe los datos adicionales del mensaje. Sin value devuelve el valor de key; con value lo guarda.
  • getCode(): devuelve el HTML del mensaje listo para insertarlo en el chat (procesa adjuntos, mensajes enriquecidos y formato de texto).
  • render(message): aplica el formato de texto (negrita, cursiva, enlaces…). Si le pasas un texto, formatea ese texto.
  • strip(message): quita el formato de texto. Si le pasas un texto, se lo quita a ese texto.

Variables:

  • details: los datos del mensaje.

💬 SBConversation

Representa una conversación.

Uso: new SBConversation(messages, details)

  • messages: lista de objetos SBMessage.
  • details: (opcional) datos de la conversación, por ejemplo { status_code: "2", title: "", department: null, ... }.

Propiedades de solo lectura:

  • id: el ID de la conversación.
  • status_code: el estado de la conversación (0 activa, 1 esperando al usuario, 2 esperando al agente, 3 archivada, 4 papelera).

Métodos:

  • get(key): devuelve un dato de la conversación, o una cadena vacía.
  • set(key, value): cambia o añade un dato (solo en la página).
  • getMessage(id): devuelve el mensaje con ese ID, o false.
  • getLastMessage(): devuelve el último mensaje visible, o false.
  • getLastUserMessage(index, agent): devuelve el último mensaje del usuario (sin contar bot ni agentes). index permite empezar la búsqueda desde otra posición. agent cambia a quién se busca: true (último de un agente), bot (último del bot), no-bot (usuario o agente, sin el bot), all (agente o bot).
  • getNextMessage(message_id, user_type): devuelve el mensaje siguiente al indicado. user_type puede ser user o agent.
  • getUserMessages(user_type): devuelve solo los mensajes de user (por defecto), agents o bot.
  • updateMessage(id, message): reemplaza un mensaje por otro objeto SBMessage (solo en la página).
  • addMessages(messages): añade uno o varios objetos SBMessage (solo en la página).
  • getCode(text_only): devuelve el HTML de la conversación, o solo el texto si text_only es true.
  • deleteMessage(id): quita un mensaje de la conversación (solo en la página).
  • searchMessages(search, exact_match): busca un texto en los mensajes y devuelve los que coinciden. Con exact_match en true busca la coincidencia exacta.
  • getAttachments(): devuelve todos los adjuntos de la conversación.
  • updateMessagesStatus(ids): marca los mensajes como leídos.

Variables:

  • details: los datos de la conversación.
  • messages: la lista de mensajes.

🔣 Variables globales

Variables que puedes definir tú

Defínelas en tu página antes del código de instalación del chat, por ejemplo:

<script>
    var SB_DEFAULT_DEPARTMENT = 2;
</script>
<script id="chat-init" async src="https://chatbot.zampisoft.com/account/js/init.js?id=12345678"></script>
Variable Qué hace
SB_DISABLED Con valor true, el chat no se carga en esa página.
SB_TICKETS Si la defines (con cualquier valor), la página carga el área de Tickets en lugar del chat. Requiere la aplicación Tickets activa.
SB_ARTICLES_PAGE Con valor true, la página muestra la página de artículos de ayuda.
SB_DEFAULT_USER Datos del usuario con el que se identifica automáticamente a los visitantes nuevos. Ejemplo: { first_name: "Juan", last_name: "Pérez", email: "juan@example.com", extra: { phone: ["+573001234567", "Phone"] } }. Si tiene email, no se pide registro. Si ese correo ya existe en ZampiBot, añade password con la contraseña cifrada que devuelve get-user (Web API); si no, el usuario existente no se identifica.
SB_DEFAULT_DEPARTMENT ID del departamento que se asigna a las conversaciones nuevas creadas desde esa página.
SB_DEFAULT_AGENT ID del agente que se asigna a las conversaciones nuevas creadas desde esa página. Combínalo con Ajustes > Misceláneas > Ocultar conversaciones de otros agentes para que solo ese agente las vea.
SB_DEFAULT_TAGS Etiquetas que se añaden a las conversaciones nuevas creadas desde esa página, como lista (["web", "promo"]) o texto separado por comas.
SB_REGISTRATION_REQUIRED Cambia en esa página el registro obligatorio. Valores: false (sin registro), "registration" (formulario de registro), "login" (formulario de inicio de sesión) o "registration-login" (los dos).
SB_LOCAL_SETTINGS Cambia en esa página ajustes del chat. Es un objeto con las claves de los ajustes del chat, por ejemplo { registration_required: false, auto_open: true }. Solo afecta a los ajustes que usa el navegador.

Variables que puedes leer

Variable Qué contiene
SBChat.initialized true si el chat ya se inicializó.
SBChat.conversation La conversación abierta (objeto SBConversation), o false.
SBChat.is_busy true si el chat está ocupado (por ejemplo, enviando un mensaje).
SBChat.chat_open true si la ventana del chat está abierta.
SBChat.agent_id ID del agente de la conversación abierta, o -1.
SBChat.agent_online true si ese agente está conectado.
SBChat.dashboard true si se está mostrando la pantalla de inicio del chat.

⚡ Funciones del chat

SBChat.submit()

Envía lo que el visitante escribió en el editor (texto y adjuntos), igual que si pulsara el botón de enviar, y vacía el editor.

SBChat.sendMessage()

Añade un mensaje a la conversación abierta. Si no hay ninguna, crea una.

  • user_id: el ID de quien envía. Por defecto: -1 (el visitante). Para enviarlo como el bot usa SBF.setting("bot_id").
  • message: el texto.
  • attachments: adjuntos, como lista de pares [["nombre", "url"], ...]. Por defecto: [].
  • onSuccess: función que se ejecuta al terminar: function(response) { ... }. Recibe lo mismo que el evento SBMessageSent.
  • payload: datos adicionales del mensaje, por ejemplo { "origen": "landing" }.
  • conversation_status_code: estado de la conversación (0 a 4). Usa skip para no cambiarlo.

Requiere que haya un usuario activo.

SBChat.updateMessage()

Cambia el texto de un mensaje existente.

  • message_id: el ID del mensaje.
  • message: el nuevo texto.

Un visitante solo puede cambiar sus propios mensajes.

SBChat.sendEmail()

Envía una notificación por correo al destinatario que devuelve SBChat.getRecipientUserID().

  • message: el texto.
  • attachments: adjuntos, como lista de pares [["nombre", "url"], ...].
  • send_to_active_user: true para enviarlo al usuario activo, o un ID de usuario para enviarlo a ese usuario. Por defecto: false.
  • onSuccess: función que se ejecuta al terminar. Por defecto: false.

SBChat.sendSMS()

Envía una notificación por mensaje de texto (SMS) al destinatario que devuelve SBChat.getRecipientUserID(). Requiere las notificaciones de mensajes de texto configuradas en Ajustes > Notificaciones > Notificaciones de mensajes de texto.

  • message: el texto.

SBChat.desktopNotification()

Muestra una notificación del navegador (si el visitante lo permitió).

  • title Requerido: el título.
  • message Requerido: el texto.
  • icon Requerido: la URL del icono.
  • conversation_id: la conversación que se abre al pulsar la notificación.

SBChat.getRecipientUserID()

Devuelve a quién va dirigida una notificación según el contexto: el último agente que respondió en la conversación; si no hay, el agente asignado; si no hay, el departamento; y si tampoco, agents (todos los agentes).

SBChat.initChat()

Inicializa el chat y muestra el botón del chat. Úsala junto con Ajustes > Chat > Inicialización manual: con esa opción activa el chat no aparece hasta que llamas a esta función.

No la pongas dentro del evento SBInit (que solo llega después de inicializar). Usa el evento SBReady.

SBChat.open()

Abre o cierra la ventana del chat.

  • open: false para cerrarla. Por defecto: true.

También puedes añadir 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 o cierra el chat.

SBChat.openConversation()

Abre una conversación del visitante en la ventana del chat.

  • conversation_id Requerido: el ID de la conversación. Solo se pueden abrir conversaciones del visitante; la lista está en SBF.activeUser().conversations.
  • onSuccess: función que se ejecuta cuando la conversación está abierta.
  • onError: función que se ejecuta si no se puede abrir.

SBChat.update()

Busca mensajes nuevos en la conversación abierta. El chat la ejecuta solo; normalmente no necesitas llamarla.

SBChat.populateConversations()

Carga en la pantalla de inicio del chat la lista de conversaciones del visitante.

  • onSuccess: función que se ejecuta al terminar: function(conversations) { ... }.

SBChat.updateConversations()

Actualiza la lista de conversaciones del visitante y comprueba si hay nuevas. El chat la ejecuta solo.

SBChat.newConversation()

Crea una conversación y, opcionalmente, le añade el primer mensaje.

  • status_code: estado inicial (0 activa, 1 esperando al usuario, 2 esperando al agente, 3 archivada, 4 papelera).
  • user_id: el ID del usuario. Por defecto: -1 (el visitante).
  • message: el texto del primer mensaje.
  • attachments: adjuntos del primer mensaje. Por defecto: [].
  • department: ID del departamento. Por defecto: null (se usa SB_DEFAULT_DEPARTMENT si la definiste). Los departamentos se configuran en Ajustes > Misceláneas > Departamentos.
  • agent_id: ID del agente asignado. Por defecto: null (se usa SB_DEFAULT_AGENT si la definiste).
  • onSuccess: función que recibe la conversación creada: function(conversation) { ... }.

Requiere que haya un usuario activo.

SBChat.setConversation()

Convierte una conversación existente en la conversación abierta.

  • conversation: la conversación, como objeto SBConversation.

SBChat.startRealTime()

Activa la comprobación periódica de mensajes nuevos en la conversación abierta.

SBChat.stopRealTime()

Detiene la comprobación periódica de mensajes nuevos.

SBChat.busy()

Muestra u oculta el indicador de carga. Mientras está activo, el chat está «ocupado» y no se pueden enviar mensajes ni adjuntos.

  • value Requerido: true para mostrarlo, false para ocultarlo.

SBChat.lastAgent()

Devuelve el último agente de la conversación abierta.

  • bot: false para no contar al bot. Por defecto: true.
{
    "user_id": "123456",
    "full_name": "Laura Ruiz",
    "profile_image": "https://tu-sitio.com/laura.jpg"
}

SBChat.scrollBottom()

Desplaza el chat hasta el final.

  • top: true para desplazarlo al principio. Por defecto: false.

SBChat.isBottom()

Devuelve true si el chat está desplazado hasta el final.

SBChat.showDashboard()

Muestra la pantalla de inicio del chat.

SBChat.hideDashboard()

Oculta la pantalla de inicio del chat.

SBChat.showPanel()

Muestra un panel dentro del chat.

  • name: el nombre del panel, por ejemplo articles.
  • title: el título que aparece en la cabecera.

SBChat.hidePanel()

Oculta el panel abierto.

SBChat.clear()

Vacía el área de la conversación y deja el chat sin conversación abierta.

SBChat.updateNotifications()

Actualiza el contador rojo del botón del chat.

  • conversation_id Requerido: el ID de la conversación.
  • message_id: el ID de un mensaje sin leer para sumar 1 al contador, o false para restar 1. Por defecto: false.

SBChat.setConversationStatus()

Cambia el estado de la conversación abierta.

  • status_code Requerido: el nuevo estado (0 a 4).

SBChat.typing()

Controla el aviso «escribiendo…» de la cabecera del chat (solo se ve con una conversación abierta).

  • user_id: por defecto -1.
  • action: start para mostrar el aviso, stop para ocultarlo. También acepta check y set, que el chat usa internamente.

SBChat.showArticles()

Muestra el panel de artículos de ayuda, un artículo o una categoría.

  • id: el ID de un artículo (o de una categoría). Sin valor, muestra la lista.
  • is_category: true si id es una categoría.

SBChat.getArticles()

Obtiene artículos y se los pasa a onSuccess.

  • id: ID de un artículo o lista de IDs. Si lo indicas, se devuelve el contenido completo. Por defecto: false (todos).
  • onSuccess Requerido: función que recibe los artículos: function(articles) { ... }.
  • category: devuelve solo los artículos de esa categoría. Por defecto: false.
  • count: número máximo de artículos. Por defecto: false (todos).

Cada artículo de la lista incluye solo un extracto del contenido.

SBChat.getArticleCategories()

Obtiene las categorías de artículos.

  • onSuccess Requerido: función que recibe las categorías: function(categories) { ... }.
  • category_type: parent para obtener solo las categorías principales, normal para obtener solo las demás. Por defecto: false (todas).
[
    {
        "id": "cuenta",
        "title": "Mi cuenta",
        "description": "Preguntas sobre tu cuenta.",
        "image": "https://tu-sitio.com/cuenta.png",
        "parent": true,
        "languages": {},
        "count": 4
    }
]

SBChat.searchArticles()

Busca artículos y muestra los resultados en el buscador de artículos del chat.

  • search Requerido: el texto a buscar (en el título y el contenido).
  • button Requerido: el botón de búsqueda (objeto jQuery).
  • target Requerido: el elemento donde se muestran los resultados (objeto jQuery).

SBChat.setArticleRating()

Guarda la valoración de un artículo.

  • article_id Requerido: el ID del artículo.
  • rating Requerido: 1 para positiva, 0 para negativa.
  • onSuccess: función que se ejecuta al terminar.

SBChat.categoryEmoji()

Muestra una categoría en el selector de emojis.

  • category Requerido: all, Smileys, People, Animals, Food, Travel, Activities, Objects o Symbols.

SBChat.searchEmoji()

Busca emojis y los muestra en el selector de emojis.

  • search Requerido: el texto a buscar.

SBChat.insertText()

Escribe un texto en el editor del chat.

  • text: el texto.

Requiere una conversación abierta.

SBChat.privacy()

Muestra el aviso de privacidad, que el visitante debe aceptar antes de empezar a chatear.

SBChat.popup()

Muestra o cierra el mensaje emergente junto al botón del chat (solo se ve con el chat cerrado).

  • close: true para cerrarlo. Por defecto: false.
  • content: el contenido: { image: "", title: "", message: "" }. Con false se usa el de Ajustes > Mensajes y formularios > Mensaje pop up. Por defecto: false.

SBChat.deleteMessage()

Elimina un mensaje de la base de datos y de la conversación abierta.

  • message_id Requerido: el ID del mensaje (los mensajes de la conversación abierta están en SBChat.conversation.messages).

Un visitante solo puede eliminar mensajes de sus propias conversaciones.

SBChat.registration()

Muestra el formulario de registro o de inicio de sesión, o comprueba si el registro es obligatorio.

  • check: true para solo comprobar si hay que registrarse (devuelve true o false). Por defecto: false.
  • type: registration para el formulario de registro o login para el de inicio de sesión.

SBChat.addUserAndLogin()

Crea un usuario nuevo (visitante) e inicia su sesión. Si definiste SB_DEFAULT_USER, usa esos datos.

  • onSuccess: función que se ejecuta al terminar: function(response) { ... }.
  • lead: true para crearlo como lead en lugar de visitor. Por defecto: false.

response es una lista con los datos del usuario y su sesión cifrada:

[
    {
        "id": "913",
        "profile_image": "https://chatbot.zampisoft.com/script/media/user.svg",
        "first_name": "User",
        "last_name": "#23262",
        "email": null,
        "user_type": "visitor",
        "token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
    },
    "YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
]

SBChat.getDepartmentCode()

Genera el HTML con los datos de un departamento (o de todos) y se lo pasa a onSuccess.

  • department_id: el ID del departamento. Sin valor, devuelve todos.
  • onSuccess Requerido: función que recibe el HTML.

SBChat.offlineMessage()

Envía el mensaje de fuera de horario si corresponde. Requiere una conversación abierta.

SBChat.isInitDashboard()

Devuelve true si el chat se abre mostrando la pantalla de inicio.

SBChat.closeChat()

Archiva la conversación abierta y la quita del chat.

  • update_conversation_status: false para solo quitarla del chat, sin archivarla. Por defecto: true.

SBChat.flashNotification()

Hace parpadear el título de la pestaña del navegador para avisar de un mensaje nuevo.

SBChat.playSound()

Reproduce el sonido de mensaje nuevo.

  • repeat: true para repetirlo las veces configuradas en los ajustes. Por defecto: false.

SBChat.automations.runAll()

Comprueba todas las automatizaciones y ejecuta las que cumplen sus condiciones.

🧩 Aplicaciones

SBApps.is()

Devuelve si una aplicación está activa en el chat.

  • name Requerido: el nombre de la aplicación, por ejemplo tickets.

SBApps.dialogflow.message()

Envía un mensaje al chatbot de inteligencia artificial y añade su respuesta a la conversación abierta.

  • message: el texto.
  • attachments: adjuntos, como lista de pares [["nombre", "url"], ...].
  • audio: URL de un audio para transcribirlo. Por defecto: false.

Requiere el chatbot activo en Ajustes > Inteligencia artificial. Las respuestas consumen créditos de IA (ver Membresía en el portal).

El nombre dialogflow de estas funciones se conserva por compatibilidad: la integración con Dialogflow se retiró y hoy el chatbot funciona con OpenAI.

SBApps.dialogflow.openAI()

Envía un mensaje al chatbot de IA. Si hay una conversación abierta, la respuesta se añade como mensaje nuevo.

  • message Requerido: el texto.
  • onSuccess: función que recibe la respuesta: function(response) { ... }.
  • audio: URL de un audio para transcribirlo. Por defecto: false.
  • attachments: adjuntos. Por defecto: [].

SBApps.dialogflow.active()

Devuelve true si el chatbot va a responder en la conversación abierta, o lo desactiva.

  • active: false para detener el chatbot en la conversación abierta; activate para volver a activarlo. Por defecto: true (solo comprueba).

SBApps.dialogflow.typing()

Muestra el aviso «escribiendo…» del chatbot.

SBApps.dialogflow.humanTakeover()

Pasa la conversación abierta a un agente humano (la acción Derivar a humano de Ajustes > Inteligencia artificial).

SBApps.dialogflow.humanTakeoverActive()

Devuelve true si la conversación abierta ya se pasó a un agente humano.

SBApps.dialogflow.translate()

Traduce varios textos con Google Translate.

  • strings Requerido: lista de textos, por ejemplo ["Hello world", "How are you?"].
  • language_code Requerido: código del idioma de destino, de dos letras. Para chino tradicional usa zt; para chino simplificado, zh; para portugués de Brasil, pt.
  • onSuccess Requerido: función que recibe las traducciones.

🎫 Tickets

Funciones del área de Tickets. Requieren la aplicación Tickets activa y una página que cargue el área de tickets (ver SB_TICKETS).

SBTickets.showPanel()

Muestra un panel o el área de conversación.

  • name: el panel: new-ticket, privacy, articles, edit-profile, login, registration. Vacío para volver al área de conversación.
  • title: el título del panel.

SBTickets.showSidePanels()

Muestra u oculta los paneles laterales.

  • show: false para ocultarlos. Por defecto: true.

SBTickets.setAgent()

Carga los datos de un agente en el panel derecho.

  • agent_id: el ID del agente.

SBTickets.activateConversation()

Abre y muestra una conversación.

  • conversation: la conversación, como objeto SBConversation.

SBTickets.selectConversation()

Marca una conversación de la lista izquierda como la activa.

  • conversation_id: el ID de la conversación.

SBTickets.getActiveConversation()

Devuelve el elemento HTML de la conversación activa.

  • type: ID para obtener solo el ID de la conversación.

📡 Tiempo real

El chat usa una conexión en tiempo real para recibir mensajes al instante. Estas funciones permiten usarla.

SBPusher.init()

Inicia la conexión en tiempo real.

  • onSuccess: función que se ejecuta al terminar.

SBPusher.start()

Activa el tiempo real y las notificaciones push para el usuario activo. Ejecútala después de SBPusher.init() y cuando ya haya un usuario activo.

SBPusher.subscribe()

Suscribe al usuario activo a un canal.

  • channel_name Requerido: el nombre del canal.
  • onSuccess: función que se ejecuta al terminar.

Si la conexión no está iniciada, la inicia.

SBPusher.event()

Ejecuta una función cuando llega un evento a un canal.

  • event Requerido: el nombre del evento.
  • callback Requerido: la función: function(response) { ... }.
  • channel: el canal. Por defecto: el canal privado del usuario activo.

Si hace falta, inicia la conexión y suscribe al usuario al canal.

SBPusher.trigger()

Envía un evento a un canal.

  • event Requerido: el nombre del evento.
  • data: los datos, por ejemplo { "nombre": "valor" }.
  • channel: el canal. Por defecto: el canal privado del usuario activo.

Desde la página de un visitante solo se pueden enviar eventos cuyo nombre empiece por client-. El resto los envía el servidor.

SBPusher.presence()

Suscribe al usuario activo al canal de presencia, que indica quién está conectado.

  • index: el número del canal de presencia. Por defecto: 1.
  • onSuccess: función que se ejecuta al terminar.

SBPusher.presenceUnsubscribe()

Da de baja al usuario activo del canal de presencia.

➕ Otras funciones

SBF.translate()

Traduce un texto del chat al idioma del visitante. Si no hay traducción, devuelve el texto original.

  • string Requerido: el texto.

SBF.activeUser()

Devuelve el usuario activo como objeto SBUser, o false si no hay ninguno.

{
    "details": {
        "id": "914",
        "profile_image": "https://chatbot.zampisoft.com/script/media/user.svg",
        "first_name": "User",
        "last_name": "#23262",
        "email": null,
        "user_type": "visitor",
        "token": "bc308e274473fb685a729abe8a4bf82d3c49cd2f"
    },
    "extra": {},
    "conversations": []
}

SBF.getActiveUser()

Lee del servidor el usuario con sesión iniciada, lo convierte en el usuario activo y se lo pasa a onSuccess.

  • database: true para comprobar también que el usuario existe en la base de datos.
  • onSuccess: función que se ejecuta al terminar.

SBF.ajax()

Llama a una función del servidor del chat. Ver «Llamadas AJAX» más abajo.

SBF.cors()

Hace una petición HTTP a una URL y pasa la respuesta a onSuccess.

  • method: POST o GET. Por defecto: GET.
  • url Requerido: la URL completa.
  • onSuccess Requerido: función que recibe la respuesta.

SBF.null()

Devuelve true si el valor es una cadena vacía, null, "null" o undefined.

  • variable Requerido: el valor a comprobar.

SBF.deactivateAll()

Cierra las ventanas emergentes y paneles abiertos.

SBF.getURL()

Devuelve el valor de un parámetro de la URL, o todos los parámetros.

  • name: el parámetro. Sin valor, devuelve un objeto con todos. Si no existe, devuelve false.
  • url: la URL a analizar. Por defecto: la de la página.

SBF.stringToSlug()

Convierte un texto en un identificador: minúsculas, sin caracteres especiales y con - en lugar de espacios. SBF.slugToString() hace lo contrario.

  • string Requerido: el texto.

SBF.settingsStringToArray()

Convierte un texto con formato nombre:valor,nombre:valor en un objeto { "nombre": "valor", ... }.

  • string Requerido: el texto.

SBF.random()

Devuelve una cadena aleatoria de letras y números.

SBF.isAgent()

Devuelve true si el tipo de usuario es agent, admin o bot.

  • user_type Requerido: el tipo de usuario.

SBF.error()

Muestra un error del chat en la consola y dispara el evento SBError.

  • message Requerido: el mensaje de error, o un objeto Error.
  • function_name: el nombre de la función donde ocurrió.

SBF.errorValidation()

Devuelve true si la respuesta de una llamada AJAX es un error de validación.

  • response Requerido: la respuesta.
  • code: código concreto a comprobar (por ejemplo duplicate-email). Por defecto: cualquier código.

SBF.login()

Inicia la sesión de un usuario, de una de estas dos formas: con correo y contraseña, o con ID de usuario y token de usuario.

  • email: el correo. Si lo usas, indica también password. Por defecto: vacío.
  • password: la contraseña. Por defecto: vacío.
  • user_id: el ID del usuario. Si lo usas, indica también token. Por defecto: vacío.
  • token: el token del usuario (no el token de API de tu cuenta). Lo devuelve la función get-user de la Web API. Por defecto: vacío.
  • onSuccess: función que se ejecuta si el inicio de sesión funciona.
[
    {
        "id": "913",
        "profile_image": "https://chatbot.zampisoft.com/script/media/user.svg",
        "first_name": "Juan",
        "last_name": "Pérez",
        "email": "juan@example.com",
        "user_type": "user",
        "token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
    },
    "YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
]

Devuelve false si los datos no son correctos. La sesión se guarda automáticamente.

SBF.logout()

Cierra la sesión del usuario y recarga la página.

  • reload: false para no recargar. Por defecto: true.

SBF.loginCookie()

Guarda la sesión cifrada del usuario (el segundo valor que devuelven login y add-user-and-login).

  • value: la sesión cifrada.

SBF.reset()

Cierra la sesión, borra todos los datos del chat guardados en el navegador y recarga la página.

SBF.lightbox()

Muestra un contenido en una ventana superpuesta.

  • content: el contenido HTML. Para una imagen: <img src="imagen.jpg">.

SBF.storage()

Guarda o lee un valor en el almacenamiento del navegador (se conserva entre visitas).

  • key Requerido: el nombre del valor.
  • value: el valor a guardar. Sin valor, la función devuelve el guardado.

SBF.storageTime()

Guarda la hora actual con un nombre y, más adelante, comprueba si ya pasaron varias horas.

  • key Requerido: el nombre.
  • hours: las horas a comprobar. Sin este valor, guarda la hora actual.

Con hours, devuelve true si ya pasaron esas horas (o si no había nada guardado) y false si no. Ejemplo: si guardaste a las 5:00 p. m. y compruebas con 3, devuelve true a partir de las 8:00 p. m.

SBF.setting()

Lee o cambia en la página un ajuste del chat.

  • key Requerido: el nombre del ajuste.
  • value: el valor nuevo. Sin valor, devuelve el actual (o false si no existe).

Los nombres usan guion bajo. Algunos útiles: bot_id (ID del bot), bot_name, registration_required, privacy, popup, welcome, follow, chat_manual_init, auto_open, office_hours (true si es horario de atención), articles, init_dashboard, queue, agents_online, rating, language.

let bot_id = SBF.setting("bot_id");

SBF.shortcode()

Convierte un shortcode en una lista con su nombre y sus opciones.

  • shortcode Requerido: el shortcode, por ejemplo [rating title="Valora la conversación" message="Cuéntanos tu experiencia." success="¡Gracias!"].
[
    "rating",
    {
        "title": "Valora la conversación",
        "message": "Cuéntanos tu experiencia.",
        "success": "¡Gracias!"
    }
]

SBF.openWindow()

Abre una página en una ventana nueva.

SBF.loadResource()

Añade un archivo .js o .css a la página.

  • src Requerido: la URL del archivo.
  • is_js: true para archivos .js. Por defecto: false (.css).
  • onLoad: función que se ejecuta cuando el archivo termina de cargarse.

SBF.debounce()

Ejecuta una función una sola vez por intervalo, aunque se llame muchas veces seguidas.

  • bounceFunction Requerido: la función.
  • id Requerido: un identificador único para esta espera. No uses #1, #2, #3…, que están reservados.
  • interval: el tiempo mínimo entre ejecuciones, en milisegundos. Por defecto: 500.

SBF.escape()

Escapa un texto para insertarlo en HTML de forma segura.

  • string Requerido: el texto.

SBF.convertUTCDateToLocalDate()

Convierte una fecha UTC a la hora local del navegador.

  • datetime Requerido: la fecha, en formato AAAA-MM-DD HH:MM:SS.
  • utc_offset: un desfase horario. Por defecto: 0.

SBF.getLocationTimeString()

Genera un texto con la hora local y el lugar del usuario, por ejemplo 05:15 AM in London, United Kingdom, y se lo pasa a onSuccess.

  • details Requerido: los datos de ubicación, por ejemplo { "timezone": "", "country": "", "city": "" }. Acepta los datos adicionales de un usuario: SBF.getLocationTimeString(SBF.activeUser().extra, function (texto) { ... }).
  • onSuccess Requerido: función que recibe el texto.

SBF.beautifyTime()

Convierte una fecha a un formato local más legible.

  • datetime Requerido: la fecha, en formato AAAA-MM-DD HH:MM:SS (las fechas se guardan en UTC).
  • extended: true para incluir la hora. Por defecto: false.
  • future: true si es una fecha futura. Por defecto: false.

SBF.dateDB()

Convierte una fecha al formato de la base de datos, en UTC.

  • date Requerido: la fecha, en formato AAAA-MM-DD HH:MM:SS. Usa now para la fecha y hora actuales.

SBF.UTC()

Devuelve una fecha como marca de tiempo Unix (en milisegundos), aplicando la zona horaria configurada en Ajustes > Misceláneas (opción Zona horaria).

  • datetime Requerido: la fecha.

SBF.unix()

Devuelve una fecha con formato AAAA-MM-DD HH:MM:SS como marca de tiempo Unix (en milisegundos).

  • datetime Requerido: la fecha.

⚡ Eventos

Los eventos te avisan de lo que pasa en el chat para que puedas ejecutar tu propio código.

Uso

Escucha el evento con jQuery. Cambia NOMBRE-DEL-EVENTO por el nombre del evento. response contiene los datos del evento (si los tiene).

$(document).on("NOMBRE-DEL-EVENTO", function (e, response) {
    // Tu código aquí
});

Ejemplo:

$(document).on("SBMessageSent", function (e, response) {
    console.log(response["user_id"]);
    console.log(response["conversation_id"]);
    console.log(response["message"]);
});

SBReady

Se dispara cuando el script del chat terminó de cargarse, antes de inicializar el chat.

SBInit

Se dispara cuando el chat terminó de inicializarse.

SBTicketsInit

Se dispara cuando el área de Tickets terminó de inicializarse. Solo con la aplicación Tickets activa.

SBActiveUserLoaded

Se dispara cuando se cargaron los datos del usuario activo. response son esos datos.

SBGetUser

Se dispara cuando se leen del servidor los datos de un usuario. response es el usuario (objeto SBUser).

SBLogout

Se dispara cuando el usuario activo cierra la sesión.

SBError

Se dispara cuando ocurre un error en el chat.

  • message: el mensaje de error.
  • function_name: la función donde ocurrió.

SBDoubleLoginError

Se dispara al iniciar el chat si en ese navegador ya hay una sesión de agente o administrador.

SBUserDeleted

Se dispara cuando se elimina un usuario. response es su ID.

SBMessageSent

Se dispara cuando se envía un mensaje desde el chat.

  • user_id: el ID de quien envió el mensaje.
  • user: el usuario activo (objeto SBUser).
  • conversation_id: el ID de la conversación.
  • conversation: la conversación (objeto SBConversation).
  • conversation_status_code: el estado de la conversación.
  • message_id: el ID del mensaje.
  • message: el texto.
  • attachments: los adjuntos.
  • payload: los datos adicionales del mensaje.

SBSMSSent

Se dispara cuando se envía una notificación por mensaje de texto.

  • recipient_id: el ID del destinatario.
  • message: el texto.
  • response: la respuesta de Twilio.

SBNotificationsSent

Se dispara después de enviar un mensaje, con la lista de notificaciones (correo, SMS, push) que se enviaron por él.

SBNotificationsUpdate

Se dispara cuando cambia el contador rojo del botón del chat.

  • conversation_id: el ID de la conversación.
  • message_id: el ID del mensaje sin leer (el contador sube 1), o false (el contador baja 1).

SBConversationOpen

Se dispara cuando una conversación se terminó de cargar y se abrió en el chat. response es la conversación (objeto SBConversation).

SBNewMessagesReceived

Se dispara cuando llegan mensajes nuevos a la conversación abierta.

  • messages: lista de objetos SBMessage.
  • conversation_id: el ID de la conversación.

SBMessageDeleted

Se dispara cuando se elimina un mensaje. response es su ID.

SBNewConversationReceived

Se dispara cuando el visitante recibe una conversación nueva. response es la conversación (objeto SBConversation).

SBActiveConversationChanged

Se dispara cuando cambia la conversación abierta. response es la nueva conversación (objeto SBConversation).

SBActiveConversationStatusUpdated

Se dispara cuando cambia el estado de la conversación abierta.

  • conversation_id: el ID de la conversación.
  • status_code: el nuevo estado (0 a 4).

SBPopulateConversations

Se dispara cuando se cargó la lista de conversaciones del visitante.

  • conversations: lista de objetos SBConversation.

SBChatOpen

Se dispara cuando se abre la ventana del chat.

SBChatClose

Se dispara cuando se cierra la ventana del chat.

SBQueueUpdate

Se dispara cuando el visitante entra en la cola de espera y cada vez que avanza. response es su posición; 0 significa que ya puede chatear.

SBBusy

Se dispara cuando el chat pasa a estar ocupado o deja de estarlo. response es true (ocupado) o false.

SBDashboard

Se dispara cuando se muestra la pantalla de inicio del chat.

SBDashboardClosed

Se dispara cuando se cierra la pantalla de inicio y se muestra una conversación.

SBScreenChange

Se dispara cuando el visitante cambia de pantalla en la barra de navegación del chat.

  • id: el identificador de la pantalla.
  • external: true si la pantalla es un enlace externo.

SBTyping

Se dispara cuando aparece o desaparece el aviso «escribiendo…». response es true o false.

SBArticles

Se dispara cuando se muestra el panel de artículos, un artículo o una categoría.

  • id: el ID del artículo o de la categoría.
  • articles: los artículos mostrados.
  • categories: las categorías (cuando se muestra la lista de categorías).

SBPrivacy

Se dispara al iniciar el chat si se muestra el aviso de privacidad.

SBPopup

Se dispara cuando se muestra el mensaje emergente. response es su contenido: { image: "", title: "", message: "" }.

SBFollowUp

Se dispara cuando se envía el mensaje de seguimiento.

SBWelcomeMessage

Se dispara cuando se envía el mensaje de bienvenida.

SBLoginForm

Se dispara cuando el visitante inicia sesión desde el formulario de inicio de sesión del chat. response es el usuario (objeto SBUser).

SBRegistrationForm

Se dispara cuando el visitante se registra desde el formulario de registro del chat, o actualiza su registro desde un mensaje enriquecido.

  • user: los datos del usuario.
  • extra: los datos adicionales.

SBRichMessageShown

Se dispara cuando se muestra un mensaje enriquecido que se carga aparte.

  • name: el nombre del mensaje enriquecido.
  • settings: sus opciones.
  • response: su HTML.

SBRichMessageSubmit

Se dispara cuando el visitante envía un mensaje enriquecido (por ejemplo un formulario) y llega la respuesta.

  • result: la respuesta.
  • data: los datos del mensaje enriquecido y lo que envió el visitante.
  • id: el ID del mensaje enriquecido.

SBAttachments

Se dispara cuando el visitante adjunta un archivo.

SBNewEmailAddress

Se dispara cuando el visitante deja su correo en el mensaje de seguimiento o en el formulario de registro.

  • name: el nombre completo.
  • email: el correo.
  • id: el ID del mensaje enriquecido (si lo hay).

SBPanelActive

Se dispara cuando se abre un panel del área de Tickets. response es el nombre del panel (new-ticket, privacy, articles, edit-profile, login, registration); vacío si se vuelve al área de conversación. Solo con la aplicación Tickets activa.

SBOpenAIMessage

Se dispara cuando el chatbot de IA devuelve una respuesta.

  • response: la respuesta.
  • message: el mensaje del visitante.

🔄 Llamadas AJAX

Desde la página puedes llamar directamente a funciones del servidor del chat con SBF.ajax(). Usan los mismos nombres y parámetros que la Web API , pero sin token: se ejecutan con la sesión del visitante, y el servidor solo permite lo que ese visitante tiene derecho a hacer.

SBF.ajax({
    function: "NOMBRE-DE-LA-FUNCION",
    parametro: "valor",
    otro_parametro: "valor"
}, (response) => {
    // Tu código aquí
});

Nunca pongas tu token de API en el código de una página. Cualquiera podría verlo y controlar tu cuenta.

Qué funciones puede usar un visitante

Disponibles para cualquiera (el servidor comprueba los datos dentro de cada función): add-user-and-login, login, logout, send-message, update-messages-status, transcript, get-articles, search-articles, get-articles-categories, article-ratings, get-departments, get-agent, get-translation, get-translations, chat-css, automations-run, automations-validate, subscribe-email.

Solo con los datos del propio visitante (sus conversaciones y mensajes): get-user, get-user-extra, update-user, update-user-to-lead, update-login, get-avatar, new-conversation, get-conversation, get-user-conversations, get-new-user-conversations, search-user-conversations, update-conversation-status, update-conversation-department, update-conversation-agent, get-agents-in-conversation, get-new-messages, update-message, delete-message, send-email, set-rating, update-tags, execute-bot-message, human-takeover, open-ai-message, translate-string, google-translate, is-allowed-extension, update-user-and-message, user-autodata.

No disponibles para visitantes (solo agentes o administradores con sesión en el panel): por ejemplo get-users, get-conversations, search-conversations, get-notes, add-note, add-user, send-custom-email, direct-message, push-notification, pusher-trigger, close-message, get-settings, save-settings. Para estas usa la Web API desde tu servidor.

Funciones que solo existen por AJAX

add-user-and-login

Crea un usuario e inicia su sesión. Devuelve los datos del usuario y la sesión cifrada (guárdala con SBF.loginCookie()).

  • settings Requerido: datos del usuario, por ejemplo { first_name: "Juan", last_name: "Pérez", email: "juan@example.com" }.
  • settings_extra: datos adicionales, con la forma { "phone": ["+573001234567", "Phone"] }.

Otras respuestas posibles: duplicate-email, duplicate-phone.

update-user-and-message

Actualiza los datos de un usuario y el contenido de un mensaje en una sola llamada. Un visitante solo puede actualizarse a sí mismo y sus propios mensajes.

  • user_id Requerido: el ID del usuario.
  • settings: datos del usuario, por ejemplo { first_name: "Juan", last_name: "Pérez", email: "juan@example.com" }.
  • settings_extra: datos adicionales, con la forma { "phone": ["+573001234567", "Phone"] }.
  • message_id: el ID del mensaje a actualizar.
  • message: el nuevo texto.
  • payload: datos adicionales del mensaje, por ejemplo {"rich-messages":{"123":{"type":"buttons","result":"Plan Premium"}}}.

Devuelve true.

user-autodata

Detecta y guarda datos del usuario activo: IP, ciudad, ubicación, país, zona horaria, moneda, navegador, idioma del navegador y sistema operativo.

  • user_id Requerido: el ID del usuario.

Devuelve true.

get-agent

Devuelve los datos públicos de un agente, administrador o bot.

  • agent_id Requerido: el ID del agente.
{
    "id": "2",
    "first_name": "Laura",
    "last_name": "Ruiz",
    "profile_image": "https://tu-sitio.com/laura.jpg",
    "department": null,
    "user_type": "agent",
    "act_as_agent": true,
    "flag": "co.png",
    "details": [
        {
            "slug": "country",
            "name": "Country",
            "value": "CO"
        },
        {
            "slug": "timezone",
            "name": "Timezone",
            "value": "America/Bogota"
        }
    ]
}

Solo incluye los datos públicos del agente: país, zona horaria, ciudad y ubicación.