Guía de Integración

Tutoriales y ejemplos para integrar AssistantAI en diferentes plataformas

Integración Básica

Sigue estos pasos para integrar AssistantAI en tu sitio web:

Obtén tu Client ID

Accede a tu panel de administración y copia tu Client ID desde la sección de configuración del widget.

Incluye el Script

Agrega el script del widget antes del cierre de la etiqueta </body> en tu HTML:

                    <script src="https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID"></script>
                

Personaliza la Configuración

Accede al panel de administración para personalizar colores, posición, mensajes y comportamiento del widget.

Configura tu Base de Conocimiento

Crea y sube documentos a tu base de conocimiento para que el asistente pueda responder preguntas.

¡Listo! El widget estará funcionando en tu sitio web.

Integraciones por Plataforma

WordPress

Integra el widget en tu sitio WordPress:

Ve a Apariencia → Editor de Temas
Edita el archivo footer.php
Agrega el script antes de </body>:

                <?php
// Agregar antes de </body>
?>
<script src="https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID"></script>
</body>
            

Alternativa: Usa un plugin como "Insert Headers and Footers" para agregar el script sin editar archivos.

React

Integra el widget en una aplicación React:

                import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Crear y cargar el script
    const script = document.createElement('script');
    script.src = 'https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID';
    script.async = true;
    document.body.appendChild(script);
    
    // Limpiar al desmontar
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);
  
  return (
    <div className="App">
      <h1>Mi Aplicación</h1>
      {/* Tu contenido aquí */}
    </div>
  );
}

export default App;
            

Vue.js

Integra el widget en una aplicación Vue.js:

                <template>
  <div id="app">
    <h1>Mi Aplicación</h1>
    <!-- Tu contenido aquí -->
  </div>
</template>

<script>
export default {
  name: 'App',
  mounted() {
    // Cargar el script del widget
    const script = document.createElement('script');
    script.src = 'https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID';
    script.async = true;
    document.body.appendChild(script);
  },
  beforeUnmount() {
    // Limpiar si es necesario
    const script = document.querySelector('script[src*="assistant-widget"]');
    if (script) {
      document.body.removeChild(script);
    }
  }
}
</script>
            

Angular

Integra el widget en una aplicación Angular:

                import { Component, OnInit, OnDestroy } from '@angular/core';

@Component({
  selector: 'app-root',
  template: '<h1>Mi Aplicación</h1>'
})
export class AppComponent implements OnInit, OnDestroy {
  private script: HTMLScriptElement | null = null;
  
  ngOnInit() {
    // Cargar el script del widget
    this.script = document.createElement('script');
    this.script.src = 'https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID';
    this.script.async = true;
    document.body.appendChild(this.script);
  }
  
  ngOnDestroy() {
    // Limpiar al desmontar
    if (this.script && document.body.contains(this.script)) {
      document.body.removeChild(this.script);
    }
  }
}
            

Next.js

Integra el widget en una aplicación Next.js:

                // pages/_app.js o app/layout.js
import { useEffect } from 'react';
import Script from 'next/script';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID"
        strategy="afterInteractive"
      />
    </>
  );
}

export default MyApp;
            

Shopify

Integra el widget en tu tienda Shopify:

Ve a Configuración → Temas → Acciones → Editar código
Busca el archivo theme.liquid
Agrega el script antes de </body>:

                <!-- Assistant Virtual IA Widget -->
<script src="https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID"></script>
<!-- End Widget -->
</body>
            

Integración con API REST

Si prefieres integrar directamente con la API REST en lugar del widget, aquí tienes ejemplos para diferentes lenguajes:

JavaScript (Fetch API)

            async function sendQuery(query, knowledgeBaseId) {
  const response = await fetch('https://tu-dominio.com/api/v1/chat/query', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      apiKey: 'TU_API_KEY',
      query: query,
      knowledgeBaseId: knowledgeBaseId,
      topK: 5
    })
  });
  
  if (!response.ok) {
    throw new Error('Error en la solicitud');
  }
  
  const data = await response.json();
  return data.answer;
}

