Events

Ravi’s processes talk over NATS JetStream, and almost everything that happens is published as an event. By the end of this page you will know how to see the topics on your own install, which topic families exist, which streams keep them, and the shape of the events you are most likely to put in a trigger.

Discover topics on your install

The topic list changes between releases, so ask the CLI instead of trusting a copy:

ravi triggers topics            # topics ready for triggers, with payload and examples
ravi triggers topics --json     # the same, machine-readable: id, category, pattern, payload, schema, examples, filters, notes

Watch events as they happen, or read back what was stored:

ravi events                                     # live stream (same as ravi events stream)
ravi events stream --only cli                   # prompt, response, tool, claude, runtime, cli or audit
ravi events stream -f 'ravi.inbound.*' --json   # glob filter, JSONL output
ravi events replay --since 1h --subject 'ravi.audit.>'
ravi events replay --session <nameOrKey> --type <type> -n 20 --json

ravi events replay reads the persisted streams. It defaults to the last 15 minutes and 100 events; --where 'path=value' and --contains <text> narrow it further. To act on an event, create a trigger. The topic is a NATS pattern (* is one token, > is the rest), and --filter tests the event data:

ravi triggers add "Reaction from Ana" \
  --topic "ravi.inbound.reaction" \
  --filter 'data.senderId == "5511999999999"' \
  --message "Ana reacted to a message. Check what she approved." \
  --agent main --cooldown 30s

See Triggers.

The catalog is a set of templates, not a whitelist: a trigger can listen on any subject. Three rules prevent loops. Triggers never subscribe to ravi.session.*. Events whose topic contains :trigger: (published from a trigger’s own session) are skipped. Events whose data carries _trigger: true are skipped.

Topic families

“Trigger” means the family is meant for triggers. “Replay” means it is kept in the RAVI_EVENTS stream for ravi events replay.

Family	Trigger	Replay	What it carries
`ravi.inbound.>`	yes	yes	Normalized channel interactions: `reaction`, `reply`, `pollVote`, `thread.created`, `interaction` (buttons and other components).
`ravi.<sessionKey>.cli.<group>.<command>`	yes	no	A CLI command run from an agent session.
`ravi._cli.cli.<group>.<command>`	yes	yes	A CLI command run outside an agent session.
`ravi.audit.>`	yes	yes	Audit events, mainly `ravi.audit.denied`.
`ravi.approval.>`	yes	yes	`ravi.approval.request` and `ravi.approval.response`.
`ravi.contacts.>`	yes	yes	Contact changes and `ravi.contacts.pending`.
`ravi.chats.>`	yes	yes	Chat changes, `ravi.chats.pending` and chat tags.
`ravi.instances.>`	yes	yes	Channel instance changes and `ravi.instances.unregistered`.
`ravi.console.>`	yes	yes	Console deliveries, mainly `ravi.console.inbox.item`.
`ravi.watch.>`	yes	yes	Normalized watch events, `ravi.watch.<connector>.<eventType>`.
`ravi.inbox.>`	yes	yes	Local inbox events, such as `ravi.inbox.mail.received`.
`ravi.task.>`	yes	yes	Task lifecycle, `ravi.task.<taskId>.event`.
`ravi.sessions.followup.>`	yes	yes	Session follow-up lifecycle.
`ravi.tags.>`	yes	yes	Tag rule applications.
`ravi.tts`, `ravi.tts.*`	yes	yes	Text-to-speech requests and lifecycle.
`ravi.artifacts.>`	yes	yes	Artifact lifecycle.
`ravi.meetings.>`	yes	yes	Meeting lifecycle and artifacts.
`ravi.session.<name>.prompt`	no	no	Prompts waiting for a session (the `SESSION_PROMPTS` work queue).
`ravi.session.<name>.response`, `.tool`, `.runtime`, `.stream`, `.delivery`, `.claude`, `.adapter.>`	no	yes	What a session does during a turn. Watch it with `ravi events stream`.
`ravi.session.abort`, `.reset.`, `.delete.`, `.prune.*`, `.model.changed`, `.runtime.control`	no	yes	Internal session control.
`ravi.outbound.>`	no	yes	Delivery requests: `deliver`, `reaction`, `message.edit`, `message.delete`, `receipt`.
`ravi.presence.>`	no	yes	Typing and other presence.
`ravi.media.send`, `ravi.stickers.send`	no	yes	Media and sticker send requests.
`ravi.whatsapp.>`	no	yes	`ravi.whatsapp.qr.<instanceId>` and `ravi.whatsapp.connected.<instanceId>` during pairing.
`ravi.runtime.>`, `ravi.rtk.>`, `ravi.work_objects.>`	no	yes	Runtime telemetry, hook rewrites and Work Object requests.
`ravi.config.changed`, `ravi.triggers.>`, `ravi.cron.>`, `ravi.heartbeat.>`, `ravi.hooks.>`	no	yes	Internal refresh signals between the CLI and the daemon.

