Add custom Kapa handoff ticket flow for docs chat by dannyneira · Pull Request #368 · warpdotdev/docs

dannyneira · 2026-07-23T23:30:55Z

Summary

add an always-on Create ticket action to the custom Kapa chat footer UI
add a structured handoff form (email + optional note) styled to match current chat controls
submit full conversation context (Q/A transcript, sources, page URL, thread ID, timestamp) to a new backend endpoint
add /api/kapa-handoff with preview mode by default and optional webhook forwarding via KAPA_HANDOFF_WEBHOOK_URL

Why

Search behavior is production-build-dependent, so this change needs CI/preview validation in a draft PR instead of relying on local dev mode.

Testing

npm run typecheck (passes)
npm run build (passes)
verify handoff flow in preview/deploy:
- open Ask chat
- click Create ticket
- submit with email and optional note
- confirm success state and payload handling

Artifacts

Conversation: https://staging.warp.dev/conversation/277e0d40-2c63-463b-970a-f17903a7bf51

Co-Authored-By: Oz oz-agent@warp.dev

Adds an always-on Create ticket action in the Kapa chat UI, includes transcript context in submissions, and provides a preview/webhook backend endpoint for handoff testing. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel · 2026-07-23T23:30:57Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Error		Jul 23, 2026 11:41pm

Set the handoff endpoint to non-prerendered so static/SSR build inputs resolve correctly in CI and Vercel. Co-Authored-By: Oz <oz-agent@warp.dev>

oz-for-oss · 2026-07-23T23:36:08Z

@dannyneira

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR adds a Kapa chat "Create ticket" handoff form and a new /api/kapa-handoff endpoint that either forwards transcripts to a configured webhook or logs preview submissions.

Concerns

The new public POST route can be invoked directly and forwards or logs user-controlled transcript content without abuse controls or field-size limits.
The route assumes parsed JSON is a non-null object with string fields, so valid but malformed payloads can still throw 500s.
Preview mode logs reply email, note, page URL, and transcript into server logs by default.

Security

Add abuse protection and server-side size limits before forwarding support-ticket payloads.
Avoid retaining user conversation content or email addresses in preview logs by default.

Spec alignment

No approved or repository spec context was provided, so no spec-drift findings were evaluated.

Verdict

Found: 0 critical, 3 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss · 2026-07-23T23:39:02Z

+	return `${value.slice(0, maxLength)}…`;
+}
+
+export const POST: APIRoute = async ({ request }) => {


⚠️ [IMPORTANT] [SECURITY] This public endpoint accepts and forwards/logs arbitrary transcript payloads with no abuse control or field-size limits; add rate limiting/CAPTCHA or equivalent gating plus server-side caps before enabling webhook delivery.

oz-for-oss · 2026-07-23T23:39:02Z

+		});
+	}
+
+	const replyToEmail = payload.replyToEmail?.trim() ?? '';


⚠️ [IMPORTANT] request.json() can return null or non-object values, so this property read can throw a 500; validate that payload is a non-null object and coerce/check field types before using them.

oz-for-oss · 2026-07-23T23:39:02Z

