HNBCRM

The CRM where humans and AI agents work together.

HNBCRM (Humans & Bots CRM) is a multi-tenant CRM built for teams that combine human agents and AI bots. Leads, conversations, and handoffs flow seamlessly between people and machines through a shared pipeline, unified inbox, and real-time collaboration tools.

Features

• AI-Human Collaboration — Human team members and AI bots are equal participants with shared context
• AI Copilot — In-app assistant (opt-in per org) that reads and edits the CRM as the logged-in user (their RBAC), with streaming chat, tool use, and two-phase confirmation for destructive actions
• AI WhatsApp Attendant — Virtual attendant that drafts replies to customers (suggest mode with human review by default; autopilot gated behind acceptance metrics), with per-record scoping, LGPD disclosure, deterministic human-handoff keywords and configurable pipeline rules
• Anti-ban Send Queue — Two-level pacing per conversation (Meta pair rate) and per phone number, humanized typing simulation on unofficial channels, official 4^X retry backoff, and automatic channel freeze on quality flags
• Visual Pipeline — Kanban boards with drag-and-drop, customizable stages, and deal aging indicators
• Unified Inbox — Multi-channel conversations with internal notes, reactions, replies/forwarding, emoji picker, full-text message search (including voice transcripts), quick replies (/ shortcuts), scheduled messages with live countdown, labels & archiving with bulk actions
• WhatsApp Channel — Official Cloud API (24h window, templates) or self-hosted gateway (QR pairing), with media, voice notes, delivery/read ticks, typing presence both ways, and a channel health panel
• Voice Transcription — Self-hosted Whisper service transcribes voice notes locally (opt-in per org, no paid API), transcripts are searchable
• Smart Handoffs — Transfer leads between humans and AI with full conversation history
• Contact Enrichment — 20+ fields with social profiles, company data, and custom fields
• REST API — Full CRUD at /api/v1/ with API key authentication and HMAC webhooks
• MCP Server — AI agents connect via Model Context Protocol with 46 tools for full CRM access
• Agent Skills — Open skill package (AgentSkills.io standard) with workflows, data model, and setup guides
• Multi-tenant — Organization-level isolation with role-based access (Admin, Manager, Agent, AI)
• Real-time — Powered by Convex for instant updates across all connected clients
• Task Manager — Projects with customizable kanban columns, colored labels, multiple assignees (human or AI), real subtasks with progress, informational dependencies, early + due-date reminders, @mentions, in-app notification bell, and saved filters
• Calendar — Day/week/month views with drag-to-reschedule and task integration
• @Mentions — Tag team members in internal notes with autocomplete
• File Storage — Message attachments, contact photos, lead documents with quota management
• Embeddable Forms — WYSIWYG form builder with public URLs, CRM field mapping, spam protection, and embed codes

Tech Stack

Quick Start

Prerequisites: Node.js 18+

git clone https://github.com/ericmil87/hnbcrm.git
cd hnbcrm
npm install
npm run dev

Open http://localhost:5173. The app starts with an anonymous sign-in option for quick exploration.

To populate the database with sample data, run the seedMockData mutation from the Convex dashboard or trigger it programmatically.

Development

Project Structure

src/
  components/       UI components (pages, layout, ui primitives)
  pages/            Public pages (DevelopersPage)
  lib/              Utilities (routes, mentions, cn())
