Skip to main content

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

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
}

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​

PlanRequests/MinuteRequests/Day
Starter301,000
Pro6010,000
Business120Unlimited

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​

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid or missing API key
FORBIDDEN403API key doesn't have access
NOT_FOUND404Chatbot not found
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server 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