[zamanafzal]

What are the relevant tickets?

Part of https://github.com/mitodl/hq/issues/13712. Frontend half is mitodl/smoot-design#274.

Description (What does it do?)

A SupportBot that asks a learner what went wrong, collects a reply-to address, shows the request back for review, and files one Zendesk ticket per chat thread. It answers nothing on purpose — it's an intake form with a conversational front end, not a tutor, and both the conversation and the filing run in code rather than through the model.

• http/support_agent/ SSE route, SupportBotHttpConsumer and SupportChatRequestSerializer, taking the single-message request shape the widget posts.
• Ticket filing in ai_chatbots/zendesk.py, called from get_completion.
• UserChatSession.support_ticket_reference and support_ticket_email, so a reconnecting learner isn't asked twice or filed twice.
• Its own throttle scope, seeded at 100/day authenticated and 50/day anonymous (main/migrations/0004_support_rate_limit.py).
• AI_CHATBOTS_COOKIE_CROSS_SITE, so the thread cookie carries SameSite=None; Secure when the widget is embedded on another origin, plus an origin check on BaseBotHttpConsumer — these routes sit ahead of
  django_asgi_app in main/asgi.py, so CsrfViewMiddleware never runs for them.
• A thread id no longer works as a bearer token: may_continue_thread() applies one ownership rule however the thread id arrived, body or cookie. That bug predates this PR, but the cross-site cookie above is what makes it reachable from another origin, so it's fixed here rather than left as a merge order someone has to remember.
• Sentry drops frame locals from every frame of an event whose stack touches ai_chatbots (main/sentry.py). The reply-to address and the learner's own words travel as plain arguments right through that package and the SDK ships locals by default, so a traceback anywhere in the intake would have carried them. It is the whole event rather than the chatbot frames alone because the data does not stay inside the package - a DRF ValidationError is raised from rest_framework's own frame, whose self renders the entire request body. Scoped to the event rather than disabling locals globally, so every other app keeps the locals that make a traceback readable.

The three custom ticket field ids have to be set in each deployed environment (Admin Center > Objects and rules > Tickets > Fields), or tickets arrive without the name and username, and with the page URL only in the comment body rather than in its own field. Full config checklist is under

Additional Context.

Implementation details

Request shape. message, plus optional page_url, user_email,
user_name, user_username, confirm, and the usual thread_id /
clear_history. An authenticated learn-ai session always beats the body, so a
request can't name somebody else as the requester for a signed-in learner;
hosts learn-ai holds no session for (the edX MFE) fall back to the body and get
the tim_unverified_requester tag. Whether the address is verified is decided
from the request doing the filing, never inherited from an earlier turn of the
thread. confirm is the widget's Send button, so a learner's approval doesn't
depend on the bot recognising the word they typed. user_username is kept
distinct from user_name because Zendesk's username field should only ever
carry the literal handle.

Why nothing here is a LangGraph tool. file_support_ticket isn't in tools.py and isn't registered as a tool. A model that declines to emit the call leaves a learner who was told their request was filed with no way to find
out it wasn't. Same reasoning for the conversation: it's a fixed form (collect
the problem and a reply-to, show it back, file), so a model only adds a
dependency and a way for every intake to fail. SupportBot.CALLS_THE_MODEL = False skips create_proxy_user, a blocking HTTP call that would otherwise put
the intake form — the thing a learner reaches when something else is already
broken — behind the LiteLLM proxy being up. get_llm still runs;
create_react_agent needs it to build the graph the bot reads and writes thread
state through.

Send, edit or cancel. A go-ahead files, a plain no cancels, a sentence of
detail is folded in and re-reviewed, and a short reply that opens with "yes" but
carries other words gets asked about — "yes please send it to support asap" adds
nothing to the ticket while "yes, and the course is 18.01" does, and nothing
here can tell them apart. A wrong cancel costs a turn to undo; a wrong send
cannot be undone. Cancelling withdraws the request rather than just the send:
the next thing the learner types starts a fresh one, so withdrawn words can't
reappear in a later ticket — which on a shared device would be someone else's.

What reaches support. Every message the learner typed about the problem
since the last cancellation, with the bare reply-to address and bare
confirmations dropped. The opening
message is kept whatever it looks like: nobody has been asked for an address at
that point, so "I can't log in as x@y.com" is the problem rather than an answer,
and dropping it filed an empty ticket.

One ticket per thread. A cache.aadd lock keyed on the thread, an
arefresh_from_db inside the lock (the lock alone leaves the read-then-write
window open), and an Idempotency-Key header plus external_id both keyed on
the thread id. The lock's TTL is sized off the worst-case filing path — mint a
token, POST, re-mint on a 401, POST again, and a scalar httpx timeout is a budget
per phase rather than per request, so each of those four can spend four
REQUESTS_TIMEOUTs — rather than a round number, since a lock that lapses while
the first turn is still in flight lets a second one through at the one moment
it must not get through.

