External API

Integrate WizChat chatbots into your applications using our REST API.

Overview

The External API allows you to:

• Send messages to your chatbot
• Retrieve responses programmatically
• Integrate chatbot functionality into your apps
• Build custom interfaces

Getting API Keys

1. Go to "Settings" > "API"
2. Click "Generate API Key"
3. Copy and securely store the key
4. Note: Keys are shown only once

Authentication

All API requests require authentication:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.wizchat.com/v1/chatbots/YOUR_CHATBOT_ID/query

Base URL

https://api.wizchat.com/v1

Sending a Message

Request

POST /chatbots/{chatbotId}/query
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "message": "What is your return policy?",
  "conversationId": "optional-conversation-id"
}

Request Body Parameters

Field	Type	Required	Description
message	string	Yes	The message to send to the chatbot
conversationId	string	No	Session ID for conversation continuity
images	array	No	Images for multimodal queries (max 5)
scope	string	No	Knowledge scope ID to query a specific namespace (Business/Enterprise only)

Response

{
  "response": "Our return policy allows returns within 30 days of purchase...",
  "conversationId": "conv_abc123",
  "sources": [
    {
      "documentId": "doc_xyz",
      "title": "Return Policy",
      "relevance": 0.95
    }
  ]
}

Conversation Management

Continue a Conversation

Include the conversationId from previous response:

{
  "message": "What if the item is damaged?",
  "conversationId": "conv_abc123"
}

Start New Conversation

Omit conversationId or pass null:

{
  "message": "Hello!",
  "conversationId": null
}

Knowledge Scopes

Business & Enterprise Only

Knowledge scopes are available on Business and Enterprise plans.

If your chatbot has Knowledge Scopes configured, you can target a specific scope by passing the scope parameter. Each scope queries its own dedicated namespace with optional behavior overrides (system prompt, persona, response length).

Discovering Available Scopes

Send a GET request to see which scopes are available:

GET /api/external/chat

The response includes an availableScopes array when scopes are configured:

{
  "name": "External Chat API",
  "version": "1.2.0",
  "enabled": true,
  "availableScopes": [
    { "id": "product-a", "label": "Product A" },
    { "id": "product-b", "label": "Product B" }
  ],
  "documentation": { ... }
}

Querying a Scope

Pass the scope ID in the request body:

{
  "message": "What features does Product A have?",
  "scope": "product-a"
}

The response metadata will include the scope that was used:

{
  "success": true,
  "answer": "Product A includes...",
  "metadata": {
    "model": "gpt-4o",
    "responseTimeMs": 1234,
    "scope": "product-a"
  }
}

Scope Errors

Error Code	HTTP Status	Description
SCOPE_NOT_AVAILABLE	403	Scope requested but plan is not Business or Enterprise
INVALID_SCOPE	400	Scope ID does not exist on this chatbot

Code Examples

JavaScript/Node.js

const response = await fetch(
  'https://api.wizchat.com/v1/chatbots/YOUR_CHATBOT_ID/query',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: 'What are your business hours?',
    }),
  }
);

const data = await response.json();
console.log(data.response);

Python

import requests

response = requests.post(
    'https://api.wizchat.com/v1/chatbots/YOUR_CHATBOT_ID/query',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'message': 'What are your business hours?',
    },
)

data = response.json()
print(data['response'])

cURL

curl -X POST https://api.wizchat.com/v1/chatbots/YOUR_CHATBOT_ID/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your business hours?"}'

Rate Limits

Plan	Requests/Minute	Requests/Day
Starter	30	1,000
Pro	60	10,000
Business	120	Unlimited

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1640000000

Error Handling

Error Response Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "retryAfter": 60
  }
}

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	API key doesn't have access
SCOPE_NOT_AVAILABLE	403	Scope requested but plan is not Business/Enterprise
INVALID_SCOPE	400	Scope ID does not exist on this chatbot
NOT_FOUND	404	Chatbot not found
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error

API Key Management

Viewing Keys

1. Go to "Settings" > "API"
2. See all active keys
3. View usage statistics

Revoking Keys

1. Go to "Settings" > "API"
2. Find the key
3. Click "Revoke"
4. Confirm revocation

warning

Revoked keys stop working immediately.

Best Practices

• Store API keys securely (environment variables)
• Rotate keys periodically
• Use separate keys for different environments
• Implement proper error handling
• Respect rate limits

Related

• API Authentication
• API Reference
• Error Codes