Oppy System Events Reference

Comprehensive list of all system events emitted by the Oppy platform. Events can be used with Automation Rules to trigger actions.

Event Type Format

Events follow the domain-prefixed format: domain.action

Examples: contact.created, conversation.status_changed, google_calendar.event_created

Contact Events

Event Type	Description	Payload
`contact.created`	New contact created	contact object
`contact.updated`	Contact updated	contact object with changes
`contact.destroyed`	Contact deleted	contact id
`contact.stage_changed`	Contact stage changed	previous_stage, new_stage
`contact.score_changed`	Contact score changed	previous_score, new_score
`contact.dnc_added`	Contact added to Do-Not-Contact list	reason, method (sms/email/all)

Conversation Events

Event Type	Description	Payload
`conversation.created`	New conversation started	conversation object
`conversation.status_changed`	Conversation status changed	previous_status, new_status
`conversation.needs_attention_set`	Conversation flagged for attention	reason, summary
`conversation.needs_attention_cleared`	Attention flag cleared	-

Message Events

Event Type	Description	Payload
`message.created`	New message created	message object
`message.updated`	Message updated	message object
`message.destroyed`	Message deleted	message id
`message.delivered`	Message delivered successfully	message, delivery_method

Email Events (Postmark)

Event Type	Description	Payload
`email.delivered`	Email successfully delivered	message_id, recipient
`email.opened`	Email opened by recipient	message_id, recipient, open_count
`email.clicked`	Link clicked in email	message_id, recipient, link
`email.bounced`	Email bounced	message_id, recipient, bounce_type
`email.spam_complaint`	Email marked as spam	message_id, recipient

Channel Events

Event Type	Description	Payload
`channel.created`	New channel (oppy) created	channel object
`channel.updated`	Channel updated	channel object
`channel.destroyed`	Channel deleted	channel id
`channel.ai_disabled_no_credits`	AI disabled due to insufficient credits	channel_id

Google Calendar Events

Event Type	Description	Payload
`google_calendar.event_created`	Calendar event created	event details, calendar_id
`google_calendar.event_updated`	Calendar event updated	event details, changes
`google_calendar.event_deleted`	Calendar event deleted	event_id, calendar_id
`google_calendar.event_started`	Calendar event started (based on start time)	event details
`google_calendar.event_upcoming_10m`	Calendar event starting in 10 minutes	event details
`google_calendar.event_upcoming_1h`	Calendar event starting in 1 hour	event details
`google_calendar.event_ended`	Calendar event ended	event details
`google_calendar.series_cancelled`	Recurring series cancelled	series details
`google_calendar.instance_cancelled`	Single recurrence instance cancelled	instance details
`google_calendar.calendar_disconnected`	Calendar disconnected from account	calendar_id, email

Account Events

Event Type	Description	Payload
`account.created`	New account created	account object
`account.suspended`	Account suspended	reason
`account.restored`	Account restored after suspension	-
`account.fraud_warning`	Fraud warning received	warning details
`account.services_enabled`	Account services enabled	-
`account.services_disabled`	Account services disabled	reason
`account.invoice_uncollectible`	Invoice marked uncollectible	invoice details

Billing & Subscription Events

Event Type	Description	Payload
`subscription.paid`	Subscription payment successful	subscription details
`subscription.canceled`	Subscription cancelled	reason
`reply.blocked_insufficient_credits`	Reply blocked due to no credits	conversation_id
`invoice.voided`	Invoice voided	invoice details
`payment_method.detached`	Payment method removed	-

Wallet Events

Event Type	Description	Payload
`wallet.auto_recharge_triggered`	Auto-recharge initiated	amount
`wallet.auto_recharge_succeeded`	Auto-recharge completed	amount, new_balance
`wallet.auto_recharge_failed`	Auto-recharge failed	error, amount

Voice & Call Events

Event Type	Description	Payload
`call.rejected_insufficient_credits`	Call rejected due to no credits	contact_id, channel_id
`meeting_ended`	Voice meeting ended	duration, participants
`meeting_failed`	Voice meeting failed	error, reason

Phone Events

Event Type	Description	Payload
`phone.purchased`	Phone number purchased	phone_number, channel_id

Meeting Bot (Attendee) Events

Event Type	Description	Payload
`bot.joined`	Meeting bot joined call	meeting_url
`bot.ended`	Meeting bot finished	duration, transcript_available
`bot.error`	Meeting bot encountered error	error details