A lost reply isn't a failure. A 5xx or a read timeout after the request went
out may still have created the ticket, so the bot says it may have gone through
and stops rather than inviting the retry that duplicates it.
ConnectTimeout/PoolTimeout and any failure minting the OAuth token are
definite failures, since nothing was posted.

Zendesk configuration. AI_ZENDESK_API_URL is deliberately separate from
the existing AI_ZENDESK_URL: that one is the branded help center used for
article search, while ticket API calls have to go to the canonical
{subdomain}.zendesk.com host. Auth is OAuth client_credentials
(AI_ZENDESK_OAUTH_CLIENT_ID / AI_ZENDESK_OAUTH_CLIENT_SECRET), minting a
short-lived access token, caching it until just before expiry and re-minting
once on a 401 — API tokens stop working 2027-04-30, so this is the supported
server-to-server path. AI_ZENDESK_STUB_MODE defaults to False: an
environment that forgets to configure Zendesk should fail loudly rather than
tell every learner their request was filed and drop it;
env/backend.local.example.env turns it on for local work. The stub still
validates the address first, so a malformed one can't pass locally and fail only
where Zendesk is configured. The custom field ids (AI_ZENDESK_URL_FIELD_ID,
AI_ZENDESK_NAME_FIELD_ID, AI_ZENDESK_USERNAME_FIELD_ID) are configured
rather than hardcoded because they're minted per Zendesk instance and Zendesk
rejects a whole ticket for an id it doesn't recognise; unset means the value is
left off. Every ticket carries tim_support_intake, and one the caller asserted
the address for also carries tim_unverified_requester. On those, the first
comment is filed private and the subject is replaced with a fixed one: this call
authenticates as an agent, so nothing has proved the requester owns the address
the caller named, and a public first comment plus a caller-chosen subject is a
way to send chosen text to a chosen address over MIT's domain through whichever
received-request trigger the instance has turned on. Agents still read the
learner's own subject and words on the ticket itself.

Cross-site cookies. Carry SameSite=None;Secure whenever
AI_CHATBOTS_COOKIE_CROSS_SITE is on; what the allow-list gates is which
cross-origin callers get a response at all. The "null" origin is never accepted. The origin check
allows a same-origin request before it consults the allow-list at all, the
way CsrfViewMiddleware does, so no environment has to list its own origin.
It also allows an absent origin (server-to-server callers send none, and a
Referrer-Policy can strip both headers) and an empty allow-list, the latter
only while cookies stay same-site — the pair of cross-site cookies and no allow-list
fails closed.

How can this be tested?

docker compose run --rm web pytest: 860 passed, 1 skipped, 5 failed. The 5 are
pre-existing — I re-ran the same tests on origin/main in a separate worktree
and got the identical 5. Four are tutor tests that need network for LiteLLM's
model-cost map (the run logs a ConnectTimeout fetching it); the fifth is
main/opik_keycloak_auth_test.py.

To walk the flow, with AI_ZENDESK_STUB_MODE=True in env/backend.local.env so
no real ticket is filed:

1. docker compose up
2. Post to the route and watch the SSE stream:

   curl -N -X POST http://ai.open.odl.local:8003/http/support_agent/ \
     -H 'Content-Type: application/json' \
     -d '{"message": "my video will not play", "page_url": "https://example.com/c/18.01", "clear_history": true}'
   

   It should ask for detail and an address rather than trying to answer.
3. Reply with an address on the same cookie. It shows the ticket for review
   before filing.
4. Reply "no" and confirm nothing is filed, then describe a different problem
   and confirm the review shows only the new one. Reply "yes please send it
   over" and confirm it asks rather than sending. Reply with extra detail and
   confirm the review comes back with it included.
5. Reply "send", then check the reference landed:

   docker compose run --rm web python manage.py shell -c \
     "from ai_chatbots.models import UserChatSession as S; print(S.objects.order_by('-id').values('thread_id','support_ticket_reference','support_ticket_email')[:1])"
   

   A stub reference looks like STUB-A1B2C3D4, so it can't be mistaken for a
   real ticket number.
6. Post again on the same thread and confirm no second ticket is filed.

Additional Context

Before this does anything in a deployed environment: AI_ZENDESK_API_URL, the
OAuth client id and secret, the three custom field ids, AI_ZENDESK_STUB_MODE
off, and CORS_ALLOW_ORIGINS plus AI_CHATBOTS_COOKIE_CROSS_SITE for the
embedding origins. CORS_ALLOW_ORIGINS comes from Vault and doesn't appear in
ol-infrastructure, so I couldn't confirm its current value anywhere, and
cross-site cookies have to stay off for plain-HTTP local dev since browsers
reject Secure cookies over HTTP. Nothing mounts the widget yet either — this
and smoot-design#274 give the launcher and the backend; a host still has to
render it.

Known gaps, each tracked separately:

• The anonymous throttle never fires (mitodl/hq#13968) and two anonymous
  learners can share a thread identity (mitodl/hq#13990). Both come from
  main/consumers.py keying anonymous callers on a Django session key that,
  under signed_cookies with an always-empty session, is a wall-clock-second
  timestamp. Every anonymous chat route, not just this one — so the throttle
  this PR seeds does not currently limit anonymous callers.
• Scripted turns don't reach the chat-history API (mitodl/hq#13986), because
  aupdate_state(..., as_node="agent") yields updated_channels=None and
  ChatMessageViewSet selects on metadata.writes. The review, the filing
  result and the already-filed reply are invisible to it, so a learner who
  reconnects sees a thread with holes. The fix is in the checkpointer every bot
  shares.
• An unverified name and username look verified on the ticket
  (mitodl/hq#13985) — only the tag says otherwise.
• APISIX profile details go stale after a learner's first login
  (mitodl/hq#13987), on the login path every ASGI request takes.
• A typed address can't override an authenticated one, which is what stops the
  chat naming a stranger as the requester. A learner signed into the wrong
  account can sign out and use the form anonymously, which gets them the
  unverified-requester path and the tag.
• "Verify anonymous requests" is off on the sandbox Zendesk account, so this
  route accepts an unverified address from an anonymous submitter exactly as the
  help center form there does; the production account still has to be checked
  before launch. The private comment and fixed subject above mean a
  received-request trigger has nothing of the caller's to put in that email
  through the usual comment placeholders, but which placeholders the triggers on
  each account actually use hasn't been checked, and {{ticket.description}} is
  the one to look at.
• The Idempotency-Key tests only assert that the same key and external_id go
  out, including on the re-POST after a 401 - against a mocked httpx client, not
  the stub, which returns before any request is sent. Zendesk documents a 2-hour
  replay window; that hasn't been confirmed against a live instance.

[Copilot]

🟡 Changes recommended

Cross-site write protection and support-flow correctness issues remain unresolved.

4 open findings

• Prevent credentialed cross-site writes with default CORS and cookies · New
• Preserve opening problem messages during reply-to address collection · New
• Persist deterministic exchanges for chat-history API retrieval · New
• Honor cancellation before filing support tickets · New

What changed in this PR

Adds the backend for conversational support intake, connecting learner chat threads to Zendesk tickets.

Changes:

• Adds a support bot, SSE endpoint, request validation, and persistent ticket references.
• Implements Zendesk OAuth authentication, ticket creation, and local stub mode.
• Adds throttling, cross-site cookie settings, origin checks, and regression tests.

File	Description
pytest.ini	Sets Zendesk test defaults.
main/​settings.py	Adds support, Zendesk, and cookie settings.
main/​migrations/​0004_support_rate_limit.py	Seeds support throttling limits.
main/​consumer_throttles_test.py	Checks throttle migration coverage.
env/​backend.local.example.env	Documents local support configuration.
ai_chatbots/​zendesk.py	Implements OAuth and ticket creation.
ai_chatbots/​zendesk_test.py	Tests Zendesk integration behavior.
ai_chatbots/​serializers.py	Validates support requests.
ai_chatbots/​serializers_test.py	Tests support request fields.
ai_chatbots/​routing.py	Registers the support SSE endpoint.
ai_chatbots/​prompts.py	Defines the intake-only prompt.
ai_chatbots/​models.py	Stores ticket reference and email.
ai_chatbots/​migrations/​0015_support_ticket_email.py	Adds the ticket email column.
ai_chatbots/​migrations/​0014_support_ticket_reference.py	Adds the ticket reference column.
ai_chatbots/​consumers.py	Adds support handling and origin validation.
ai_chatbots/​consumers_test.py	Tests identity handling and origin checks.
ai_chatbots/​constants.py	Adds Zendesk constants and cookie attributes.
ai_chatbots/​constants_test.py	Tests cookie configuration.
ai_chatbots/​checkpointers.py	Handles null updated channels.
ai_chatbots/​checkpointers_test.py	Covers null-channel checkpoints.
ai_chatbots/​chatbots.py	Implements intake, review, and filing flow.
ai_chatbots/​chatbots_test.py	Tests support flow and persistence.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Intake parsing, filing retry safety, and sensitive-data redaction still need correction.

6 open issues

• Address extraction corrupts requester and edit details · New
• Unicode normalization triggers unintended confirmation · New
• Uncertain filings can be retried concurrently · New
• Filing lock expires during long-running requests · New
• Post-submit transport errors are misreported as definite failures · New
• Dependency locals leak learner input to Sentry · New

4 resolved since last review

• Prevent credentialed cross-site writes with default CORS and cookies
• Honor cancellation before filing support tickets
• Persist deterministic exchanges for chat-history API retrieval
• Preserve opening problem messages during reply-to address collection

_{Review effort: Balanced}

[mbertrand]

Looking great, just found a few more things.

[mbertrand]

👍