Widget API Overview

The Widget API is the backend for the web chat widget. It serves widget appearance settings, registers visitors, loads chat history, handles message sending, and delivers new messages in realtime via Socket.IO.

This documentation covers what you need to integrate the Widget API in a production environment.

What does it do?

The widget client (the chat UI embedded in your web page) does not connect directly to the chat database or bot engine. All visitor interaction flows through the Widget API:

Responsibility	Description
Appearance & form	Config to model the widget (theme, required fields, greeting)
Identity	Visitor registration and JWT (accessToken) issuance
History	Message list for the active chat
Sending	Send text or file messages
Live stream	Receive bot / agent replies via Socket.IO

Integration flow

A typical widget session proceeds in this order:

1. GET  /settings/:appId     → widget config
2. POST /register            → accessToken (JWT)
3. Socket.IO  /message       → auth.token = accessToken
4. GET  /message             → geçmiş mesajlar
5. POST /message             → yeni mesaj (text / dosya)
6. Socket "message" event    → bot / agent cevapları

Step-by-step logic

1. Fetch settings — Use Widget Settings to load config by appId. Model form fields, required fields, theme, and greeting messages from this response. JWT is not required.
2. Register the visitor — Send form data via Visitor Registration. The server creates or updates the user and returns an accessToken.
3. Connect to the socket — Connect to the /message namespace with the token. The server joins you to the correct room ({chatAppId}-{chatUserId}).
4. Load history — Fetch existing messages via Message History. The data shape depends on the type field; see Message Types.
5. Send a message — Send user input via Send Message. The socket is only for incoming messages.

Core concepts

Concept	Description
appId	UUID of the chat application. Used in settings and registration requests.
accessToken	JWT obtained after registration. Required for message history, sending messages, and Socket.IO.
Message type (type)	TEXT, IMAGE, VIDEO, AUDIO, FILE, MULTIPLE_CHOICE, MULTIPLE_CHOICE_REPLY, INTERACTIVE, CAROUSEL, TEMPLATE
isFromSupport	If true, the message was sent by a bot/agent; if false, by the visitor.

Base URL

In all examples, BASE_URL refers to:

const BASE_URL = 'https://widget-api.chatbot.aithinks.net';

Live service: https://widget-api.chatbot.aithinks.net/

Next steps

1. Widget Settings — widget config
2. Visitor Registration
3. Authentication — JWT usage
4. Realtime messages
5. Message History
6. Send Message
7. Message types