ChatForge REST API v1

Programmatically manage agents, conversations, leads, and analytics. Enterprise plan required.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer cf_your_api_key_here

Generate your API key in the Dashboard → Integrations tab.

Base URL

https://chatforge.aiedge247.com/api/dashboard.js?action=v1-{resource}

All API endpoints use query parameters. Agent-specific endpoints require &agent_id=UUID.

Endpoints

List Agents

{
  "agents": [
    {
      "id": "uuid",
      "name": "Support Agent",
      "welcome_message": "Hi! How can I help?",
      "active": true,
      "primary_color": "#6366f1",
      "created_at": "2026-03-25T10:00:00Z"
    }
  ]
}

Create Agent

// Request body
{
  "name": "Sales Agent",
  "welcome_message": "Hi! Looking to learn more?",
  "system_prompt": "You are a helpful sales assistant.",
  "knowledge_base": "Our pricing starts at $99...",
  "primary_color": "#10b981"
}

// Response
{
  "agent": { "id": "uuid", "name": "Sales Agent", "active": true }
}

Get Agent

Update Agent

// Request body
{
  "name": "Updated Name",
  "active": false,
  "system_prompt": "New system prompt..."
}

Delete Agent

List Conversations

{
  "conversations": [
    {
      "id": "uuid",
      "visitor_email": "john@example.com",
      "visitor_name": "John",
      "lead_captured": true,
      "message_count": 8,
      "page_url": "https://example.com/pricing",
      "created_at": "2026-03-25T14:30:00Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

List Leads

{
  "leads": [
    {
      "id": "uuid",
      "visitor_name": "John Smith",
      "visitor_email": "john@example.com",
      "visitor_phone": "480-555-1234",
      "conversation_summary": "Asked about estate planning...",
      "source_page_url": "https://example.com/services",
      "created_at": "2026-03-25T14:32:00Z"
    }
  ]
}

Get Analytics

{
  "month": "2026-03",
  "conversations": { "total": 245, "this_month": 82 },
  "leads": { "total": 31, "this_month": 12 },
  "messages_this_month": 410
}

Inject Message (Human Takeover)

// Request body
{
  "conversation_id": "uuid",
  "content": "Hi, this is Cal jumping in. How can I help?"
}

// Response
{
  "message": {
    "id": "uuid",
    "role": "assistant",
    "content": "Hi, this is Cal jumping in. How can I help?",
    "created_at": "2026-03-25T14:35:00Z"
  }
}

Webhooks

ChatForge fires webhooks on agent events. Configure them in the Dashboard → Integrations tab.

Events

• conversation.started — visitor sends first message
• conversation.ended — 30 min inactivity
• lead.captured — visitor shares contact info
• message.received — every visitor message
• upgrade.prompted — agent hits message limit

Webhook Payload

{
  "event": "lead.captured",
  "agent_id": "abc123",
  "timestamp": "2026-03-25T10:30:00Z",
  "data": {
    "visitor_name": "John Smith",
    "visitor_email": "john@example.com",
    "visitor_phone": "480-555-1234",
    "conversation_summary": "Asked about estate planning services",
    "page_url": "https://example.com/services"
  }
}

Signature Verification

Every webhook includes an X-ChatForge-Signature header containing an HMAC-SHA256 hex digest of the JSON payload, signed with your webhook secret.

// Node.js verification example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return signature === expected;
}

Error Codes

400 — Bad request (missing required fields)
401 — Invalid or missing API key
403 — Insufficient plan (Enterprise required)
404 — Resource not found
429 — Rate limit exceeded
500 — Internal server error