Skip to main content

​
End-to-end message flow

User -> Widget                 : natural-language request
Widget -> Warpy API            : /widget/chat
Warpy API -> Widget            : tool calls or final answer
Widget -> Customer app or API  : execute browser-side tool calls
Customer app or API -> Widget  : tool results
Widget -> Warpy API            : /widget/chat with tool results
Warpy API -> Widget            : final response and suggestions
Widget -> User                 : answer

​
The most important runtime detail

Backend tool calls, frontend tool calls, and screen-autopilot actions all run from the embedded widget and then report results back to Warpy.

​
Tool routing logic

User request
  -> Warpy orchestration
      -> question needs docs              -> Knowledge base search
      -> approved backend action exists   -> Backend tool call
      -> approved frontend action exists  -> Frontend tool call
      -> no tool fits or page help needed -> Screen autopilot

Tool result or retrieved knowledge
  -> answer draft
  -> final answer

​
What each layer is responsible for

LayerResponsibility
Widgetcapture the message, fetch config, execute browser-side tool calls, return results
Warpy APIorchestrate reasoning, choose tools, enforce widget auth, produce the final response
Customer appreceive backend requests, expose frontend handlers, or provide live page context

​
Backend tool execution path

When Warpy returns a backend tool call, the widget:
  1. reads the configured session headers from browser storage
  2. substitutes path parameters
  3. builds query string and body
  4. sends the request to your selected base URL
  5. sends the result back to Warpy

​
Frontend tool execution path

When Warpy returns a manual frontend tool call, the widget:
  1. calls window.warpy(toolName, vars)
  2. waits for your app to finish the handler
  3. sends the result back to Warpy

​
Screen autopilot path

When screen autopilot is enabled, Warpy can:
  • inspect the page structure
  • find the right element
  • click, type, select, navigate, scroll, or run JavaScript
Use this when the best execution surface is the live interface itself.

​
Security and limits in the flow

  • Signed widget tokens are enforced on POST /widget/chat.
  • Token refresh happens through the customer-owned endpoint you configure.
  • Per-user rate limits are checked before and after billable execution.
  • The widget hides when action availability or rate-limit state says it should.