// Uso
const answer = await sendQuery('¿Cuáles son los horarios?', 'kb-123-456');
console.log(answer);
        

Python

            import requests

def send_query(query, knowledge_base_id, api_key):
    url = 'https://tu-dominio.com/api/v1/chat/query'
    payload = {
        'apiKey': api_key,
        'query': query,
        'knowledgeBaseId': knowledge_base_id,
        'topK': 5
    }
    
    response = requests.post(url, json=payload)
    response.raise_for_status()
    return response.json()['answer']

# Uso
answer = send_query('¿Cuáles son los horarios?', 'kb-123-456', 'TU_API_KEY')
print(answer)
        

PHP

            <?php
function sendQuery($query, $knowledgeBaseId, $apiKey) {
    $url = 'https://tu-dominio.com/api/v1/chat/query';
    $data = [
        'apiKey' => $apiKey,
        'query' => $query,
        'knowledgeBaseId' => $knowledgeBaseId,
        'topK' => 5
    ];
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    $result = json_decode($response, true);
    return $result['answer'];
}

// Uso
$answer = sendQuery('¿Cuáles son los horarios?', 'kb-123-456', 'TU_API_KEY');
echo $answer;
?>
        

C# (.NET)

            using System.Net.Http;
using System.Text;
using System.Text.Json;

public class AssistantClient
{
    private readonly HttpClient _httpClient;
    private readonly string _apiKey;
    private readonly string _baseUrl;
    
    public AssistantClient(string apiKey, string baseUrl = "https://tu-dominio.com")
    {
        _httpClient = new HttpClient();
        _apiKey = apiKey;
        _baseUrl = baseUrl;
    }
    
    public async Task<string> SendQueryAsync(string query, string knowledgeBaseId)
    {
        var payload = new
        {
            apiKey = _apiKey,
            query = query,
            knowledgeBaseId = knowledgeBaseId,
            topK = 5
        };
        
        var json = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await _httpClient.PostAsync($"{_baseUrl}/api/v1/chat/query", content);
        response.EnsureSuccessStatusCode();
        
        var responseJson = await response.Content.ReadAsStringAsync();
        var result = JsonSerializer.Deserialize<JsonElement>(responseJson);
        
        return result.GetProperty("answer").GetString();
    }
}

// Uso
var client = new AssistantClient("TU_API_KEY");
var answer = await client.SendQueryAsync("¿Cuáles son los horarios?", "kb-123-456");
Console.WriteLine(answer);
        

Mejores Prácticas

Seguridad

Nunca expongas tu API Key en el frontend: Si usas la API REST directamente, crea un endpoint backend que maneje las solicitudes.
Usa HTTPS: Asegúrate de que tu sitio use HTTPS para proteger las comunicaciones.
Valida las solicitudes: Implementa validación en el servidor antes de enviar consultas a la API.

Rendimiento

Carga asíncrona: Usa async al cargar el script del widget para no bloquear la carga de la página.
Lazy Loading: Considera cargar el widget solo cuando el usuario interactúe con él.
Caché: El script del widget se cachea automáticamente, pero puedes configurar headers de caché adicionales.

Experiencia de Usuario

Mensajes claros: Personaliza el mensaje de bienvenida para que sea relevante para tu audiencia.
Posición adecuada: Elige una posición que no interfiera con el contenido principal.
Responsive: El widget es responsive por defecto, pero verifica que funcione bien en dispositivos móviles.

Soporte

¿Necesitas ayuda con la integración? Estamos aquí para ayudarte:

Documentación: Revisa la documentación de la API para detalles técnicos.
Ejemplos: Consulta los ejemplos de código en esta página.
Contacto: Si tienes preguntas específicas, contáctanos a través del panel de administración.

Nota: Para problemas técnicos o preguntas sobre la integración, consulta primero la documentación. Si el problema persiste, nuestro equipo de soporte estará encantado de ayudarte.