What are Listeners?
Listeners are event sources that trigger your squads automatically. Instead of users sending messages through chat or API, a listener waits for an event (such as a new email, a webhook POST, or a scheduled time) and invokes your squad to process it.
Listeners decide when a squad runs. Orchestrators decide how a squad executes agents after invocation. See What are Orchestrators?.
How Listeners Work
Listeners are attached to squads. When an event occurs, the listener dispatches to the appropriate orchestration service, which uses your squad's agents and configuration to handle the event. This means:
- One squad can have multiple listeners (e.g. one Gmail listener, one webhook listener, one time-based listener).
- Different listeners use different orchestrations if added to the same squad, they all share the same squad (same agents, same configuration).
- The listener type determines what kind of event triggers it; the squad provides the AI capabilities that respond.
Listeners vs. Chat and API
| Trigger | How it works |
|---|---|
| Chat / Widget / API | A user sends a message; the squad responds in real time. |
| Listener | An external event occurs (email, webhook, schedule); the squad processes it automatically. |
Listeners enable use cases like:
- Email auto-reply: Connect Gmail or Outlook; when new emails arrive, your squad generates and sends replies using your knowledge base.
- Webhook integration: External systems (CRMs, ticketing tools, CI/CD) POST to a webhook URL; your squad processes the payload.
- Scheduled tasks: Run your squad on a schedule (e.g. every 5 minutes, hourly) for digest generation, reports, or maintenance tasks.
Requirements
- Squad with API key: A squad must have an API key assigned before listeners can be active. This is used for billing attribution.
- Agents in the squad: The squad needs agents configured to handle the type of work the listener triggers (e.g. an Email Response Agent for Gmail/Outlook listeners).
Managing Listeners
Listeners are managed in two places:
- Squad Listeners tab: When editing a squad, open the Listeners tab to add, edit, or remove listeners for that squad.
- Listeners dashboard: View all listeners across your squads in one place at .
/dashboard/listeners
See Listener Types for details on Gmail, Outlook, Webhook, and Time listeners and how to configure each.