Chatbot ↔ CRM Integration

Every wrrk chatbot is wired to the CRM in both directions. When a visitor chats with your bot, the bot recognizes returning contacts, personalizes its replies, and pushes captured leads back into the CRM, without anyone touching a button.

What Happens When a Visitor Sends a Message

Visitor lookup: Before the AI generates a reply, the bot looks up the visitor in the CRM by their persistent visitorId cookie, the email they shared earlier, or the phone number.
Context injection: If a matching CRM contact is found, the bot's system prompt is enriched with a VISITOR CRM CONTEXT block: name, company, role, lifecycle (subscriber / lead / MQL / SQL / customer), score, deal history, total revenue, last activity, tags.
Persona shift: The AI is instructed to treat the visitor differently depending on lifecycle:

Customers → warm, support-first, references their history.
MQL/SQL leads → picks up where qualification left off, doesn't restart.
Returning subscribers → doesn't re-ask for name/email.
Anonymous visitors → standard greet + qualification flow.

Lead detection: As the visitor types, a lightweight regex pulls out email, phone, and name when they're shared.
CRM sync (fire-and-forget): The bot calls the CRM sync service to create or update the contact. The conversation is logged as a chatbot activity on the contact's timeline.
Prospect upgrade: If Create Prospect on Capture is enabled and the visitor is brand-new, the contact is upgraded to status = prospect, lifecycle = mql, and tagged chatbot-captured.

What Happens When the Bot Hands Off to a Human

When the bot escalates a conversation (visitor frustration, explicit "speak to a human", or a rule trigger):

A chatbot ticket is created in the chatbot module.
A linked CRM ticket is created in the same step.
Both tickets share the conversationId so the CRM ticket has the full transcript inline.
The CRM contact's lifecycle and activity log are updated to reflect the handoff.

Where to See the Integration

In the chatbot inbox: Open any conversation. Above the AI Copilot panel on the right, you'll see the visitor's CRM card with their lifecycle, score, company, deal count, and last activity. Click View in CRM to jump to the full contact record. If the visitor isn't on file yet, you'll see a quiet "Anonymous visitor, not in CRM yet" hint instead.

In the CRM contact view: Open any contact. The Conversations tab has a Chatbot filter chip that surfaces every chat the contact has had with your bots, plus a deep link back to the bot's inbox. The Timeline has a chatbot activity type alongside email, call, meeting, and WhatsApp.

Settings (per bot)

Navigate to Chatbots > [Your Bot] > Settings > Actions to control:

CRM Integration card:

Auto-create Contact: Sync a CRM contact when a new conversation starts.
Create Ticket on Handoff: Open a CRM ticket the moment the bot transfers to an agent.
Update Contact on Email: Refresh the CRM record when the visitor shares an email.
Create Prospect on Capture: When a brand-new lead shares an email, upgrade the contact to prospect (lifecycle = MQL) and tag chatbot-captured. Off by default; turn it on when you want marketing to inherit chatbot-captured leads as warm prospects rather than cold subscribers.
Store Conversation Notes: (Coming soon) Save a conversation summary to the CRM record on resolve.

Lead Capture card:

When to collect: Off, Optional, Required, or After 1st reply.
Off, Bot never asks for contact info.
Optional, Bot looks for natural moments to ask. Doesn't block the conversation if declined.
Required, Bot collects info before giving substantive help. Use this for sales bots.
After 1st reply, Bot answers the first question, then asks. Good middle ground.
Fields to capture: name, email, phone, company, role, pain points (pick any).
Custom prompt: Override the default "Could I get your name and email?" with your own wording.

Disabling the master CRM Integration toggle stops the bot from creating or updating CRM contacts entirely. Use this only if you want a fully ephemeral support bot with no CRM trace.

Recommended Setups

Support bot (existing customers): Auto-create Contact ON, Create Ticket on Handoff ON, Update on Email ON, Create Prospect on Capture OFF, Lead Capture Optional. The bot will recognize returning customers, won't ask qualifying questions, and will create a ticket only when it needs a human.

Sales bot (lead gen on marketing site): All CRM toggles ON including Create Prospect on Capture, Lead Capture Required, fields = name + email + company + role. Every new email becomes a prospect ready for outreach.

Mixed bot (FAQ + lead capture): All CRM toggles ON, Lead Capture After 1st reply. The bot demonstrates value first, then asks for contact info.

Data Flow Summary

Visitor message
    ↓
Lambda fetches: bot config + org profile + conversation history + knowledge + CRM context  ← parallel
    ↓
System prompt built (with VISITOR CRM CONTEXT block if visitor is on file)
    ↓
Claude generates reply with full context
    ↓
Lead fields detected in visitor's message? → syncContactToCRM (creates/updates contact + logs activity)
    ↓
New lead with email + createProspectOnCapture enabled? → upgrade to status=prospect, lifecycle=mql

The CRM lookup and the lead sync run in parallel with the rest of the message pipeline, so they don't add latency to the visitor's reply.

Troubleshooting

Visitor isn't showing as a known CRM contact even though I have their email on file: The bot looks up by visitorId first, then email, then phone. If the visitor cleared their cookies and is on a new device with no email shared yet, the bot can't match them. Once they share an email, the lookup succeeds and subsequent messages will personalize.

My contact didn't get upgraded to a prospect: Check three things: (1) Auto-create Contact is ON, (2) Create Prospect on Capture is ON, (3) the visitor shared a valid email. The upgrade only fires for brand-new contacts, existing contacts keep their current lifecycle.

The chatbot tab in the CRM contact's Conversations panel is empty: Conversations are linked to contacts by email. If the bot captured the email mid-conversation, only messages after that point are linked. We're working on backfilling older messages once the email lands.