Developer API & SDK

Quick Start

Authentication

All API requests require an API key obtained from your dashboard.

Bearer Token

Pass this header with every API request

HTTP

Authorization: Bearer YOUR_API_KEY

Get your API KeyFree account, no credit card required

Widget Embed

Embed the Chat Widget

Add your chatbot to any website. Choose the method that fits your stack.

REST API

Chat Endpoint

Build custom chat UIs, backend integrations, or mobile apps.

POST

https://vocui.com/api/chat/CHATBOT_ID

bash

curl -X POST "https://vocui.com/api/chat/CHATBOT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"message": "Hello!", "session_id": "unique-session-id"}'

Test from your terminal. Great for quick testing and debugging.

Request Body

Field	Type	Required	Description
`message`	string	Required	The user message to send to the chatbot.
`session_id`	string	Optional	A stable identifier to group messages into a conversation. If omitted, a new session is created.

Replace YOUR_API_KEY with a key from the API Keys page. Keep it server-side or in a protected admin area.

Agent Console

Embed the Agent Console

Embed a live agent console so your team can manage handoff conversations.

HTML

<script
  src="https://vocui.com/agent-console/sdk.js"
  data-chatbot-id="CHATBOT_ID"
  data-api-key="YOUR_API_KEY"
></script>

Full-page console. Add data-position="sidebar" for a fixed sidebar instead.

Replace YOUR_API_KEY with a key from the API Keys page. Keep it server-side or in a protected admin area.

Webhooks

Real-time Event Notifications

Receive real-time HTTP notifications when events happen in your chatbots.

Signature Verification

Each request includes three headers. Compute HMAC-SHA256(timestamp + "." + body, secret) and compare the hex digest against X-Webhook-Signature. Reject requests where the timestamp is more than 5 minutes old.

X-Webhook-Signature

HMAC-SHA256 hex digest

X-Webhook-Timestamp

Unix epoch seconds

X-Webhook-Event

Event name, e.g. lead.captured

Node.js verification example

JavaScript

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const sig = req.headers['x-webhook-signature'];
  const ts  = req.headers['x-webhook-timestamp'];
  const body = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', secret)
    .update(ts + '.' + body)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expected)
  );
  const isRecent = Date.now() / 1000 - Number(ts) < 300;
  return isValid && isRecent;
}

Event Types

Subscribe to specific events or leave empty to receive all events.

generation.startedA generation request was received

generation.completedA generation finished successfully

generation.failedA generation failed

usage.limit_reachedAn account hit a usage limit

usage.threshold_reachedAn account crossed a usage threshold

subscription.createdA subscription was created

subscription.updatedA subscription changed

subscription.canceledA subscription was canceled

api_key.createdA new API key was created

api_key.deletedAn API key was deleted

conversation.startedA new chat session began

conversation.endedA chat session ended

lead.capturedA lead was captured from a conversation

ticket.createdA visitor submitted a support ticket

escalation.createdA visitor escalated or reported an issue

credits.exhaustedAn account reached zero credits

Save your webhook secret

The secret is shown only once when you create a webhook. Store it securely — you will need it to verify signatures on every incoming request.

Manage Webhooks

Build with VocUI