Hoe we een voice assistant maakten die écht iets kan

Bij Sping geloven we niet in technologie om de technologie, maar in het oplossen van complexe problemen met slimme architectuur. De komst van de OpenAI Realtime API opende een deur: we konden eindelijk praten met software zonder de vertraging van traditionele Text-to-Speech en vervolgens Speech-to-Text.

Maar een pratende AI is slechts de helft van het verhaal. De echte waarde zit in Agency: het vermogen van de AI om daadwerkelijk acties uit te voeren in jouw systemen.

In dit artikel duiken we onder de motorkap van AI Dialog, onze interne tool die spraak, WebRTC en HubSpot CRM combineert tot een naadloze assistent die niet alleen alle mogelijke CRM-acties in HubSpot kan uitvoeren, maar dit ook sneller doet dan een mens.

Om een stabiele en veilige voice-ervaring te bieden, kozen we voor een gesplitste stack:

1. 1. Next.js (Frontend/UI): Verantwoordelijk voor de WebRTC-client, het opvangen van audio en het tonen van real-time transcripties.
   2. NestJS (Backend): Onze "security gateway". Hier leeft de authenticatie, de token-opslag voor HubSpot en de proxy die API-aanroepen valideert.
   3. OpenAI Realtime API: De motor die audio verwerkt, taal begrijpt en besluit welke acties (tools) uitgevoerd moeten worden.

Stap 1: De Veilige Handshake (WebRTC)

Traditionele API-keys wil je nooit in de frontend hebben. Daarom maken we gebruik van een ephemeral token (een tijdelijk geheim).

Eerst vraagt onze Next.js route een sessie aan bij OpenAI. Hier geven we direct de persoonlijke instructies voor de assistent mee.

TypeScript

De frontend haalt dit token op en start de WebRTC-handshake via SDP (Session Description Protocol).

TypeScript

Stap 2: Slimme Turn-Detection en VAD

Niets is irritanter dan een AI die je in de rede valt omdat je even ademhaalt. Daarom configureren we het datakanaal met Semantic VAD (Voice Activity Detection). Door de eagerness op low te zetten, voorkom je dat de assistent reageert op achtergrondgeluid of een kuchje.

TypeScript

Stap 3: De "Generic Tool" Strategie voor HubSpot

Dit is waar het project echt slim wordt. In plaats van voor elke HubSpot-actie (zoals createContact of updateDeal) een aparte functie te programmeren, gaven we de AI één krachtige tool: de hubspotApi.

Door de AI toegang te geven tot een generieke methode, hoeven we geen honderden regels code te onderhouden voor elke mogelijke CRM-actie.

TypeScript

API-docs in de Prompt

Hoe weet de AI welk pad hij moet gebruiken? We injecteren de documentatie van de HubSpot API direct in de system instructions. We leggen het model uit hoe search operators werken en hoe je een 'Note' koppelt aan een 'Deal'. De AI fungeert hier dus als een developer die de documentatie on-the-fly leest en toepast.

Stap 4: Security & Proxy Hardening

Vrijheid is goed, maar veiligheid is essentieel. De browser praat nooit rechtstreeks met HubSpot. Elke tool-call gaat via onze NestJS-backend. Hier voeren we een aantal cruciale checks uit:

1. Path Traversal Check: We blokkeren elk pad dat .. bevat, om zo te voorkomen dat de gebruiker ‘uitbreekt’ en de proxy voor andere doeleinden kan gebruiken.
2. Scope Filtering: Het pad moet beginnen met /crm/. De AI kan dus nooit bij instellingen of gebruikersbeheer komen.
3. Token Management: De HubSpot OAuth-tokens worden veilig server-side opgeslagen en ververst. De frontend weet alleen: "HubSpot is verbonden".

TypeScript

De "Loop": Van actie naar bevestiging

Wanneer de AI een tool aanroept, stopt de audio-output. De frontend voert de call uit, stuurt het resultaat terug naar OpenAI via het datakanaal, en vraagt om een nieuwe response. Hierdoor kan de AI verbaal bevestigen: "Ik heb de deal aangemaakt en een notitie toegevoegd aan het contact."

TypeScript

Conclusie

Door OpenAI's Realtime model te combineren met een rigoureuze backend-proxy en een generieke tool-opzet, hebben we een assistent gebouwd die niet alleen sneller reageert dan een mens, maar ook complexe CRM-taken foutloos uitvoert.

De toekomst van software is niet meer klikken en typen, maar praten tegen systemen die je context begrijpen en de juiste gereedschappen in handen hebben. Bij Sping zijn we er klaar voor.

Benieuwd hoe we Agentic AI kunnen inzetten voor jouw infrastructuur? Laten we een (spraak)gesprek plannen.

(Disclaimer: we gebruikten AI om dit artikel lekker leesbaar te maken en interessante code snippets te laten kiezen. Maar de inhoud komt niet uit een korte prompt, maar is wel door onszelf getypt)