Een AI-assistent in WhatsApp: zo herbouw je die koppeling stap voor stap

Wat je gaat bouwen

Het hele systeem bestaat uit twee programma's die naast elkaar op één server draaien, plus een AI-model:

• De brug — een klein programma (wij schreven het in Go) dat als gekoppeld apparaat aan je WhatsApp hangt, net als WhatsApp Web. Het ontvangt elk bericht en kan berichten versturen.
• Het tussenprogramma — een webserver (bij ons Python) die elk binnenkomend bericht aanneemt, er een opdracht voor het AI-model van maakt en het antwoord terugstuurt.
• Het geheugen — een database waarin per gesprek alle berichten staan, zodat de assistent weet wat er eerder is gezegd.

De route van één bericht: jouw telefoon → WhatsApp → de brug → het tussenprogramma → het AI-model → het tussenprogramma → de brug → terug in je chat. De brug en het tussenprogramma praten met elkaar via twee lokale poorten op dezelfde server — er hoeft niets van deze keten open op internet.

Benodigdheden

• Een Linux-server of VPS (1 CPU en 1 à 2 GB geheugen is genoeg om te starten)
• Go 1.21 of nieuwer, voor de brug
• Python 3.11 of nieuwer, voor het tussenprogramma
• Een opensource WhatsApp-bibliotheek; wij gebruiken whatsmeow, die het apparaat-koppelprotocol van WhatsApp spreekt
• Toegang tot een AI-model: een API-sleutel van een aanbieder, of een AI-tool die je vanaf de commandoregel kunt aanroepen
• SQLite (zit vrijwel overal standaard bij) voor sessie en berichtgeschiedenis
• Optioneel: ffmpeg en een spraak-naar-tekstmodel zoals Whisper, voor spraakberichten

Je hebt géén apart telefoonnummer nodig: de brug koppelt als extra apparaat aan een bestaand WhatsApp-account. Voor zakelijk gebruik is een tweede nummer wel netter.

Fase 1 — de brug: verbinding maken met WhatsApp

De brug doet maar twee dingen: verbonden blijven en berichten doorgeven. Zo zet je hem op:

1. Maak een nieuw Go-project en voeg de WhatsApp-bibliotheek toe als afhankelijkheid.
2. Laat de bibliotheek haar sessie opslaan in een lokaal SQLite-bestand — daardoor blijft de koppeling bestaan na een herstart.
3. Start het programma: bij de eerste keer verschijnt een QR-code in de terminal.
4. Scan die QR-code met je telefoon via WhatsApp → Gekoppelde apparaten, precies zoals bij WhatsApp Web.
5. Registreer een event-handler die afgaat bij elk binnenkomend bericht.
6. Sla in die handler elk bericht op in een tweede SQLite-database met twee tabellen: één voor gesprekken (chat-ID, naam, laatste bericht) en één voor berichten (ID, chat-ID, afzender, tekst, tijdstip, van-mij-of-niet).

Test dit eerst los: stuur jezelf een appje en kijk of het in de database verschijnt. Pas als dit staat, ga je verder.

Fase 2 — de brug als doorgeefluik: webhook en verstuur-API

De brug moet berichten kunnen doorgeven én versturen. Daarvoor krijgt hij twee gezichten:

1. Geef de brug een kleine HTTP-server op een lokale poort (wij gebruiken 8080), alleen bereikbaar vanaf de server zelf.
2. Maak daarop een verstuur-endpoint: een POST met ontvanger, tekst en optioneel een bestandspad, waarna de brug het als WhatsApp-bericht verzendt.
3. Maak een download-endpoint dat media van een eerder bericht ophaalt en ontsleutelt (WhatsApp-media is versleuteld; de sleutel zit bij het bericht en de bibliotheek regelt het ontsleutelen).
4. Laat de berichten-handler uit fase 1 elk binnenkomend bericht óók doorsturen: een POST met chat-ID, afzender, tekst, tijdstip en het mediatype naar een vast webhook-adres op de server — bij ons poort 8769.

Dat webhook-adres is het tussenprogramma uit fase 3. Bestaat het nog niet, dan gaat er alleen een POST de mist in — de brug blijft gewoon draaien.

Fase 3 — het tussenprogramma: van bericht naar antwoord

