CRM Integration

Overview

The CRM Integration API lets you connect Next Cap directly to your existing CRM — Salesforce, HubSpot, Zendesk, or any custom system. With a single API key, you get access to both live chat (real-time WebSocket) and ticketing (REST API), enabling full bidirectional communication from your own dashboard.

How It Works

Unlike the read-only External Data API, the CRM Integration API provides per-user authentication. Every API key is tied to a seat in your organization and inherits that seat's exact permissions and widget assignments. This means:

• Every CRM key occupies a paid seat in your organization
• Each key inherits the seat's permissions (e.g., live-chat:join, tickets:manage)
• Each key only sees data from widgets the seat is assigned to
• If the seat has live-chat permissions, the key can access live chat — if it has ticketing permissions, it can access tickets — one key, both features
• If a seat is removed or deactivated, its CRM key stops working immediately

Authentication

CRM keys use the branded nextcap_ck_ prefix. The same key works for both REST and WebSocket:

X-Api-Key: nextcap_ck_YOUR_KEY

# or

Authorization: Bearer nextcap_ck_YOUR_KEY

const socket = io("wss://api.nextcap.ai/crm-chat", {
  auth: { apiKey: "nextcap_ck_YOUR_KEY" },
  transports: ["websocket"],
});

Obtaining CRM Keys

There are two ways to create a CRM key, depending on your use case:

The live chat integration uses WebSocket (Socket.IO) for real-time bidirectional communication. Connect your CRM to receive messages, typing indicators, and conversation events the moment they happen — and reply to visitors instantly.

WebSocket Connection

Connect to the /crm-chat namespace with your CRM API key:

wss://api.nextcap.ai/crm-chat

Quick Start — Live Chat

import { io } from "socket.io-client";

const CRM_KEY = "nextcap_ck_YOUR_KEY";

// Connect to the CRM chat WebSocket
const socket = io("wss://api.nextcap.ai/crm-chat", {
  auth: { apiKey: CRM_KEY },
  transports: ["websocket"],
});

socket.on("connect", () => {
  console.log("Connected to live chat");
});

// Join a conversation room
socket.emit("crm:join", { conversationId: "CONV_ID" }, (res) => {
  console.log("Joined:", res);
});

// Listen for new messages
socket.on("message:new", (msg) => {
  console.log(`[${msg.role}] ${msg.content}`);
});

// Send a message as the agent
socket.emit("crm:message", {
  conversationId: "CONV_ID",
  content: "Hi, how can I help you?",
});

// Listen for typing indicators
socket.on("typing", (data) => {
  console.log(`${data.role} is typing...`);
});

// Listen for conversation lifecycle events
socket.on("agent:assigned", (data) => {
  console.log("Agent assigned:", data.agentUserId);
});
socket.on("conversation:resolved", (data) => {
  console.log("Conversation resolved:", data.conversationId);
});

Client → Server Events

Events your CRM sends to Next Cap:

socket.emit("crm:join", { conversationId: "CONV_ID" }, (res) => {
  if (res.success) console.log("Joined conversation");
});

socket.emit("crm:message", {
  conversationId: "CONV_ID",
  content: "Hi, how can I help you today?",
}, (res) => {
  if (res.success) console.log("Sent:", res.messageId);
});

Server → Client Events

Events your CRM receives from Next Cap for conversations you've joined:

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "role": "user",
  "content": "I need help with my order",
  "visitorId": "visitor_456",
  "createdAt": "2026-04-07T14:30:00.000Z",
  "attachments": null
}

Conversation REST Endpoints

Use these REST endpoints alongside the WebSocket for initial data loading, listing conversations, and managing the handoff queue:

# List live chat conversations
curl -H "X-Api-Key: nextcap_ck_YOUR_KEY" \
  "https://api.nextcap.ai/api/v1/external/crm/conversations?status=handed_off&per_page=20"

# Get a conversation with messages
curl -H "X-Api-Key: nextcap_ck_YOUR_KEY" \
  "https://api.nextcap.ai/api/v1/external/crm/conversations/CONV_ID"

# Get the handoff queue
curl -H "X-Api-Key: nextcap_ck_YOUR_KEY" \
  "https://api.nextcap.ai/api/v1/external/crm/conversations/queue"

# Assign an agent to a conversation
curl -X POST -H "X-Api-Key: nextcap_ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "USER_UUID"}' \
  "https://api.nextcap.ai/api/v1/external/crm/conversations/CONV_ID/assign"

# Resolve a conversation
curl -X POST -H "X-Api-Key: nextcap_ck_YOUR_KEY" \
  "https://api.nextcap.ai/api/v1/external/crm/conversations/CONV_ID/resolve"

Typical Integration Flow

For ticketing, the recommended approach is webhooks + REST API. Webhooks push events to your server the moment something happens (ticket created, status changed, reply received), so your CRM stays in sync without polling. Then use the REST API to take action — reply, assign, close, or update tickets.

Quick Start — Ticketing

# List tickets visible to your CRM user
curl -H "X-Api-Key: nextcap_ck_YOUR_KEY" \
  "https://api.nextcap.ai/api/v1/external/crm/tickets?status=open&per_page=20"

# Reply to a ticket
curl -X POST -H "X-Api-Key: nextcap_ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "We are looking into this issue."}' \
  "https://api.nextcap.ai/api/v1/external/crm/tickets/TICKET_ID/reply"

Ticket Endpoints

Ticket Actions

Attachments

Two flows are available depending on your needs. Direct upload is simplest — stream the file to our API in one request. Presigned PUT is useful when you want the file to go straight to storage without passing through our server. After either flow you get an attachment_id, which you then pass as attachment_ids[] on ticket create / reply / customer-reply.

Webhook Events

Use these webhook events to keep your CRM in sync with Next Cap. Register webhooks via the POST /external/webhooks endpoint.

Ticket Status Transitions

Ticket status follows a strict state machine. Invalid transitions return 400 Bad Request.

new → open, in_progress, closed
open → in_progress, waiting_customer, waiting_internal, resolved, closed
in_progress → waiting_customer, waiting_internal, resolved, closed
waiting_customer → open, in_progress, resolved, closed
waiting_internal → open, in_progress, resolved, closed
resolved → closed, reopened
closed → reopened
reopened → open, in_progress, waiting_customer, waiting_internal, resolved, closed

Permissions Reference

The CRM key inherits the user's role permissions. Here's what each feature requires: