Automations - Spark OS Documentation

Automations let your agent respond to events automatically — without you sending a message or being online. When something happens (a new lead arrives, a contact changes stage, a task becomes overdue), your agent can take action.

How Automations Work

Every automation has two parts:

Trigger — the event that starts it
Action — what your agent does in response

When a trigger fires, your agent wakes up in an isolated session, processes the event, and takes the defined action.

The Automations Tab

Navigate to the Automations tab in your workspace sidebar. Here you can:

View all configured automations
Create new automations
Enable or disable existing ones
See the run history for each automation

Setting Up an Automation

Choose a Trigger

Select what event should kick off the automation. See the trigger types below.

Define the Action

Write what your agent should do when the trigger fires. This is a plain-language instruction — the same way you’d tell your agent something in chat.

Configure Options

Set any additional options — filters, conditions, or scheduling constraints.

Enable It

Toggle the automation on. It starts listening for the trigger immediately.

Trigger Types

New Contact Created

Fires when a new contact is added to your workspace — whether manually, via webhook, or by your agent.Common uses:

Process and qualify new leads
Send a welcome email
Create an initial follow-up task
Notify your team

Example action:

“Review the new contact’s details. Score them as hot, warm, or cool based on their source and any notes. If they included a message, draft a personalized response email. Create a follow-up task for tomorrow.”

Contact Stage Changed

Fires when a contact moves to a different pipeline stage.Common uses:

Send stage-specific emails (e.g., welcome email when moved to Customer)
Update related deals
Notify team members about progress
Create stage-appropriate tasks

Example action:

“The contact moved to Proposal Sent. Create a follow-up task for 3 business days from now titled ‘Check in on proposal.’ If they have a deal, update the deal stage to match.”

Webhook Received

Fires when an external system sends data to your webhook URL. This is how form submissions, third-party tools, and external events reach your agent.Common uses:

Process form submissions (lead capture, contact forms)
Handle events from third-party tools
Sync data from external systems

Example action:

“Parse the incoming webhook data. Create a new contact with the available fields. If they mentioned a specific service in their message, set their tag to that service. Score the lead and create an appropriate follow-up task.”

See Webhooks for setup details.

Task Overdue

Fires when a task passes its due date without being completed.Common uses:

Escalate to a team member
Remind the assigned person
Reschedule the task
Log the missed follow-up

Example action:

“The task is overdue. Check the associated contact — if they’re a hot lead, send me an urgent notification. Reschedule the task for tomorrow and add a note that it was pushed from the original due date.”

Email Received

Fires when a new email arrives in your connected Gmail inbox (requires Gmail integration).Common uses:

Auto-respond to inquiries
Extract contact information from emails
Route emails to the right team member
Log email content on the associated contact

Example action:

“Read the incoming email. If it’s from an existing contact, add a note to their profile with a summary. If it’s from someone new and looks like a business inquiry, create a new contact and classify the lead. Ignore newsletters and automated emails.”

Calendar Event Starting

Fires before a calendar event begins (requires Google Calendar integration).Common uses:

Prepare briefing notes for meetings
Send reminder messages
Pull up relevant contact info

Example action:

“A meeting is starting in 15 minutes. Look up the attendees in our CRM and prepare a brief summary — their pipeline stage, last interaction, and any open deals. Post this to chat.”

Writing Effective Automation Actions

The action field is where you tell your agent what to do. Think of it as a mini instruction set that runs every time the trigger fires.

✅ Good Actions
❌ Bad Actions

Review the new lead's submission data. Create a contact with 
their name, email, phone, and company. Score them as:
- Hot: if they requested a demo or pricing
- Warm: if they asked a specific product question
- Cool: if it's a general inquiry

Set their pipeline stage based on score (Hot → Qualified, 
Warm → Contacted, Cool → New Lead). Create a follow-up task 
with a due date based on their score. Post a summary to chat.

This is specific, has clear logic, and tells the agent exactly what to produce.

Handle the new lead.

This gives the agent no guidance. It’ll do something, but probably not what you want.

Test your automation actions by pasting them into chat first. Send your agent the instruction along with sample data and see what it does. Once you’re happy with the result, use that same instruction as the automation action.

Automation + Schedules

Automations and schedules are complementary:

Feature	Automations	Schedules
Triggered by	Events (something happened)	Time (clock hit a certain time)
Runs when	Immediately on event	On the defined schedule
Best for	Reacting to new data	Recurring reviews and reports
Example	”When a new lead arrives, process it"	"Every morning, review all leads”

Use them together:

Automation: When a new lead arrives → create the contact and a follow-up task
Schedule: Every morning at 8am → review all open tasks and post today’s priorities

Conditions and Filters

Some automations support conditions to narrow when they fire:

Stage filter — only trigger when a contact enters a specific stage
Tag filter — only trigger for contacts with certain tags
Source filter — only trigger for leads from a specific source

If built-in filters don’t cover your logic, put conditions in the action itself:

When the new contact is created, check their source. 
If they came from our website contact form, process them as a 
warm lead. If they came from a partner referral, tag them as 
"Partner Referral" and process as a hot lead. 
If the source is unknown, tag as "Review Needed" and skip automation.

Your agent evaluates these conditions and acts accordingly.

Managing Automations

Enabling / Disabling

Toggle any automation on or off without deleting it. Useful when you want to pause processing temporarily (e.g., during a system migration).

Run History

Each automation keeps a log of every time it ran:

When it fired
What triggered it
What the agent did
Whether it succeeded or encountered an error

Review this log to verify your automations are working as expected.

Debugging

If an automation isn’t doing what you expect:

Check the run history for the specific trigger event
Look at what data was available to the agent
Test the action by sending it to your agent in chat with sample data
Refine the action wording and re-test

Automations run in isolated sessions. Your agent won’t have context from your recent chat — it only has its knowledge files, memory, and the trigger data. Make sure your action instructions are self-contained and don’t assume conversational context.

Example: Full Lead Capture Automation

Here’s a complete example of a lead capture automation: Trigger: Webhook received (from your website contact form) Action:

A new form submission arrived via webhook. Parse the data and:

1. Check if a contact with this email already exists
   - If yes: update their record with any new info and add a note
   - If no: create a new contact

2. Fill in all available fields: name, email, phone, company

3. Read their message and score the lead:
   - Mentions pricing, demo, or buying → Hot
   - Asks about specific features or services → Warm
   - General question or just browsing → Cool

4. Set pipeline stage: Hot → Qualified, Warm → Contacted, Cool → New Lead

5. Create a follow-up task:
   - Hot: due in 2 hours
   - Warm: due tomorrow at 9am
   - Cool: due in 3 business days

6. Draft a personalized response email based on their inquiry.
   Reference our Pricing Guide if they asked about pricing.
   Save the draft for review — do not send automatically.

7. Post a summary to chat: contact name, score, and key details.

This gives your agent everything it needs to handle the lead end-to-end.

​How Automations Work

​The Automations Tab

​Setting Up an Automation

​Trigger Types

​Writing Effective Automation Actions

​Automation + Schedules

​Conditions and Filters

​Managing Automations

​Enabling / Disabling

​Run History

​Debugging

​Example: Full Lead Capture Automation

How Automations Work

The Automations Tab

Setting Up an Automation

Trigger Types

Writing Effective Automation Actions

Automation + Schedules

Conditions and Filters

Managing Automations

Enabling / Disabling

Run History

Debugging

Example: Full Lead Capture Automation