Añade una mascota de IA que habla a tu web con Wixzel Voice

¿Qué necesitas antes de empezar?

• Una cuenta de Wixzel Voice con crédito. Las llamadas desde el widget se pagan con crédito real, no con los minutos de prueba gratuitos; la recarga mínima es de $5.
• Una clave de API con los permisos agents:write y calls:write, guardada en tu servidor. Todo lo de abajo también se puede hacer en la consola, en la pestaña Mascota del agente.
• Un sitio web servido por HTTPS en el que puedas añadir una etiqueta script. Los navegadores solo dan acceso al micrófono a una página servida por HTTPS.

¿Cómo construyes esto en Wixzel Voice, paso a paso?

1. 01Crea el agente a partir de tu sitio web

   Dale tu sitio y un rol. role es receptionist, support, sales, guide o tus propias palabras:

   shellCopiar

   curl https://api.voice.wixzel.com/v1/agents/generate \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "website_url": "https://smiledental.example", "role": "receptionist" }'

   make-agent.mjs (TypeScript SDK)Copiar

   import { WixzelVoice, waitForAgent } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   let agent = await client.agents.generate({
     website_url: 'https://smiledental.example',
     role: 'receptionist',
   });
   agent = await waitForAgent(client.agents, agent); // until the mascot is ready or failed
   console.log(agent.id, agent.name, agent.mascot.status, agent.knowledge_base_id);

   Responde al instante con un agente que ya puede hablar y mascot.status: "building". En segundo plano lee tus páginas, escribe las instrucciones y la frase de apertura, crea una base de conocimiento con lo que leyó y dibuja una mascota con el color de tu marca. Consulta GET /v1/agents/{id} hasta que mascot.status sea ready, normalmente en menos de un minuto; en el SDK, waitForAgent hace esas consultas. Si la creación falla, el agente sigue funcionando con el aspecto que tenía.

   El agente empieza con Gemini Live. Cambia su motor, su voz o sus instrucciones como en cualquier otro agente con PATCH /v1/agents/{id}; su mascota se queda como está.

2. 02Activa el widget y elige quién puede llamar

   La opción de compartir está desactivada hasta que la actives. Indica los orígenes desde los que se sirve tu sitio; el widget no iniciará una llamada en ningún otro:

   shellCopiar

   curl -X PATCH https://api.voice.wixzel.com/v1/agents/AGENT_ID/mascot \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "welcome_message": "Hi! I am Molly from Smile Dental. Tap Call to talk to me.",
       "sharing": {
         "embed": true,
         "embed_origins": ["https://smiledental.example", "https://www.smiledental.example"],
         "caller_info": "contact",
         "max_call_seconds": 300,
         "daily_minutes": 60,
         "calls_per_visitor_daily": 3,
         "max_concurrent_calls": 2
       }
     }'

   caller_info es lo que un visitante te da antes de una llamada: none (el valor predeterminado) no pide nada, contact pide un nombre y un teléfono o un correo electrónico, y google pide iniciar sesión con Google. El inicio de sesión con Google te dice quién es y nunca le crea una cuenta de Wixzel; en tu sitio se abre en una ventana pequeña en voice.wixzel.com, que devuelve el resultado solo a un origen incluido en embed_origins.

   Los cuatro límites mantienen las llamadas públicas dentro de un presupuesto: la duración máxima de una llamada, los minutos públicos al día para todos en conjunto (hasta la medianoche UTC), las llamadas que un visitante puede hacer al día y las llamadas simultáneas. Los valores de arriba son los predeterminados. Añade "link": true para tener también una página para compartir en voice.wixzel.com/m?id=….

   La respuesta incluye mascot.public_id, como m_4fT9qLx2Bv8K. Es el id que va en la etiqueta script.

3. 03Pega una etiqueta script

   Añade esto a cada página que deba mostrar la mascota, antes de la etiqueta de cierre de body:

   index.htmlCopiar

   <script src="https://voice.wixzel.com/embed.js" data-mascot="m_4fT9qLx2Bv8K" async></script>

   La mascota espera en la esquina inferior derecha con su mensaje de bienvenida. Un visitante toca Call, permite el micrófono y habla; la mascota escucha, piensa y mueve la boca con la voz del agente. El widget funciona dentro de un shadow root, así que tu CSS y el suyo nunca se mezclan.

4. 04Colócala donde quieras y deja que el agente actúe en tu página

   Para mostrarla dentro de tu propio elemento en lugar de en la esquina, quita data-mascot de la etiqueta y llama a WixzelMascot.mount cuando el script se haya cargado.

   Una herramienta de cliente se ejecuta en tu página cuando el agente la pide, por ejemplo para abrir la página de reservas. Crea la herramienta para el agente en la consola o con POST /v1/tools y luego registra lo que hace, antes o después de que cargue el script:

   index.htmlCopiar

   <div id="talk"></div>
   <script>
     window.WixzelMascot = Object.assign(window.WixzelMascot || {}, {
       tools: {
         open_page: ({ path }) => {
           location.href = path;
           return { opened: path };
         },
       },
     });
   </script>
   <script
     src="https://voice.wixzel.com/embed.js"
     async
     onload="WixzelMascot.mount(document.getElementById('talk'), { mascot: 'm_4fT9qLx2Bv8K' })"
   ></script>

   Lo que devuelva un handler vuelve al agente, que se lo dice a quien llama. Las herramientas webhook, que llaman a tu servidor, también funcionan en el widget.

5. 05Mira quién llamó y bloquea a alguien

   Cada llamada desde el widget registra a quien llama. Lista las personas que han llamado a un agente:

   shellCopiar

   curl "https://api.voice.wixzel.com/v1/callers?agent_id=AGENT_ID&limit=20" \
     -H "Authorization: Bearer $WIXZEL_API_KEY"
   
   curl -X PATCH https://api.voice.wixzel.com/v1/callers/CALLER_ID \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "blocked": true }'

   Cada persona que llama tiene una location aproximada (ciudad, región y país, calculados a partir de la dirección IP, que solo se guarda como hash), platform (navegador, sistema operativo y dispositivo), la page_url desde la que llamó, lo que te dio y call_count. Un id aleatorio que guarda su navegador agrupa las llamadas de una misma persona; no se usa huella digital del navegador (fingerprinting), y el widget le dice a quien llama qué se comparte contigo.

   Una persona bloqueada no puede volver a llamar a ese agente desde el widget, el enlace para compartir, la app ni por teléfono. Cada llamada también está en GET /v1/calls con su transcripción y su costo, y se puede filtrar por caller_id.

¿Cuánto cuesta esto en Wixzel Voice?

¿Qué límites de Wixzel Voice se aplican a esto?

• El audio es de calidad telefónica, G.711 µ-law a 8 kHz en ambas direcciones.
• El widget solo inicia llamadas desde los orígenes de embed_origins, hasta 20.
• Las llamadas públicas se mantienen dentro de los límites del agente. Pasado daily_minutes, las llamadas se rechazan hasta la medianoche UTC.
• Las llamadas del widget cuentan para el límite de llamadas simultáneas de la cuenta, cinco por defecto, junto con las llamadas telefónicas y las sesiones de apps. max_concurrent_calls evita que una página con mucho tráfico las ocupe todas.
• Las llamadas del widget usan crédito real. Los minutos de prueba gratuitos son para hablar con tus propios agentes desde la consola.
• Desde una llamada web no se puede transferir a una persona; las transferencias necesitan una línea telefónica.