The ravi.session.* and internal families are for observing and debugging. Do not build triggers on them.

Streams

Ravi creates these JetStream streams:

Stream	Subjects	Retention
`SESSION_PROMPTS`	`ravi.session.*.prompt`	Work queue, consumer `ravi-prompts`. Prompts older than 60 seconds are dropped.
`RAVI_EVENTS`	Every family marked “Replay” above	7 days or 512 MB.
`CHANNEL_OUTBOUND`	`ravi.channel.outbound.*`	Outbound jobs for Slack, consumer `ravi-channel-outbound`. 7 days or 256 MB.

Omni owns three streams that the daemon reads with durable consumers. Each consumer starts at new messages, so the daemon does not replay history when it first connects.

Omni stream	Subjects Ravi reads	Ravi consumer
`MESSAGE`	`message.received.>`	`ravi-messages`
`REACTION`	`reaction.received.>`	`ravi-reactions`
`INSTANCE`	`instance.>`	`ravi-instances`

Omni subjects

Omni publishes <eventType>.<channelType>.<instanceId>, for example:

message.received.whatsapp-baileys.<instance-uuid>
reaction.received.whatsapp-baileys.<instance-uuid>
instance.connected.whatsapp-baileys.<instance-uuid>
instance.qr_code.whatsapp-baileys.<instance-uuid>

A message’s metadata.ingestMode is realtime or history-sync. History-sync messages are recorded in Ravi’s chat history but never start a turn. Omni reactions are republished as ravi.inbound.reaction, and pairing events as ravi.whatsapp.qr.<instanceId> and ravi.whatsapp.connected.<instanceId>, so you can trigger on the Ravi topics instead of Omni’s. Native Slack does not go through Omni subjects. Its reactions and interactions arrive on the same ravi.inbound.* topics.

Payloads you will use

Trigger filters and message templates address the payload as data.<path>.

`ravi.inbound.reaction`

{ "targetMessageId": "ABC123XYZ", "emoji": "<emoji>", "senderId": "5511999999999" }

Published for WhatsApp reactions (through Omni) and Slack reaction_added. targetMessageId is the id of the message that got the reaction; keep your own mapping from message id to business state if a routine needs it.

`ravi.audit.denied`

{ type, agentId, denied, reason, dedupeKey, timestamp,
  command?, detail?, blockType?, missingPrincipals?, missingPrincipalDetails?,
  recommendedGrantSubjects?, denialId?, context? }

Published whenever a permission or policy check refuses an agent. missingPrincipals and recommendedGrantSubjects name who lacks the permission and who to grant it to if the denial was wrong. See Permissions.

CLI command audit

When an agent session runs a command, Ravi publishes ravi.<sessionKey>.cli.<group>.<command>, for example ravi.agent:main:main.cli.contacts.add. Commands run outside a session publish ravi._cli.cli.<group>.<command>.

