# Oppy System Events Reference 04/21/2026

Published: 2026-04-22
Updated: 2026-05-01
Source: https://docs.oppy.pro/n/oppy-system-events-reference
Account: Oppy Inc

---

# 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 |

---

## Visitor Activity Events (Embeddable Widget)

| 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 |

---

## Page Events (Embeddable Widget)

| 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

```javascript
// 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.