API Reference

The Conferbot API is organized around REST. Our API accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and authentication.

Getting started guide

Base URL

https://api-v2.conferbot.com/api/v1

Client Libraries

The API docs use curl examples. See SDKs & Code Examples for Node.js and Python wrappers.

Authentication

The Conferbot API uses API keys to authenticate requests. You can generate and manage API keys from your workspace settings.

Include your API key in the x-api-key header with every request. Do not share your API key or expose it in client-side code.

Keep your API key secret. Do not embed it in frontend code, public repositories, or client-side applications.

Authenticated Request

curl

curl https://api-v2.conferbot.com/api/v1/external/v1/chatbots \
  -H "x-api-key: YOUR_API_KEY"

Your API Key

Generate an API key from Dashboard → Workspace → API Keys

Base URL

All API requests should be made to the base URL below. All endpoints in this documentation are relative to this base.

https://api-v2.conferbot.com/api/v1

Rate Limits

The API is rate limited to 60 requests per minute per API key. Monthly call limits are determined by your plan.

Plan	Monthly Calls	Rate
Starter	10,000	60/min
Pro	50,000	60/min
Business	200,000	60/min
Enterprise	Custom	Custom

Rate Limit Headers

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Rate limit exceeded",
  "message": "You exceeded 60 requests in 1 minute."
}

Errors

The API uses conventional HTTP response codes to indicate success or failure.

200OK — Request succeeded

201Created — Resource created

400Bad Request — Invalid parameters

401Unauthorized — Missing or invalid API key

403Forbidden — Plan doesn't include API access

404Not Found — Resource doesn't exist

429Too Many Requests — Rate limit exceeded

500Server Error — Something went wrong

Error Response

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Chatbots

Manage chatbots in your workspace — list, create, update, duplicate, and delete.

GET/external/v1/chatbots

List chatbots

Returns all chatbots in the workspace associated with the API key.

Request

curl https://api-v2.conferbot.com/api/v1/external/v1/chatbots \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": "64f8a2b3c1d4e5f6a7b8c9d0",
      "name": "Customer Support Bot",
      "status": "active",
      "responseCount": 12847,
      "createdAt": "2024-09-01T10:30:00Z"
    }
  ]
}

GET/external/v1/chatbots/{id}

Get a chatbot

Returns detailed information for a single chatbot.

Parameters

idpathstringrequired

Chatbot ID

Request

curl https://api-v2.conferbot.com/api/v1/external/v1/chatbots/64f8a2b3c1d4e5f6a7b8c9d0 \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "data": {
    "id": "64f8a2b3c1d4e5f6a7b8c9d0",
    "name": "Customer Support Bot",
    "status": "active",
    "description": "Handles customer inquiries 24/7",
    "responseCount": 12847,
    "createdAt": "2024-09-01T10:30:00Z",
    "updatedAt": "2024-12-15T14:22:00Z"
  }
}

POST/external/v1/chatbots

Create a chatbot

Creates a new chatbot in the workspace. Subject to plan chatbot limits.

Request Body

namestringrequired

Chatbot name (max 100 characters)

descriptionstring

Optional chatbot description

Request

curl -X POST https://api-v2.conferbot.com/api/v1/external/v1/chatbots \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lead Gen Bot", "description": "Captures visitor leads"}'

Response 201

{
  "data": {
    "id": "64f8a2b3c1d4e5f6a7b8c9d0",
    "name": "Lead Gen Bot",
    "description": "Captures visitor leads",
    "createdAt": "2024-12-15T14:22:00Z"
  }
}

PUT/external/v1/chatbots/{id}

Update a chatbot

Updates a chatbot's name, description, or disabled status. Only provided fields are changed.

Parameters

idpathstringrequired

Chatbot ID

Request Body

namestring

New name (max 100 characters)

descriptionstring

New description

disabledboolean

Set true to disable the chatbot

Request

curl -X PUT https://api-v2.conferbot.com/api/v1/external/v1/chatbots/{id} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Bot Name", "disabled": false}'

Response 200

{
  "data": {
    "id": "64f8a2b3c1d4e5f6a7b8c9d0",
    "name": "Updated Bot Name",
    "description": "Captures visitor leads",
    "disabled": false,
    "updatedAt": "2024-12-16T10:00:00Z"
  }
}

DELETE/external/v1/chatbots/{id}

Delete a chatbot

Permanently deletes a chatbot and removes it from the workspace. This action cannot be undone.

Parameters

idpathstringrequired

Chatbot ID

Request

curl -X DELETE https://api-v2.conferbot.com/api/v1/external/v1/chatbots/{id} \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "message": "Chatbot deleted"
}

POST/external/v1/chatbots/{id}/duplicate

Duplicate a chatbot

Creates a copy of a chatbot with all its configuration. The copy is named with a " (copy)" suffix. Subject to plan chatbot limits.

Parameters

idpathstringrequired

Chatbot ID to duplicate

Request

curl -X POST https://api-v2.conferbot.com/api/v1/external/v1/chatbots/{id}/duplicate \
  -H "x-api-key: YOUR_API_KEY"