{ tool, input, isError, outcome, exitCode?, errorCode?, durationMs?, timestamp, sessionKey, ... }

tool is <group>_<command> (for example contacts_add). outcome is succeeded, blocked, usage_error, denied or failed. Inputs, and the output of session commands, are sanitized and truncated before they are published.

ravi triggers add "Contact added" --topic "ravi.*.cli.contacts.*" \
  --filter 'data.tool == "contacts_add"' --message "A contact was added. Update the CRM." --agent main

`ravi.console.inbox.item`

When you are logged in to the Console, the daemon polls the agent inbox every 15 seconds and publishes each item here:

{ version, eventId, sequence, dedupeKey, eventType, category, severity, sensitivity,
  title, summary, organization: { id }, project: { id }, source, actor: { type, id },
  target, payload, links, delivery: { ... }, occurredAt, createdAt }

Watch items are also published as ravi.watch.<connector>.<eventType>, for example ravi.watch.console.bug.status for a bug report you follow. Bases events have category: "bases". Turn them on per base with ravi bases subscribe <base> (optionally filtered with --events, --props and --view, and with --trigger to create the trigger too).

Field	Value
`eventType`	`bases.row.created`, `bases.row.updated`, `bases.row.archived`, `bases.row.restored`, or `bases.rows.bulk_changed` (more than 50 rows in one request); `bases.approval.requested`, `bases.approval.decided`; `bases.agent.requested`, `bases.agent.backfill`.
`payload`	`{ baseId, baseSlug, projectId, rowId, version, schemaVersion, changedPropertyCount, surface }`. `surface` is `console`, `cli`, `page` or `system`. Bulk events have no `rowId`. Approval events add `propertyId` and `state`; `bases.agent.requested` adds `propertyId` and `inputsHash`; `bases.agent.backfill` is `{ baseId, baseSlug, projectId, propertyId, rowCount, schemaVersion }`. Items of a filtered subscription add `subscriptionId`.
`payload.row`	Added locally for `bases.row.`, `bases.approval.` and `bases.agent.requested`: `{ rowId, version, values, archivedAt }`, the row as read at delivery (no body).
`payload.rowEnrichment`	`{ "status": "ok" }`, or `{ "status": "failed", "code": ... }` when the row could not be read. Then there is no `payload.row`.
`actor.type`	`user` for a person in the Console or on a page, `cli` for any CLI or agent of this install. `actor.id` is the accountable person.
`dedupeKey`	`bases:row:<rowId>:v<version>:<verb>:<installation>`, plus `:<subscriptionId>` for a filtered subscription.

ravi triggers add "New ticket" --topic "ravi.console.inbox.item" \
  --filter 'data.category == "bases" && data.payload.baseSlug == "tickets" && data.actor.type == "user"' \
  --message "A ticket changed. Process the queue view." --agent main --cooldown 5s

If the agent writes to the same base that wakes it, filter on data.actor.type == "user". Its own writes arrive as cli and would otherwise trigger it again.

See Bases for queues, per-row sessions and cooldown behaviour.

Triggers: create, test and tune triggers.
Architecture: which process publishes what.
Troubleshooting: tracing a message that got no answer.

CLI

System

Tools

Discover topics on your install

Topic families

Streams

Omni subjects

Payloads you will use

`ravi.inbound.reaction`

`ravi.audit.denied`

CLI command audit

`ravi.console.inbox.item`

​Discover topics on your install

​Topic families

​Streams

​Omni subjects

​Payloads you will use

​ravi.inbound.reaction

​ravi.audit.denied

​CLI command audit

​ravi.console.inbox.item

​Related

Discover topics on your install

Topic families

Streams

Omni subjects

Payloads you will use

`ravi.inbound.reaction`

`ravi.audit.denied`

CLI command audit

`ravi.console.inbox.item`

Related