Feedback and Leads APIs

All three endpoints require X-Widget-Publishable-Key for browser requests and enforce the agent’s domain allowlist. Lead capture also requires X-Visitor-Id.

Message feedback

Endpoint:

POST /api/feedback

Payload:

{
  "messageId": "msg_123",
  "feedback": "positive",
  "conversationId": "cs_456"
}

feedback supports: positive, negative.

Use the X-Assistant-Message-Id and X-Conversation-Id returned by chat. The message must be an assistant message in that conversation and agent scope.

The latest value replaces the previous value for that message, so a visitor can change a prior thumbs vote. Success returns { "success": true }.

Conversation feedback

Endpoint:

POST /api/conversation-feedback

Payload:

{
  "conversationId": "cs_456",
  "userRating": "positive",
  "userFeedbackComment": "Very helpful",
  "easeOfUseRating": "easy"
}

Ratings:

• userRating: positive or negative
• easeOfUseRating: very-easy, easy, neutral, difficult, very-difficult

Only conversationId is required. The other fields are optional. A successful submission marks the conversation resolved and records its end time, so call this when the visitor finishes the chat—not after every message.

Lead capture

Endpoint:

POST /api/leads

Headers:

• X-Widget-Publishable-Key
• X-Visitor-Id

Payload:

{
  "email": "jane@example.com",
  "name": "Jane Doe",
  "phone": "+1-555-111-2222",
  "message": "Please contact me",
  "conversationId": "cs_456"
}

name and email are required. phone and message are optional. Current limits are 100 characters for name, 255 for email, 30 for phone, and 2000 for message.

Behaviour:

• Creates or updates the contact by email within the workspace.
• Links a valid, agent-scoped conversation to the contact.
• Escalates the conversation only when the agent’s lead-capture handoff rule is enabled.
• Links the contact and matching conversation inside the workspace when a conversation id is supplied.

Do not accept orgId or agentId from an untrusted browser and treat them as authority. Widget scope is resolved from the publishable key and allowed origin.