NodeLoom|Docs
HomeDashboard

Widgets API

Widgets are embeddable chat interfaces powered by AI agent workflows. The API is split into two sections: Dashboard endpoints (JWT-authenticated) for managing widgets, and Public endpoints (token-authenticated) for end-user chat interactions.

Dashboard Endpoints (JWT Auth)

These endpoints require standard JWT cookie authentication and are used from the NodeLoom dashboard to manage widget configurations.

List Widgets

GET
/api/teams/:teamId/widgets

List all widgets for a team

200 OK
[
  {
    "id": "uuid",
    "name": "Support Chat",
    "workflowId": "uuid",
    "active": true,
    "customization": {
      "primaryColor": "#6366f1",
      "title": "How can we help?",
      "position": "bottom-right"
    },
    "createdAt": "2026-02-17T10:00:00.000Z"
  }
]

Create Widget

POST
/api/teams/:teamId/widgets

Create a new widget for a team

FieldTypeRequiredDescription
namestringYesWidget display name
workflowIdUUIDYesAI agent workflow to power the widget
customizationobjectNoVisual customization (colors, title, position, avatar)
allowedDomainsstring[]NoRestrict embedding to specific domains
Request
{
  "name": "Support Chat",
  "workflowId": "uuid",
  "customization": {
    "primaryColor": "#6366f1",
    "title": "How can we help?",
    "position": "bottom-right"
  },
  "allowedDomains": ["example.com", "app.example.com"]
}

Update Widget

PUT
/api/teams/:teamId/widgets/:id

Update widget configuration

Accepts the same fields as create. Only provided fields are updated.

Delete Widget

DELETE
/api/teams/:teamId/widgets/:id

Delete a widget and invalidate its embed token

Irreversible

Deleting a widget immediately invalidates the embed token. Any deployed instances of the widget will stop working.

Get Embed Code

GET
/api/teams/:teamId/widgets/:id/embed-code

Get the HTML embed snippet for a widget

200 OK
{
  "embedCode": "<script src=\"https://your-domain.com/widget.js\" data-token=\"your-widget-token\"></script>"
}

Regenerate Token

POST
/api/teams/:teamId/widgets/:id/regenerate-token

Regenerate the widget embed token

Invalidates the current token and generates a new one. Update the embed snippet on your website after regenerating.

200 OK
{
  "token": "new-widget-token-value",
  "message": "Token regenerated. Update your embed code."
}

Get Widget Stats

GET
/api/teams/:teamId/widgets/:id/stats

Get usage statistics for a widget

200 OK
{
  "totalSessions": 1234,
  "totalMessages": 8765,
  "avgMessagesPerSession": 7.1,
  "activeSessionsToday": 42,
  "tokenUsage": {
    "input": 245000,
    "output": 312000
  }
}

Public Endpoints (Token Auth)

These endpoints are used by the embedded widget on your website. They authenticate using the widget embed token instead of JWT cookies.

Token authentication

Public endpoints authenticate via the widget token passed in the URL path or as a header. No JWT cookie is required.

Initialize Widget

GET
/api/widget-chat/init/:token

Initialize the widget and load configuration

Called when the widget script loads on the page. Returns the widget customization settings and validates the token.

200 OK
{
  "widgetId": "uuid",
  "name": "Support Chat",
  "customization": {
    "primaryColor": "#6366f1",
    "title": "How can we help?",
    "position": "bottom-right",
    "avatarUrl": null
  }
}

Create Chat Session

POST
/api/widget-chat/sessions

Create a new public chat session

FieldTypeRequiredDescription
tokenstringYesThe widget embed token
visitorIdstringNoOptional visitor identifier for session continuity
201 Created
{
  "sessionId": "uuid",
  "createdAt": "2026-02-17T10:00:00.000Z"
}

Get Chat Messages

GET
/api/widget-chat/sessions/:sessionId/messages

Get message history for a widget chat session

200 OK
{
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "content": "I need help with billing",
      "createdAt": "2026-02-17T10:01:00.000Z"
    },
    {
      "id": "uuid",
      "role": "assistant",
      "content": "I can help with billing questions...",
      "createdAt": "2026-02-17T10:01:03.000Z"
    }
  ]
}

Send Chat Message

POST
/api/widget-chat/sessions/:sessionId/messages

Send a message in a widget chat session (streaming response)

FieldTypeRequiredDescription
contentstringYesThe message text
tokenstringYesThe widget embed token

Returns a streaming SSE response, identical in format to the Agent Chat send message endpoint.

Error Codes

StatusMeaning
400Invalid request or missing required fields
401Invalid or expired widget token
403Domain not allowed for this widget
404Widget or session not found
410Widget has been deleted or deactivated
Previous

Agent Chat

Next

Monitoring