Documentation

Everything you need to ship

From a one-line embed to full webhook pipelines — integrate OyeChats in minutes, not days.

Quick start

📦Step 1

Install the widget

Add a single script tag to your site and the chat widget appears instantly.

🔑Step 2

Get your bot key

Find your unique bot key in the dashboard under Settings → Widget.

🧠Step 3

Upload your docs

Upload PDFs, paste URLs, or connect a sitemap — the RAG pipeline handles the rest.

⚡Step 4

Configure webhooks

Push lead events, BANT scores, and chat transcripts to your own backend.

Widget Setup

Add the chat widget

Paste the script tag before the closing </body> tag on any HTML page.

HTMLPaste before </body>

<!-- OyeChats Widget -->
<script
  src="https://widget.oyechats.com/loader.js"
  data-bot-key="YOUR_BOT_KEY"
  defer
></script>

Configuration attributes

Attribute	Type	Required	Description
data-bot-key	string	Yes	Your unique bot key from the dashboard.
data-position	"bottom-right" \| "bottom-left"	No	Widget corner position. Default: bottom-right.
data-primary-color	hex string	No	Override the primary brand color (e.g. #2563EB).
data-launcher-label	string	No	Text shown next to the launcher button.
data-auto-open	"true" \| "false"	No	Open the widget automatically on page load.
data-hide-branding	"true" \| "false"	No	Remove "Powered by OyeChats" label (Standard+ plans).

Webhooks

Receive real-time events

Configure a webhook URL in your dashboard and OyeChats will POST a signed JSON payload to your endpoint whenever these events occur.

conversation.started

Fires when a visitor opens and sends their first message.

lead.captured

Fires when a visitor submits name/email via the lead form.

bant.scored

Fires after a conversation is scored for Budget, Authority, Need, Timeline.

operator.requested

Fires when the visitor asks to speak with a human.

conversation.ended

Fires when a chat session is closed by any party.

Example payload — bant.scored

JSON

{
  "event": "bant.scored",
  "timestamp": "2025-04-11T14:23:05Z",
  "conversation_id": "conv_8f3a2b1c",
  "lead": {
    "name": "Sarah Chen",
    "email": "sarah@acme.com"
  },
  "bant": {
    "budget": 82,
    "authority": 91,
    "need": 74,
    "timeline": 68,
    "composite": 79,
    "tier": "hot"
  }
}

All webhook requests include an X-OyeChats-Signature header (HMAC-SHA256). Verify this in your handler before processing.

API Reference

REST API

Base URL: https://api.oyechats.com

Authenticate with your API key in the Authorization: Bearer <key> header.

Method	Endpoint	Description
GET	/v1/conversations	List all conversations with pagination.
GET	/v1/conversations/:id	Get a single conversation with messages.
GET	/v1/leads	List captured leads with BANT scores.
POST	/v1/documents	Upload a document to the RAG knowledge base.
DELETE	/v1/documents/:id	Remove a document from the knowledge base.
GET	/v1/analytics/summary	Get conversation and lead analytics for a date range.

💡

Need a full OpenAPI spec? Contact us — we'll send the YAML directly to your inbox.

Need help integrating?

Our team responds within 2 hours on business days.

Contact support