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 (shared across our cluster). Monthly call quotas, chatbot caps, and webhook caps are determined by your plan. Burst 429 responses do not consume your monthly quota; only successful (2xx) and server-error (5xx) calls are billed.

Plan	Monthly Calls	Chatbots	Webhooks	Burst
Free	No API access	—	—	—
Starter	10,000	5	5	60/min
Pro	50,000	15	15	60/min
Business	200,000	25	50	60/min
Enterprise	Custom	Custom	Custom	Custom

Headers on every response

# Per-minute burst (IETF draft headers)
RateLimit-Policy:     60;w=60
RateLimit-Limit:      60
RateLimit-Remaining:  47
RateLimit-Reset:      32          # seconds until window resets

# Monthly quota
X-Quota-Limit:        200000
X-Quota-Remaining:    198650
X-Quota-Reset:        1782864000  # Unix epoch of next month start
X-Quota-Period:       month

429 response

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

{
  "error": "External API rate limit exceeded. Max 60 requests per minute.",
  "code": "RATE_LIMIT_ERROR"
}

Errors

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

200OK — Request succeeded

201Created — Resource created

400Bad Request — Invalid parameters or body

401Unauthorized — Missing or invalid API key

403Forbidden — Plan limit reached or no API access

404Not Found — Resource doesn't exist or doesn't belong to your workspace

409Conflict — Duplicate (e.g. webhook with same chatbot + URL)

413Payload Too Large — Request body exceeded 15 MB

429Too Many Requests — Burst or monthly quota exceeded

500Server Error — Something went wrong

Error Response

# Every error response uses the same envelope.
# A machine-readable "code" is set on specific error classes
# (e.g. RATE_LIMIT_ERROR on 429).

{
  "error": "Invalid API key"
}

{
  "error": "Unknown event(s): user.signup. Valid events: response.created, response.updated, conversation.started, conversation.completed"
}

{
  "error": "External API rate limit exceeded. Max 60 requests per minute.",
  "code": "RATE_LIMIT_ERROR"
}

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",
      "disabled": false,
      "responseCount": 12847,
      "createdAt": "2024-09-01T10:30:00Z",
      "updatedAt": "2024-12-15T14:22: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",
    "disabled": false,
    "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",
      "chatbot": {
        "id": "64f8a2b3c1d4e5f6a7b8c9d0",
        "name": "Support Bot"
      },
      "url": "https://your-server.com/webhook",
      "events": ["response.created", "response.updated"],
      "description": "Production webhook",
      "status": "active",
      "failureCount": 0,
      "lastDeliveryAt": "2024-12-15T10:42:00Z",
      "lastFailureAt": null,
      "createdAt": "2024-12-01T10:00:00Z",
      "updatedAt": "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 -X POST 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",
    "chatbot": { "id": "64f8a2b3c1d4e5f6a7b8c9d0", "name": null },
    "url": "https://your-server.com/webhook",
    "events": ["response.created"],
    "description": "Production webhook",
    "status": "active",
    "failureCount": 0,
    "lastDeliveryAt": null,
    "lastFailureAt": null,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z",
    "secret": "a1b2c3d4e5f6...64_char_hex_string"
  },
  "message": "Save the secret — it won't be shown again."
}

PATCH/external/v1/webhooks/{id}

Update a webhook

Partial update. The signing secret is preserved across updates. Only the fields you include are changed.

Parameters

idpathstringrequired

Webhook ID

Request Body

urlstring

New target URL (https only, no localhost/private IPs)

eventsstring[]

Replacement event list. At least one required.

descriptionstring

Updated description

statusstring

active or paused (failed is machine-set and cannot be requested)

Request

curl -X PATCH https://api-v2.conferbot.com/api/v1/external/v1/webhooks/{id} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

Response 200

{
  "data": {
    "id": "64f8a2b3c1d4e5f6a7b8c9d0",
    "chatbot": { "id": "5fb...", "name": "Support Bot" },
    "url": "https://api.acme.com/conferbot-webhook",
    "events": ["response.created"],
    "description": "Production webhook",
    "status": "paused",
    "failureCount": 0,
    "lastDeliveryAt": null,
    "lastFailureAt": null,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T11:42:00Z"
  }
}

DELETE/external/v1/webhooks/{id}

Delete a webhook

Permanently deletes a webhook and all its delivery logs. Deleting the parent chatbot also cascades and removes all of its webhooks.

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"
}

Account

Read and update the workspace owner's profile, and rotate the account email via OTP. All endpoints accept the same workspace x-api-key as the rest of the External API.

GET/external/v1/account

Get account profile

Returns the workspace owner's name, email, phone, date of birth, address, and IANA timezone.

Request

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

Response 200

{
  "data": {
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "phone": null,
    "dateOfBirth": null,
    "address": null,
    "timezone": "Asia/Dubai"
  }
}

PATCH/external/v1/account

Update account profile

Partial update. Validates phone format (digits/+/spaces/dashes/parens, 6–20 digits), date as ISO-8601, and timezone as a real IANA zone. Strips HTML tags from name/address.

Request Body

namestring

Display name (max 200 chars)

phonestring

Phone in permissive E.164-ish format

dateOfBirthstring

YYYY-MM-DD

addressstring

Mailing address (max 500 chars)

timezonestring

IANA timezone, e.g. America/New_York

Request

curl -X PATCH https://api-v2.conferbot.com/api/v1/external/v1/account \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+971501234567","timezone":"Asia/Dubai"}'

Response 200

{
  "data": {
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "phone": "+971501234567",
    "dateOfBirth": null,
    "address": null,
    "timezone": "Asia/Dubai"
  }
}

POST/external/v1/account/email/request-change

Request email change

Sends a 6-digit OTP to the new email address. The OTP expires in 10 minutes. The old email is notified once the change is confirmed.

Request Body

newEmailstringrequired

The new email address

Request

curl -X POST https://api-v2.conferbot.com/api/v1/external/v1/account/email/request-change \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"newEmail":"[email protected]"}'

Response 200

{
  "data": {
    "success": true,
    "message": "Verification code sent to your new email address"
  }
}

POST/external/v1/account/email/confirm-change

Confirm email change

Verifies the OTP and updates the account email.

Request Body

newEmailstringrequired

Must match the email from the request step

otpstringrequired

6-digit verification code from email

Request

curl -X POST https://api-v2.conferbot.com/api/v1/external/v1/account/email/confirm-change \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"newEmail":"[email protected]","otp":"123456"}'

Response 200

{
  "data": { "success": true }
}

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.