Response 201

{
  "data": {
    "id": "65b2c3d4e5f6a7b8c9d0e1f2",
    "name": "Lead Gen Bot (copy)",
    "description": "Captures visitor leads",
    "createdAt": "2024-12-15T14:30:00Z"
  }
}

Responses

Access chatbot conversation responses and visitor data.

GET/external/v1/chatbots/{id}/responses

List responses

Returns paginated responses for a chatbot with optional date filtering.

Parameters

idpathstringrequired

Chatbot ID

pagequeryinteger

Page number (default: 1)

limitqueryinteger

Items per page (default: 20, max: 100)

startDatequerystring

Filter from date (YYYY-MM-DD)

endDatequerystring

Filter to date (YYYY-MM-DD)

Request

curl https://api-v2.conferbot.com/api/v1/external/v1/chatbots/{id}/responses?page=1&limit=20 \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "chatSessionId": "sess_abc123",
      "visitorId": "visitor_xyz789",
      "chatDate": "2024-12-15T09:30:00Z",
      "record": [...],
      "answerVariables": { "email": "[email protected]" }
    }
  ],
  "total": 1284,
  "page": 1,
  "totalPages": 65
}

GET/external/v1/chatbots/{id}/responses/{responseId}

Get a response

Returns a single response with full conversation data.

Parameters

idpathstringrequired

Chatbot ID

responseIdpathstringrequired

Response ID

Request

curl https://api-v2.conferbot.com/api/v1/external/v1/chatbots/{id}/responses/{responseId} \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "data": {
    "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
    "chatSessionId": "sess_abc123",
    "visitorId": "visitor_xyz789",
    "record": [
      { "type": "bot", "message": "Hello! How can I help?" },
      { "type": "user", "message": "I need help with billing" }
    ],
    "answerVariables": {
      "email": "[email protected]",
      "name": "John"
    }
  }
}

Analytics

Get engagement metrics and trends for your chatbots.

GET/external/v1/chatbots/{id}/analytics

Get chatbot analytics

Returns total response count and daily breakdowns for a given period.

Parameters

idpathstringrequired

Chatbot ID

daysqueryinteger

Period in days (default: 30)

Request

curl https://api-v2.conferbot.com/api/v1/external/v1/chatbots/{id}/analytics?days=30 \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "data": {
    "totalResponses": 12847,
    "recentResponses": 432,
    "period": "30d",
    "dailyCounts": [
      { "date": "2024-12-01", "count": 15 },
      { "date": "2024-12-02", "count": 22 },
      { "date": "2024-12-03", "count": 18 }
    ]
  }
}

Webhooks

Manage webhook subscriptions via the API. For event payloads and signature verification, see the Webhooks Guide.

GET/external/v1/webhooks

List webhooks

Returns all webhook subscriptions for the workspace.

Request

curl https://api-v2.conferbot.com/api/v1/external/v1/webhooks \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "_id": "65b2c3d4e5f6a7b8c9d0e1f2",
      "url": "https://your-server.com/webhook",
      "events": ["response.created", "response.updated"],
      "status": "active",
      "chatbot": {
        "_id": "64f8a2b3...",
        "name": "Support Bot"
      },
      "createdAt": "2024-12-01T10:00:00Z"
    }
  ]
}

POST/external/v1/webhooks

Create a webhook

Creates a new webhook subscription. Returns the webhook with a signing secret (shown only once).

Request Body

chatbotIdstringrequired

Chatbot to subscribe to

urlstringrequired

Endpoint URL for webhook POSTs

eventsstring[]required

Event types to subscribe to

descriptionstring

Optional description

Request

curl https://api-v2.conferbot.com/api/v1/external/v1/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotId": "64f8a2b3c1d4e5f6a7b8c9d0",
    "url": "https://your-server.com/webhook",
    "events": ["response.created"],
    "description": "Production webhook"
  }'

Response 201

{
  "data": {
    "_id": "65b2c3d4e5f6a7b8c9d0e1f2",
    "url": "https://your-server.com/webhook",
    "events": ["response.created"],
    "status": "active",
    "secret": "a1b2c3d4e5f6...64_char_hex_string",
    "description": "Production webhook"
  },
  "message": "Save the secret — it won't be shown again."
}

DELETE/external/v1/webhooks/{id}

Delete a webhook

Permanently deletes a webhook and all its delivery logs.

Parameters

idpathstringrequired

Webhook ID

Request

curl -X DELETE https://api-v2.conferbot.com/api/v1/external/v1/webhooks/{id} \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "message": "Webhook deleted"
}

Usage

Monitor your API consumption and plan limits.

GET/external/v1/usage

Get API usage

Returns current month's API call count, plan limit, and remaining quota.

Request

curl https://api-v2.conferbot.com/api/v1/external/v1/usage \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "data": {
    "month": "2025-01",
    "plan": "Starter",
    "used": 1423,
    "limit": 10000,
    "remaining": 8577
  }
}

Need help? Check the Getting Started guide or try the API Playground.