Triggers

One-shot init payloads that start an assistant conversation with personalized content and variables.

Overview

A trigger is a server-stored init payload that starts a conversation with an assistant. It is not the conversation itself — it primes the first turn with resolved content and optional variables, then links to the conversation once used.

Use triggers when the agent should speak first with context that is specific to the end user (for example an assessment with student name and rubric), without putting large payloads in the URL.

How it works

Your backend (or the dashboard) creates a trigger for a published deployment with content, optional variables, optional ui_surface, and optional ttl_hours.
You distribute a link that includes tid={trigger_id} (8 characters) (for example https://chat.amarsia.com/chat/{deployment_id}?tid=...).
The chat UI loads the trigger (public GET). If unused, it starts a conversation and sends the stored content with trigger_id on the first runner call.
The runner links conversation_id (and the workflow log) to the trigger. Later visits with the same tid resume that conversation.

flowchart LR
  create[Create trigger] --> link[Share URL with tid]
  link --> get[GET trigger]
  get --> unused{conversation_id null?}
  unused -->|yes and not expired| fire[Start conversation]
  unused -->|no| resume[Resume conversation]
  unused -->|expired| block[Show expired]

Key terms

Term	Definition
Trigger	One-shot init object: `content`, `variables`, `expires_at`, optional `conversation_id`
`trigger_required`	Workflow setting. When true, runner calls without `trigger_id` are rejected
Unused	`conversation_id` is null and not expired — can start a new conversation
In use	`conversation_id` is set — resume only; cannot start a new conversation from this trigger
Expired	`expires_at` is set and in the past — link cannot be used
`tid`	Query param used by chat.amarsia.com to load a trigger

Triggers

Overview

How it works

Key terms

Related

On this page