convex/
  schema.ts         All table definitions and indexes
  router.ts         REST API endpoints (/api/v1/*)
  leads.ts          Lead CRUD, stage moves, assignment
  calendar.ts       Calendar events (time-ranged) CRUD
  contacts.ts       Contact CRUD with enrichment
  conversations.ts  Multi-channel messaging, labels, message search
  whatsapp.ts       WhatsApp ingress + outbound dispatch (Cloud API / bridge)
  transcription.ts  Voice-note transcription (self-hosted Whisper)
  quickReplies.ts   Quick replies ("/" shortcuts in the composer)
  scheduledMessages.ts  Scheduled message delivery
  handoffs.ts       AI-to-human handoff workflow
  attendant.ts      AI WhatsApp attendant (queue, eligibility, transactional commits)
  copilot.ts        AI copilot tools + threads (SSE streaming in copilotHttp.ts)
  aiSettings.ts     Org AI config: activation + LGPD ack, toggles, models, budget
  lib/llm/          Provider-agnostic LLM layer (OpenAI-compatible, ZDR registry)
  lib/whatsappDispatch.ts  Two-level anti-burst send pacing + humanized typing
  llmsTxt.ts        /llms.txt endpoint content
  seed.ts           Development seed data
mcp-server/         MCP server package (hnbcrm-mcp)
.claude/skills/     Agent Skill (workflows, data model, setup)
public/             Logo assets

API & Integrations

REST API — RESTful endpoints at /api/v1/ authenticated via X-API-Key header. Covers leads, contacts, conversations, handoffs, boards, and team members. See convex/router.ts for the full reference.

MCP Server — The mcp-server/ directory contains an MCP server (hnbcrm-mcp) with 46 tools and 4 resources for AI agent integration. See mcp-server/README.md for setup.

Agent Skills — The .claude/skills/hnbcrm/ directory contains a portable Agent Skill following the AgentSkills.io open standard. Includes workflows, data model reference, API mapping, and platform setup guides. Copy the skill into any compatible agent workspace to get started.

Webhooks — HMAC-SHA256 signed webhook events for lead, conversation, and handoff state changes.

llms.txt — AI-readable documentation at /llms.txt (summary) and /llms-full.txt (full reference) for LLM-powered tools and agents.

Email Setup (Resend)

HNBCRM uses @convex-dev/resend for transactional email delivery. The system sends notifications for team invites, handoff requests, task assignments, lead assignments, overdue reminders, and daily digests.

Domain Configuration

Since the primary domain (hnbcrm.com) uses Gmail for sending/receiving, Resend is configured on a subdomain (mail.hnbcrm.com) to avoid MX/SPF conflicts.

Steps:

1. Resend Dashboard → Domains → Add Domain → mail.hnbcrm.com
2. Cloudflare DNS — Add the records Resend provides:
   • 3x CNAME records for DKIM (e.g., resend._domainkey.mail.hnbcrm.com)
   • 1x TXT record for SPF on mail.hnbcrm.com
   • 1x TXT record for DMARC (if not already on root domain)
3. Verify in Resend dashboard (near-instant with Cloudflare)

Environment Variables

npx convex env set RESEND_API_KEY re_xxxxx
npx convex env set APP_URL https://app.hnbcrm.com.br
npx convex env set RESEND_FROM_EMAIL "HNBCRM <[email protected]>"
npx convex env set RESEND_WEBHOOK_SECRET whsec_xxxxx   # after webhook setup

Webhook Setup

1. In the Resend dashboard, create a webhook pointing to:
   https://<your-convex-deployment>.convex.site/api/v1/webhooks/resend
2. Enable all email.* events
3. Copy the signing secret to RESEND_WEBHOOK_SECRET

Test Mode

By default, @convex-dev/resend runs in test mode — only Resend test addresses receive emails. To enable production sending, update convex/email.ts:

export const resend: Resend = new Resend(components.resend, {
  testMode: false,  // Enable real email delivery
  onEmailEvent: internal.email.handleEmailEvent,
});

Architecture

• Central dispatch: convex/email.ts → internal.email.dispatchNotification
• Templates: convex/emailTemplates.ts (8 PT-BR templates, dark theme)
• Preferences: notificationPreferences table (opt-out model)
• Daily digest: Cron at 08:00 BRT via convex/crons.ts

Deploy

The backend runs on Convex Cloud — no infrastructure to manage. The frontend is a static SPA that can be deployed anywhere.

Vercel (recommended)

1. Import the repo on vercel.com/new

2. Set the environment variable:

   Variable	Value
   VITE_CONVEX_URL	Your Convex deployment URL (e.g. https://your-app.convex.cloud)

3. Deploy — Vercel auto-detects Vite, uses npm run build, outputs from dist/

The included vercel.json handles SPA routing (all paths fallback to index.html).

Convex Production

To deploy Convex functions to production:

npx convex deploy

See Convex Hosting & Deployment for details.

UI Language

The interface is in Portuguese (PT-BR). English localization is planned.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT

Acknowledgments

Built with Convex, Lucide, @dnd-kit, and Sonner.