Skip to main content

Quickstart

This guide takes you from zero to your first authenticated call against the WizChat Management API.

1. Create a Management API key​

Management API keys are personal, scoped, secret keys with the wpk_live_… prefix. You create one from the WizChat dashboard:

  1. Open the WizChat dashboard and go to Settings → API keys.
  2. Click Create Management API key.
  3. Give it a name and select the scopes it needs (for example chatbots:read).
  4. Copy the key — it is shown only once.

Store the key in an environment variable rather than hard-coding it:

export WIZCHAT_API_KEY="wpk_live_xxxxxxxxxxxxxxxxxxxx"
warning

A wpk_live_… key is a secret. Never commit it to source control or expose it in client-side code. Treat it like a password.

2. List your chatbots with curl​

Every request goes to https://www.wizchat.com under the /api/v1 prefix and carries the key as a bearer token:

curl https://www.wizchat.com/api/v1/chatbots \
  -H "Authorization: Bearer $WIZCHAT_API_KEY"

A successful response is a JSON object with a chatbots array — one entry per chatbot you own or created:

{
  "chatbots": [
    {
      "id": "abc123",
      "name": "Support Bot",
      "status": "deployed",
      "deployment": {
        "status": "deployed",
        "deploymentUrl": "https://support-bot.wizchat.app",
        "deployedAt": "2026-06-01T12:00:00Z"
      }
    }
  ]
}

If you get a 401, the key is missing or invalid; a 403 means the key is valid but lacks the chatbots:read scope. See Errors & rate limits.

3. Create a chatbot​

You can create a new chatbot programmatically with POST /api/v1/chatbots. Only name is required; description, dataRegion ("US" or "EU"), requireAuth, and logoUrl are optional:

curl -X POST https://www.wizchat.com/api/v1/chatbots \
  -H "Authorization: Bearer $WIZCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Bot", "dataRegion": "US"}'

The response is a 201 with the new chatbot in status: "draft" and deployment.status: "pending". The first deploy still requires going through the WizChat dashboard (which provisions the underlying infrastructure). Subsequent redeploys can be triggered via POST /api/v1/chatbots/{id}/deploy.

{
  "chatbot": {
    "id": "xyz789",
    "name": "My New Bot",
    "status": "draft",
    "deployment": { "status": "pending" }
  }
}

Required scope: chatbots:write.

4. Use an SDK​

Both SDKs are generated from the same OpenAPI document that powers this reference, so their types always match the deployed API.

TypeScript — @wizchat/management​

npm install @wizchat/management
import { createWizChatClient } from '@wizchat/management';

const wizchat = createWizChatClient({
  apiKey: process.env.WIZCHAT_API_KEY!,
});

const chatbots = await wizchat.listChatbots();
console.log(chatbots.map((c) => c.id));

The SDK unwraps the response envelope, so listChatbots() returns the array of chatbots directly — not the { "chatbots": [...] } object shown in the raw HTTP response above.

Python — wizchat-management​

pip install wizchat-management
import os
from wizchat_management import WizChatClient

with WizChatClient(api_key=os.environ["WIZCHAT_API_KEY"]) as wizchat:
    chatbots = wizchat.list_chatbots()
    print([c.id for c in chatbots])

Next steps​