Skip to main content

Decagon Chat Widget Agent

This integration sends text to an anonymous Decagon web chat deployment and returns the next plain-text AI reply. It preserves the Decagon conversation across turns within an evaluation session. Use it for an agent that Decagon has deployed through its web chat product.

The integration reproduces the transport used by a public Decagon widget. It does not authenticate a customer, supply an account identity, or bypass access controls.

Required secrets​

Spec27 stores the deployment values below as project secrets because required secret bindings are the sandbox configuration channel. These values identify the Decagon deployment; they are not Decagon account credentials.

SecretWhat it is
DECAGON_API_ORIGINHTTPS origin that receives the widget's conversation requests, such as https://api.decagon.ai or https://eu.api.decagon.ai.
DECAGON_WIDGET_ORIGINHTTPS origin shown in the widget request's Origin header, such as https://decagon.ai or https://eu.decagon.ai.
DECAGON_TEAM_IDValue of the widget request's x-decagon-auth-team-id header.
DECAGON_FLOW_IDValue of flow_id in the widget's conversation and message request bodies.
DECAGON_METADATA_JSONComplete metadata object from a widget message request. It must include non-empty timezone and user_device strings.
DECAGON_TERMINAL_REPLIES_JSONJSON array of exact terminal reply mappings. Use [] when you have not verified a terminal reply.

Configure Decagon​

Ask your Decagon administrator to publish the agent as an anonymous web chat deployment. Confirm that the deployment answers text messages on a test site before you connect it to Spec27.

Capture the deployment values​

You can read the deployment values from a widget conversation that you are authorized to test:

  1. Open the page that hosts the Decagon widget.
  2. Open your browser's developer tools and select the Network panel.
  3. Clear the recorded requests, open the widget, and send a harmless test message.
  4. Find the request whose path ends in /conversation/new. Copy the URL's scheme and host as DECAGON_API_ORIGIN.
  5. Inspect that request's headers. Copy Origin as DECAGON_WIDGET_ORIGIN and x-decagon-auth-team-id as DECAGON_TEAM_ID.
  6. Inspect the JSON body. Copy flow_id as DECAGON_FLOW_ID.
  7. Find the request whose path matches /chat/<conversation-id>/message. Copy its complete metadata object as one-line JSON for DECAGON_METADATA_JSON.

Set DECAGON_TERMINAL_REPLIES_JSON to [] unless probing has verified that an exact reply ends the native conversation. For a verified terminal reply, use this shape:

[
  {
    "text": "The exact terminal reply",
    "reason": "The Decagon agent ended the conversation"
  }
]

The integration returns the terminal reply for the current turn. If the simulator requests another turn, Spec27 records the configured reason and stops before sending another provider request.

Do not copy the anonymous user ID or conversation ID. The integration creates new values for each evaluation session. If the widget sends a non-empty x-decagon-auth-signature or depends on a signed-in customer, use a custom agent that implements that deployment's authentication contract.

Set the values in Spec27​

  1. Copy Decagon Chat Widget Agent from the registry into your project.
  2. Open the project's secrets and create each exact key listed under Required secrets.
  3. Open the copied agent and use the preview to send a harmless support question.

The metadata value must be valid JSON. Keep string values and property names in double quotes.

Turn support​

This integration supports single-turn and multi-turn evaluations. It keeps one anonymous user ID and Decagon conversation ID for the duration of each sandbox session, so later turns retain the conversation context.

Limitations and notes​

  • The integration supports anonymous web chat deployments. It does not support signed customer sessions.
  • It returns the first non-empty AI text message after the matching user message. It does not serialize cards, forms, files, surveys, or other widget components.
  • Configure verified handoff or conversation-ending announcements through DECAGON_TERMINAL_REPLIES_JSON so later turns stop before another request.
  • The integration enforces a 15-second timeout on conversation creation and message submission. It polls for each reply for up to 36 seconds and bounds every history request by the remaining polling time.
  • Evaluations create real conversations and may invoke tools configured on the Decagon agent. Use a non-production deployment when the agent can change customer or business data.