Widget API Documentation

Everything you need to integrate the NexonTech chat widget into your application.

Overview

The Widget API lets you initialize chat conversations and exchange messages with your AI agent programmatically. All endpoints accept and return JSON. CORS is fully open, so you can call these endpoints from any domain.

Base URL: https://nexontech.org/api/widget

Quick Start

Get a conversation running in two API calls:

1. Initialize a conversation

POST /api/widget/init
Content-Type: application/json

{
  "key": "wk_your_widget_key"
}

2. Send a message

POST /api/widget/chat
Content-Type: application/json

{
  "key": "wk_your_widget_key",
  "conversation_id": "conv_id_from_step_1",
  "text": "Hello, I need help!"
}

Authentication

All widget API requests are authenticated using your widget key. Include the key in the request body of every call. Keys start with wk_ and are tied to a specific agent.

Where to find your key

Go to Dashboard > Agents
Select or create an agent
Copy the key from the Embed Code section

Initialize Conversation

POST/api/widget/init

Creates a new conversation and returns the conversation ID. Call this once per chat session.

Request Body

Field	Type	Required	Description
`key`	string	Yes	Your widget API key (starts with wk_)
`visitor_id`	string	No	Optional visitor identifier for tracking returning users
`page_url`	string	No	URL of the page where the chat was started

Response 200 OK

{
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "visitor_id": "v_abc123",
  "chatbot_name": "Support Bot",
  "config": {}
}

Field	Type	Description
`conversation_id`	string	Unique conversation identifier — use this in all subsequent chat requests
`visitor_id`	string	Visitor ID (generated if not provided in the request)
`chatbot_name`	string	Display name of the agent
`config`	object	Agent configuration metadata

Send Message

POST/api/widget/chat

Sends a user message and returns the AI agent's response. Messages are persisted and visible in your dashboard.

Request Body

Field	Type	Required	Description
`key`	string	Yes	Your widget API key
`conversation_id`	string	Yes	Conversation ID from the init response
`text`	string	Yes	User message (max 2,000 characters)
`visitor_id`	string	No	Visitor identifier
`lang`	string	No	Language code: en, ro, or ru (default: en)

Response 200 OK

{
  "response": "Hi! I'd be happy to help. What can I do for you today?",
  "user_reply_options": ["Check order status", "Talk to a human", "Browse products"]
}

Field	Type	Description
`response`	string	The AI agent's reply text
`user_reply_options`	string[]	Optional quick-reply suggestions (may be absent)

Note: The user_reply_options array is optional and may not be present in every response. When provided, you can display these as quick-reply buttons.

Rate Limiting

Both widget endpoints are rate-limited per IP address. If you exceed the limit, you'll receive a 429 response. Wait a few seconds and retry. Rate limits are generous for normal usage — they only trigger to prevent abuse.

Error Codes

All errors return a JSON object with an error field describing the issue.

Status	Description
400 Bad Request	Missing or invalid required fields in the request body.
403 Forbidden	Invalid or inactive widget key, or invalid conversation.
429 Too Many Requests	Rate limit exceeded. Wait and retry.
502 Bad Gateway	The AI agent backend is temporarily unavailable.
504 Gateway Timeout	The request timed out. Try again.

Error response format

{
  "error": "Invalid or inactive widget key"
}

Embed Snippet

The easiest way to add the chat widget to your website is with our drop-in script tag. No API calls needed — it handles everything automatically.

<script src="https://nexontech.org/widget.js" data-key="wk_your_widget_key"></script>

Replace wk_your_widget_key with your actual key from the dashboard. The script loads asynchronously and won't block your page.

Ready to integrate?

Go to Dashboard Contact Support