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 four headers. Compute HMAC-SHA256(timestamp + "." + raw_body, secret) over the raw body bytes and compare sha256=<hex digest> against X-VocUI-Signature. Reject requests where the timestamp is more than 5 minutes old, and deduplicate retries on X-VocUI-Delivery-ID.

X-VocUI-Signature

'sha256=' + HMAC-SHA256 hex digest

X-VocUI-Timestamp

Unix epoch seconds

X-VocUI-Event

Event name, e.g. lead.captured

X-VocUI-Delivery-ID

Unique delivery UUID — dedupe key for retries

Node.js verification example

JavaScript

const crypto = require('crypto');

// rawBody must be the exact request body bytes (e.g. express.raw()).
function verifyWebhook(req, rawBody, secret) {
  const sig = req.headers['x-vocui-signature'] || '';
  const ts  = req.headers['x-vocui-timestamp'] || '';

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

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

Event Types

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

conversation.startedA new chat session began

conversation.endedA chat session ended

message.receivedA visitor sent the chatbot a message

message.sentThe chatbot sent a reply

escalation.requestedA visitor asked for a human or reported an issue

handoff.startedA live human handoff began

handoff.resolvedA live human handoff was resolved

knowledge.updatedA knowledge source finished processing

lead.capturedA visitor submitted the pre-chat form

ticket.createdA visitor submitted a support ticket

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