Je workspace beheren
Leadscoring & traject
Elk gesprek krijgt een leadscore op een schaal van 0 tot 100
op basis van waarneembare signalen: welke pagina’s de bezoeker heeft bekeken, hoe
intensief hij of zij aan de chat heeft deelgenomen en of hij of zij contactgegevens heeft gedeeld.
De score verschijnt als een gekleurd bolletje in de lijst ‘Gesprekken’, de
lijst met leads en in het zijpaneel van elk gesprek —
zodat de verkoopafdeling prioriteit kan geven aan de meest veelbelovende prospects zonder elk
transcript opnieuw te hoeven lezen. Webhook-gebruikers krijgen de score ook mee in de
payload van lead.captured, zodat een CRM veelbelovende leads automatisch naar
een andere wachtrij kan sturen.
Hoe de score wordt berekend
De LeadScoringEngine telt zes gewichten met een maximum bij elkaar op, beperkt het
totaal tot [0, 100] en deelt het resultaat vervolgens in drie
categorieën in. De gewichten zijn gebaseerd op koopintentie, niet
op hoeveel iemand chat: een lang gesprek op zich maakt een
lead nog niet ‘hot’.
| Signaal | Gewicht | Max |
|---|---|---|
| Bezochte pagina’s | +3 per unieke pagina | 15 |
| Aankoop- of contactpagina's — het adres bevat een woord zoals prijzen, winkelwagen, afrekenen, bestel, offerte, contact (Engels), prijzen, offerte, winkelwagen, afrekenen, bestel, afspraak (Nederlands), Preise, Warenkorb, Kasse, Angebot, Termin (Duits) of tarif, panier, commande, devis (Frans), aan het begin van een woord | +10 per overeenkomende pagina | 20 |
| Vraag over kopen of contact in de chat — een bericht van een bezoeker over prijs, bestellen, een offerte, een demo, een afspraak of gecontacteerd worden, in het Engels, Nederlands, Duits of Frans | +10 per bericht | 20 |
| Op een productkaart geklikt | +10 | 10 |
| Op een knop in de chat geklikt | +10 | 10 |
| Berichten van bezoekers (alleen die van de bezoeker, niet die van de assistent) | +2 per bericht | 10 |
| Achtergelaten contactgegevens (e-mailadres aanwezig) | +20 | 20 |
Drempels per categorie: Warm ≥ 70 (groen), Lauw 40–69 (oranje), Koud 0–39 (grijs). Een bezoeker die dertig berichten verstuurt zonder te vragen om iets te kopen, scoort 10 (Koud). Een bezoeker die een product en het winkelmandje bekijkt, naar de prijs vraagt, op de productkaart klikt en zijn e-mailadres achterlaat, scoort 58 (Warm); als hij ook op een knop klikt en vraagt om teruggebeld te worden, 80 (Hot). De redenen achter een score — die je ziet als je met de muis over de pil gaat en in het zijpaneel van het gesprek — verschijnen in de taal van je dashboard.
De scores zijn veranderd toen deze formule werd uitgerold, dus een webhook-gebruiker die
doorverwijst via score_bucket ziet minder uitgebreide gesprekken
met een hoge score. De structuur van de payload is ongewijzigd.
Hoe het up-to-date blijft
De herberekening wordt in de wachtrij geplaatst — nooit op het SSE-hotpath. De
RecomputeLeadScoreJob
wordt vanaf drie plaatsen geactiveerd:
-
Nieuwe paginaweergave
—
/api/v1/widget/initschrijft eenvisitor_page_views-rij telkens wanneer de widget opstart op een nieuwe pagina (herlaadbeurten van dezelfde pagina binnen 2 minuten worden gedupliceerd), en zet vervolgens een herberekening in de wachtrij. -
Nieuwe beurt opgeslagen
—
PersistTurnJobvoegt elke beurt van een assistent en gebruiker toe aan de berichtenlijst en zet een herberekening in de wachtrij voordat het afsluit. - Klik — een klik op een productkaart of chatknop die door de widget wordt gemeld, zet een herberekening in de wachtrij.
-
Lead vastgelegd
— wanneer de bezoeker het
leadformulier verstuurt, voert de controller de herberekening synchroon uit
voordat
RouteLeadJobwordt verzonden, zodat de webhook-payload de actuele score ziet.
Bezoekerstraject
Achter de score zit een browsegeschiedenis per bezoeker. Elke pagina waarop de
widget wordt geplaatst, registreert een rij in visitor_page_views:
id bigserial
workspace_id uuid -- tenancy scope
agent_id uuid
visitor_id uuid
conversation_id uuid -- nullable (set when the page view happens
-- inside an active conversation)
url varchar(500)
title varchar(200) nullable
referrer varchar(500) nullable
viewed_at timestamptz
created_at timestamptz
De conversatiedetailpagina (/app/conversations/{id}
)
toont de laatste 50 paginaweergaven in chronologische volgorde in de rechterkolom
— pagina’s die tijdens
de conversatie zijn bezocht, krijgen een groene
rand, zodat de medewerker tijdens de chat het verschil kan zien tussen browsen tijdens de chat en eerdere
bezoeken.
Webhook-payload
De lead.captured-gebeurtenis bevat nu drie extra
velden:
{
"event": "lead.captured",
"lead": { "id": "01h…", "email": "buyer@example.com", … },
"agent_id": "01h…",
"score": 75,
"score_bucket": "high",
"trajectory": [
{
"url": "https://example.com/pricing",
"title": "Pricing — Plans",
"referrer": "https://google.com",
"viewed_at": "2026-05-18T10:14:02+00:00"
},
…
]
}
Het traject is beperkt tot de 10 meest recente weergaven om
de payloads klein te houden. score_bucket is een van
low, medium, high.
Waarom deze score? (array met redenen)
Bij elke herberekening blijft ook de regel-voor-regel uitsplitsing in
conversations.lead_score_reasons
(JSON) bewaard. Elke rij is een
voor mensen leesbare tekenreeks die de engine heeft gegenereerd op weg naar het totaal —
bijv.
"3 unieke pagina’s bezocht (+15)"
,
"2 intentiepagina’s bezocht (prijzen, demo) (+30)"
,
"5 berichten verzonden/ontvangen (+10)"
,
"Contactgegevens vastgelegd (+15)"
. Op de pagina met gespreksdetails
wordt de lijst weergegeven onder het gedeelte ‘Leadscore’, zodat de medewerker
precies weet welke signalen zijn geactiveerd; de badge zelf toont dezelfde regels
in de tooltip als je er met de muis overheen gaat. Als een signaal 0 bijdraagt, wordt het weggelaten —
een koude lead zonder intentie-overeenkomsten bevat simpelweg minder items.
Bestaande gesprekken bijwerken
De scorekolom staat standaard op 0 voor elk gesprek dat al bestond voordat deze functie werd gelanceerd. Om de geschiedenis in één keer opnieuw te berekenen, voer je het volgende uit:
php artisan pitchbar:recompute-lead-scores
Handige vlaggen:
-
--workspace={uuid}— beperk tot één werkruimte -
--agent={uuid}— beperk tot één agent (heeft voorrang op--workspace) -
--queue— stuur éénRecomputeLeadScoreJobper gesprek in plaats van het inline uit te voeren. Gebruik dit voor hele grote werkruimten (miljoenen gesprekken) waar de analytics-worker het werk op de achtergrond moet verwerken. -
--chunk=500— batchgrootte per rij voor dechunkById-iterator (standaard 500). Verlaag dit naar 100 op hosts met weinig geheugen.
Het commando is idempotent: als je het opnieuw uitvoert, worden de score en redenen gewoon overschreven met de meest recente waarden. Gesprekken in de Playground worden altijd overgeslagen.
Gesprekken met een score van nul
Een gloednieuw gesprek zonder paginaweergave, zonder berichten en zonder
vastgelegde contactgegevens scoort 0 en komt in de
Cold-bucket terecht. De UI verbergt de badge helemaal als de score 0 is —
zo voorkom je een rij grijze "Cold · 0"-pillen bij elke keer dat de widget
wordt geladen, terwijl er nooit een actie is geactiveerd. Gesprekken krijgen pas
een badge nadat het eerste scoresignaal is afgegaan (meestal een paginaweergave
via /init op een niet-lege pagina-URL).
De lijst met leads filteren
Leads
(/app/leads
) hebben een schakelaar Alleen Hot
in de werkbalk — als die aan staat, wordt de lijst beperkt
tot leads waarvan het onderliggende gesprek een score van ≥ 70 heeft. De schakelaar is
als bladwijzer opslaan: de URL wordt ?hot=1
en blijft behouden bij het verversen.
De leads van een AI-medewerker zijn dezelfde lijst, maar dan voor hem gefilterd
(/app/leads?agent={id}&hot=1
); het oude
/app/agents/{id}/leads
-adres stuurt je daarheen door.
Afstemmen
De gewichten staan in
app/Services/Scoring/LeadScoringEngine.php
. Voeg een nieuw
signaal toe door een privé-scoreFoo()
-methode te schrijven die
['score' => int, 'reasons' => string[]]
retourneert
en deze toe te voegen aan de compute()
-array met onderdelen. Houd de
som van de caps redelijk — het totaal blijft hoe dan ook op 100, maar
als je één signaal te zwaar laat wegen, worden de grenzen van de buckets
zinloos.
Om de lijst met intent-trefwoorden uit te breiden, bewerk je
LeadScoringEngine::INTENT_KEYWORDS
. Er wordt alleen gezocht naar
substrings in de URL, waarbij hoofdletters en kleine letters niet uitmaken — het toevoegen van een trefwoord leidt niet
tot een herberekening van historische gesprekken totdat de volgende herberekening wordt geactiveerd
(d.w.z. de volgende paginaweergave, het volgende bericht of het vastleggen van een lead in dat
gesprek). Gebruik php artisan pitchbar:recompute-lead-scores
om een bulkherberekening voor bestaande rijen te forceren.
De engine beperkt de geschiedenis van paginaweergaven tot de meest recente
200
rijen per bezoeker
(LeadScoringEngine::MAX_PAGE_VIEWS
). Daarboven
raken de wegingen toch verzadigd, en de limiet houdt de query efficiënt voor
terugkerende bezoekers die lang blijven.