Widget API
The Widget API is the set of HTTP endpoints that the Trackelio widget uses to communicate with the backend. All endpoints are served from https://api.trackelio.com and require the X-Project-Key header for authentication.
Authentication
Section titled “Authentication”Every request must include the project key in the header:
X-Project-Key: YOUR_PROJECT_KEYThe project key is found in your workspace under Sites > Settings. It identifies which workspace and site the request belongs to.
Endpoints
Section titled “Endpoints”| Endpoint | Method | Description |
|---|---|---|
/v1/widget/config | GET | Fetch widget configuration |
/v1/widget/submit | POST | Submit feedback |
/v1/widget/upload | POST | Upload screenshot or recording |
/v1/widget/nps | POST | Submit NPS response |
/v1/widget/csat | POST | Submit CSAT response |
/v1/widget/survey | GET | Load survey definition |
/v1/widget/survey/respond | POST | Submit survey answers |
/v1/widget/messenger/start | POST | Start a chat conversation |
/v1/widget/messenger/message | POST | Send a chat message |
/v1/widget/messenger/history | GET | Load conversation history |
/v1/widget/messenger/end | POST | End a conversation |
/v1/widget/announcements | GET | Fetch announcements |
Widget configuration
Section titled “Widget configuration”GET /v1/widget/config?key=YOUR_PROJECT_KEYReturns the full widget configuration for the given project key, including enabled modules, theming, targeting rules, and feature flags. The widget calls this on initialization to determine how to render.
Feedback submission
Section titled “Feedback submission”POST /v1/widget/submitSubmits a new feedback post. The request payload includes the following fields:
Core fields
Section titled “Core fields”title— The feedback title or summary.description— The full feedback body text.item_type— The type of feedback (e.g., bug, idea, question).
Submitter info
Section titled “Submitter info”- Submitter identity fields such as name, email, and user ID (if identified via the SDK).
Page context
Section titled “Page context”Automatically captured metadata about the page where the feedback was submitted:
url— The full page URL.path— The URL path.title— The page title.referrer— The referring URL.
Viewport and browser data
Section titled “Viewport and browser data”- Viewport dimensions (width and height).
- Browser name, version, and platform information.
Session data
Section titled “Session data”session_token— A token identifying the current user session.
Attachments
Section titled “Attachments”attachment_ids— An array of IDs referencing previously uploaded screenshots or recordings (via/v1/widget/upload).
Element data
Section titled “Element data”- Element-specific data if the user marked a specific element on the page using the visual feedback tool.
Diagnostic data
Section titled “Diagnostic data”console_logs— Captured browser console output.network_logs— Captured network request data.
File upload
Section titled “File upload”POST /v1/widget/uploadUploads a screenshot or screen recording captured by the widget. Returns an attachment ID that can be included in the feedback submission payload.
NPS response
Section titled “NPS response”POST /v1/widget/npsSubmits a Net Promoter Score response, including the numeric score (0—10) and optional feedback text.
CSAT response
Section titled “CSAT response”POST /v1/widget/csatSubmits a Customer Satisfaction response, including the rating value and optional comment.
Surveys
Section titled “Surveys”GET /v1/widget/surveyLoads the survey definition for the current site, including questions, answer types, and display configuration.
POST /v1/widget/survey/respondSubmits the user’s answers to the survey questions.
Messenger
Section titled “Messenger”The messenger endpoints manage real-time chat conversations between users and your team.
POST /v1/widget/messenger/startStarts a new conversation. Returns a conversation ID used in subsequent requests.
POST /v1/widget/messenger/messageSends a message within an active conversation. Requires the conversation ID.
GET /v1/widget/messenger/historyRetrieves the message history for a conversation.
POST /v1/widget/messenger/endEnds an active conversation and marks it as resolved.
Announcements
Section titled “Announcements”GET /v1/widget/announcementsFetches the list of active announcements configured for the site. The widget displays these to users based on targeting and scheduling rules.