+		});
+	}
+
+	console.info(


⚠️ [IMPORTANT] [SECURITY] Preview mode writes the user's email, note, page URL, and transcript to server logs; log metadata only or gate preview logging so support conversations and contact info are not retained in logs by default.

Move the custom handoff POST route to /kapa-handoff and remove the stale /api/kapa-handoff file to avoid CI/Vercel SSR rollup conflicts with the /api docs page. Co-Authored-By: Oz <oz-agent@warp.dev>

oz-for-oss · 2026-07-23T23:47:39Z

@dannyneira

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR adds a custom Kapa handoff form to the docs chat UI and a new Astro POST endpoint that either forwards submissions to a configured webhook or records preview submissions server-side.

Concerns

The new public handoff endpoint accepts anonymous submissions and forwards them to the webhook without visible bot protection, rate limiting, or other abuse controls.
Preview mode logs user email, note, page URL, and transcript content to server logs when the webhook is unset.

Security

The endpoint should add anti-abuse controls before forwarding ticket payloads.
Preview mode should avoid logging sensitive user-provided conversation data.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss · 2026-07-23T23:51:02Z

+	return `${value.slice(0, maxLength)}…`;
+}
+
+export const POST: APIRoute = async ({ request }) => {


⚠️ [IMPORTANT] [SECURITY] This anonymous endpoint forwards every valid submission to the configured webhook with no bot protection, rate limiting, or abuse control. Add a CAPTCHA/rate-limit guard before accepting submissions, otherwise anyone can spam support or force webhook traffic.

oz-for-oss · 2026-07-23T23:51:02Z

+	console.info(
+		'[kapa-handoff-preview] Received handoff request:\n',
+		truncate(ticketBody, 6000)


⚠️ [IMPORTANT] [SECURITY] Preview mode logs the reply-to email, note, page URL, and transcript. If KAPA_HANDOFF_WEBHOOK_URL is missing in production, user PII and conversation content will be persisted in platform logs; return preview metadata without logging ticketBody, or redact the sensitive fields first.

Add custom Kapa handoff ticket flow for docs chat

18e7ccf

Adds an always-on Create ticket action in the Kapa chat UI, includes transcript context in submissions, and provides a preview/webhook backend endpoint for handoff testing. Co-Authored-By: Oz <oz-agent@warp.dev>

cla-bot Bot added the cla-signed label Jul 23, 2026

vercel Bot had a problem deploying to Preview July 23, 2026 23:31 Failure

Fix PR preview build for Kapa handoff API route

939c966

Set the handoff endpoint to non-prerendered so static/SSR build inputs resolve correctly in CI and Vercel. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot had a problem deploying to Preview July 23, 2026 23:34 Failure

dannyneira marked this pull request as ready for review July 23, 2026 23:35

dannyneira marked this pull request as draft July 23, 2026 23:38

oz-for-oss Bot reviewed Jul 23, 2026

View reviewed changes

Fix preview build by moving handoff endpoint off /api

6c0eb87

Move the custom handoff POST route to /kapa-handoff and remove the stale /api/kapa-handoff file to avoid CI/Vercel SSR rollup conflicts with the /api docs page. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel Bot had a problem deploying to Preview July 23, 2026 23:41 Failure

dannyneira marked this pull request as ready for review July 23, 2026 23:47

dannyneira marked this pull request as draft July 23, 2026 23:47

oz-for-oss Bot reviewed Jul 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add custom Kapa handoff ticket flow for docs chat - #368

Add custom Kapa handoff ticket flow for docs chat#368
dannyneira wants to merge 3 commits into
mainfrom
danny/kapa-handoff-preview

dannyneira commented Jul 23, 2026

Uh oh!

vercel Bot commented Jul 23, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot commented Jul 23, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot left a comment

Uh oh!

oz-for-oss Bot Jul 23, 2026

Uh oh!

oz-for-oss Bot Jul 23, 2026

Uh oh!

oz-for-oss Bot Jul 23, 2026

Uh oh!

oz-for-oss Bot commented Jul 23, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot left a comment

Uh oh!

oz-for-oss Bot Jul 23, 2026

Uh oh!

oz-for-oss Bot Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

dannyneira commented Jul 23, 2026

Summary

Why

Testing

Artifacts

Uh oh!

vercel Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Security

Spec alignment

Verdict

Uh oh!

oz-for-oss Bot Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Security

Verdict

Uh oh!

oz-for-oss Bot Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel Bot commented Jul 23, 2026 •

edited

Loading

oz-for-oss Bot commented Jul 23, 2026 •

edited

Loading

oz-for-oss Bot commented Jul 23, 2026 •

edited

Loading