Note Events

Event Type	Description	Payload
`note.created`	Note created	note object
`note.updated`	Note updated	note object
`note.destroyed`	Note deleted	note id
`note_pageview`	Public note page viewed (auto-fired by Public::NotesApi)	note_id, slug, ip, user_agent
`note_listen_clicked`	“Listen” button clicked on public note page	note_id, slug
`note_listen_played`	TTS audio playback started	note_id, slug
`note_listen_completed`	TTS audio playback finished to end	note_id, slug
`note_copy_markdown_clicked`	Note copied as markdown from public page	note_id, slug
`note_copy_url_clicked`	Note URL copied to clipboard from public page	note_id, slug, method
`note_share_clicked`	Native share invoked on public note	note_id, slug, method
`note_embed_clicked`	Embedded oppy chat opened on public note	note_id, slug
`note_download_clicked`	Public note printed/downloaded as PDF	note_id, slug, format

Public-page click events fire via POST /comms-api/public/notes/:slug/event (anonymous, slug-scoped, allowlisted event_type).

List & Board Events

Event Type	Description	Payload
`list.created`	List created	list object
`list.updated`	List updated	list object
`list.destroyed`	List deleted	list id
`list_item.created`	List item created	item object
`list_item.updated`	List item updated	item object
`list_item.destroyed`	List item deleted	item id
`board.created`	Board created	board object
`board.updated`	Board updated	board object
`board.destroyed`	Board deleted	board id
`faq.created`	FAQ/Index created	faq object
`faq.updated`	FAQ/Index updated	faq object
`faq.destroyed`	FAQ/Index deleted	faq id

Event Type	Description	Payload
`visitor.session_start`	Visitor started new session	session_id, user_agent
`visitor.click`	Visitor clicked element	element, coordinates
`visitor.link_click`	Visitor clicked a link	url, element
`visitor.idle`	Visitor idle for threshold	idle_duration
`visitor.form_submit`	Visitor submitted a form	form_id, fields
`visitor.scroll_milestone`	Visitor scrolled to milestone	scroll_depth (25/50/75/100)
`visitor.rage_click`	Visitor rage-clicked (multiple rapid clicks)	element, click_count

Event Type	Description	Payload
`page.viewed`	Page view recorded	url, title, referrer
`page.navigated`	Navigation to new page	from_url, to_url
`page.engagement`	Page engagement metrics	time_on_page, scroll_depth

Website Chat Events

Event Type	Description	Payload
`website_chat.conversation_started`	Chat conversation started	embed_key, visitor
`website_chat.message_sent`	Message sent in chat widget	message, direction

Integration Events

Follow Up Boss (FUB)

Event Type	Description	Payload
`fub.peopleCreated`	Contact created via FUB webhook	FUB payload
`fub.peopleUpdated`	Contact updated via FUB webhook	FUB payload

ActiveCampaign

Event Type	Description	Payload
`activecampaign.update`	Contact updated via AC webhook	AC payload
`activecampaign.auth_failure`	AC authentication failed	error
`activecampaign.payment_failure`	AC payment sync failed	error

Legacy Event Type Format (Deprecated)

For backward compatibility, automation rules also support underscore-delimited event types. These are automatically aliased to the new dotted format:

Legacy Format	New Format
`contact_create`	`contact.created`
`contact_update`	`contact.updated`
`note_create`	`note.created`
`message_create`	`message.created`
`channel_create`	`channel.created`
`list_item_destroy`	`list_item.destroyed`
`visitor_click`	`visitor.click`
`page_viewed`	`page.viewed`

Creating Events via API/MCP

// Using MCP manage_events tool
{
  "action": "create",
  "event_type": "custom.my_event",
  "message": "Event description",
  "description": "Detailed description",
  "payload": { "key": "value" },
  "associate_with": [
    { "type": "Contact", "id": "uuid" },
    { "type": "Conversation", "id": "uuid" }
  ]
}

Automation Rules

Events can trigger automation rules with various action types:

sync_card - Sync to a board/list
send_notification - Send webhook notification
send_webhook - Generic webhook with full payload
create_list_item - Create board item (no dedup)
trigger_conversation - Start outreach to contact
post_to_conversation - Post to AI conversation for processing

See manage_automation_rules MCP tool for configuration details.

Oppy System Events Reference 04/21/2026