Dit is het brein van de keten. Een webserver (wij gebruiken FastAPI) met één taak: bericht in, antwoord uit.

1. Maak een webserver met een webhook-endpoint dat de POST van de brug aanneemt.
2. Bouw als allereerste een toegangslijst in: alleen telefoonnummers die jij expliciet toestaat worden verwerkt, de rest wordt genegeerd. Sla deze stap nooit over — iedereen die je nummer heeft kan je assistent anders aan het werk zetten.
3. Haal bij elk bericht de laatste berichten van dat gesprek uit de database van fase 1 — dat is je gespreksgeheugen.
4. Zet geheugen en nieuw bericht om in één opdracht voor het AI-model, met een korte systeeminstructie erboven: wie de assistent is, wat hij wel en niet mag.
5. Roep het AI-model aan — via de API van een aanbieder, of door een AI-commandoregeltool als apart proces te starten (zo doen wij het; het proces krijgt de opdracht en print het antwoord).
6. Stuur het antwoord als POST naar het verstuur-endpoint van de brug uit fase 2.

Daarmee is de cirkel rond: wie op de toegangslijst staat, appt en krijgt antwoord van de AI — met geheugen.

Fase 4 — foto's, documenten en spraak

Berichten zijn zelden alleen tekst. Drie uitbreidingen die het verschil maken:

1. Ziet het tussenprogramma een mediatype in de webhook-payload, laat het dan het bestand ophalen via het download-endpoint van de brug en geef het lokale pad mee aan het AI-model — moderne modellen kunnen afbeeldingen direct bekijken.
2. Is het een spraakbericht, haal het audiobestand op en haal het door een spraak-naar-tekstmodel; de tekst gaat daarna dezelfde route als een gewoon bericht.
3. Bouw een korte wachttijd in (wij gebruiken 2 seconden): stuurt iemand drie foto's achter elkaar, dan wil je die als één opdracht behandelen in plaats van drie keer het model aan te roepen.

Wie audio terugstuurt: let op het formaat. iPhones spelen niet elk audiobestand af — AAC/M4A werkt, ruwe WAV of OGG vaak niet.

Fase 5 — draaiend houden (het echte werk)

Alles hiervoor bouw je in een weekend. Dit is waar de maanden in gaan zitten:

1. Draai brug en tussenprogramma als systemd-services met automatisch herstarten, zodat een crash of server-reboot zichzelf oplost.
2. Vang de twee manieren op waarop de WhatsApp-verbinding stukgaat — ze vragen elk een andere reactie. Ten eerste: de sessie wordt uitgelogd (gebeurt bij ons ongeveer wekelijks); dan moet er opnieuw een QR-code gescand worden. Ten tweede: de bibliotheek is verouderd en WhatsApp weigert de verbinding; dan moet de bibliotheek bijgewerkt en de brug opnieuw gebouwd worden — zonder nieuwe QR.
3. Bouw een watchdog die de keten elke paar minuten controleert en jou wáárschuwt via een ander kanaal dan WhatsApp — als WhatsApp plat ligt, komt een WhatsApp-alarm namelijk nooit aan. Wij mailen.
4. Log elk bericht en elk antwoord met tijdstip, zodat je bij een klacht kunt terugzien wat er gebeurde.
5. Denk na over lange taken: een gebruiker verwacht in seconden antwoord, maar echte klussen duren minuten. Stuur direct een korte bevestiging en laat het werk in een achtergrondproces doorlopen.

Dit onderhoud stopt nooit. Het protocol verandert, sessies verlopen, servers herstarten. Precies dit deel is bij ons het meest herschreven — en precies dit deel schiet er in een druk bedrijf als eerste bij in.

Zo doet Mia het

Alles hierboven — de brug, het geheugen, media, spraak, de watchdogs — draait bij Mia als beheerde dienst onder de naam Mia DM: dezelfde assistent die je apps bouwt, bereikbaar als gewoon chatgesprek op je telefoon en computer. Het draaiend houden is ons werk, niet het jouwe.

Chatten met Mia zit standaard in elk abonnement, binnen je eigen Mia OS in de browser. Mia DM zit er gratis bij — voor wie haar óók buiten het OS om in zijn broekzak wil.