B Blengi docs

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’.

SignaalGewichtMax
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/init schrijft een visitor_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 — PersistTurnJob voegt 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 RouteLeadJob wordt 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 één RecomputeLeadScoreJob per 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 de chunkById -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.