Widget API - SetterMaxer AI

Overview

The Widget API powers the embeddable chat widget. All endpoints are public (no authentication required) but rate-limited and scoped to individual agents.

Endpoints

Create or resume a session

string

required

The agent’s unique identifier.

POST /api/v1/widget/{agentId}/messages

Action: init Creates a new chat session or resumes an existing one.

{
	"action": "init",
	"visitorToken": "optional-existing-token"
}

Response:

{
	"sessionId": "uuid",
	"visitorToken": "uuid",
	"messages": []
}

The visitor token is persisted in the browser’s localStorage as setter_visitor_{agentId}. Returning visitors send their token to resume the previous conversation.

Send a message

POST /api/v1/widget/{agentId}/messages

Action: send

{
	"action": "send",
	"sessionId": "uuid",
	"visitorToken": "uuid",
	"message": "Hi, I'm interested in your product"
}

Response:

{
	"status": "ok"
}

After sending, the client polls for the AI response.

Poll for messages

GET /api/v1/widget/{agentId}/messages?sid={sessionId}&vt={visitorToken}

Returns the latest messages in the conversation. The widget uses exponential backoff polling (500ms → 4s, max 30 seconds) to wait for the AI response. Response:

{
	"messages": [
		{
			"role": "user",
			"content": "Hi, I'm interested in your product",
			"timestamp": "2026-01-15T10:30:00.000Z"
		},
		{
			"role": "model",
			"content": "Welcome! I'd love to help you learn more...",
			"timestamp": "2026-01-15T10:30:02.000Z"
		}
	]
}

GET /api/v1/widget/{agentId}/config

Returns the widget’s display configuration. Response:

{
	"buttonType": "classic_circle",
	"avatarUrl": null,
	"agentName": "Megan"
}

Rate limits

Limit	Value
New sessions per agent per hour	100
Messages per session per minute	10
Max user messages per session	50
Max message length	1,000 characters

429 response — The widget displays a “sending too quickly” message. Timeout — If the AI doesn’t respond within 30 seconds, a “Sorry, I took too long” fallback is shown.

Lead limits

When an organisation exceeds its monthly lead limit, new sessions are created with ai_enabled: false. The agent won’t respond automatically. The conversation is still created so the lead’s message is captured.

​Overview

​Endpoints

​Create or resume a session

​Send a message

​Poll for messages

​Get widget config

​Rate limits

​Lead limits