CRM Integration

The CRM works in three ways, all automatic:

The phone number is always pinned from the phone network, never from what the caller says. New contacts are tagged voice-caller automatically.

CRM is enabled by default when the RelationshipHub tools are installed. To explicitly control it, set features.crmCapture in your config.json:

// config.json
{
  "features": {
    "crmCapture": true   // or false to disable
  }
}

This single flag controls both the read path (caller lookup) and the write path (auto-extraction and transcript logging). When off, no CRM subprocess runs and no caller data is read or written.

You can also set the environment variable NINJA_TALK_CRM_CAPTURE=false in your .env file for the same effect.

The moment a call arrives, before the agent even picks up, here is what happens:

1. The phone network delivers the caller's phone number (network-verified, not spoofable by the caller)
2. The gateway fires a CRM search with a bounded 5-second deadline
3. If a match is found, the contact profile (name, company, notes, recent interactions) is formatted into a compact text block
4. That block is injected into the voice model session's system instruction before the greeting
5. The agent speaks a personalized greeting: "Hey Sarah, good to hear from you again"

Cache hits resolve in under 1ms. Warm lookups take around 50ms. Even in the worst case, the 5-second deadline ensures the call always proceeds - if the lookup is slow, the agent greets without context and the profile is cached for next time.

If no match is found, the agent uses a neutral greeting from your playbook and waits for the caller to identify themselves.

You don't need to ask callers to spell out their details. The gateway listens to the natural conversation and extracts identity information server-side:

• Name - "This is Michael", "My name is Sarah Chen"
• Company - "I'm calling from Acme Corp", "over at Riverside Dental"
• Email - "You can reach me at mike@acme.com"

Extraction is debounced - the gateway waits for a natural pause in the conversation before running extraction, so rapid-fire introductions get batched into a single save. Corrections are handled automatically: if a caller says "Actually, call me Mike" later in the call, the record updates.

All inputs are sanitized (HTML/code stripped, Unicode-safe name validation, field length limits enforced) before writing to the CRM. The phone number is always the network-verified one from the phone network, never something the caller dictates.

Contacts are stored in the OpenClaw RelationshipHub CRM on your server. You can browse and search contacts through:

• Chat commands - Ask your bot "Show me the contact for 555-1234" or "Who called yesterday?"
• CRM search tool - The RelationshipHub skill provides full-text search across names, companies, and notes
• Direct file access - Contact records are stored as structured data in your OpenClaw workspace under tools/relationship-hub/

Each contact record includes: name, phone, company, email, tags, interaction history (with timestamps and call summaries), and any custom notes your agent has saved.

When placing outbound calls via the API, the CRM lookup is skipped - you already know who you're calling. Instead, context is provided through task facts:

// Outbound call API request
{
  "to": "+15551234567",
  "purpose": "Follow up on proposal",
  "targetName": "Sarah Chen",
  "facts": [
    "Sarah is the CTO at Acme Corp",
    "She requested a callback about pricing",
    "Last spoke 3 days ago about the enterprise plan"
  ]
}

The targetName and facts fields inject directly into the agent's context, giving it full awareness of who it's calling and why. The agent opens with purpose: "Hi Sarah, I'm calling back about the pricing question you had on the enterprise plan."

After the outbound call ends, the transcript is still logged to the CRM under that contact's record (if a matching contact exists), so the history stays complete.