> ## Documentation Index
> Fetch the complete documentation index at: https://mantle.rasa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation events

> Mantle tracker and event-broker JSON shape (ProtoJSON).

Mantle persists conversation events and publishes them on the event broker as
**nested ProtoJSON**, not the legacy flat `{"event": "user", ...}` shape.
Legacy (non-Mantle) projects are unchanged.

This page is the builder summary. The authoritative schema lives in
`proto/rasa/events/v1/broker_event.proto` with rules and examples in that
directory's README, plus golden JSON fixtures under
`proto/rasa/events/v1/fixtures/` for consumer tests.

## Shape at a glance

* Each event is one JSON object with envelope fields
  (`conversation_id`, `timestamp`, `event_id`, `sequence`, `user_id`,
  `deployment_environment`, `session_id`, optional `metadata`) and **exactly
  one** nested payload key (`user`, `bot`, `memory_set`, `skill_activated`, …).
* Wire keys are stable snake\_case (`json_name`). Do not assume protobuf field
  identifiers match the JSON keys.
* `conversation_id` is the tracker conversation id (Python still calls this
  `sender_id` on tracker APIs).
* Memory values and tool arguments / results are JSON **strings**
  (`value_json`, `arguments_json`, `result_json`). Parse them once so integers
  stay integers (`"42"` → `42`, not `42.0`).
* Mantle lifecycle events' names include: `skill_*`, `ordered_block_*`,
  `memory_*`, `tool_executed`.

Example:

```json theme={null}
{
  "conversation_id": "conv-1",
  "timestamp": 1788852000.123,
  "event_id": "018f3a2b-7c3d-7e4f-9a10-000000000000",
  "sequence": 0,
  "user_id": "user-1",
  "deployment_environment": "production",
  "session_id": "session-1",
  "user": {
    "text": "I want to transfer money",
    "input_channel": "rest",
    "message_id": "a1b2c3",
    "anonymized_at": null
  }
}
```

## Dual-read

New Mantle saves are ProtoJSON-only. Loading a tracker still accepts a mix of
ProtoJSON and older flat `{"event": "…"}` rows so existing conversations keep
working.

## Sorting and identity

Prefer `sequence` (0-based per conversation) for order. Gaps are possible, so
do not require contiguous values. `event_id` is a UUID v7 string minted on
first ProtoJSON serialize; older rows without these fields still load.

## Suppressed user input

On a voice channel, a final transcript that Mantle deliberately does not
process is recorded as `user_input_suppressed` instead of `user`. No turn runs
for it.

```json theme={null}
{
  "conversation_id": "conv-1",
  "sequence": 12,
  "user_input_suppressed": {
    "text": "I don't remember it",
    "modality": "audio",
    "reason": "dtmf_audio_input_disabled"
  }
}
```

| `reason` | When |
| - | - |
| `dtmf_audio_input_disabled` | The active collect step sets [`allow_audio_input: false`](https://mantle.rasa.com/reference/ordered-block-steps#dtmf) |
| `backchannel` | The caller spoke over the agent with a backchannel such as "uh-huh" |
| `below_min_words` | The caller spoke over the agent with fewer than `min_words` words while the backchannel model was unavailable |
| `interruption_cooldown` | Repeated interruptions temporarily disabled further interruptions |

`text` is the suppressed transcript, so treat it like `user.text`.

## Call recording

A voice call with recording enabled publishes four broker notifications.
They are not tracker events: they are not stored on the conversation and
they do not replay. On a Mantle broker each one is a `BrokerEvent` whose
payload key is the outcome. `call_id` is on that payload. `sequence` is
unset, because these notifications are outside the tracker sequence.
Classic brokers still publish flat `{"event": "call_recording_*"}` bodies.

| Payload | When |
| - | - |
| `call_recording_started` | Recording is enabled as the call starts |
| `call_recording_available` | The file was stored. The payload carries `provider`, `bucket`, `key`, `uri`, and `content_type` |
| `call_recording_failed` | Encode or upload failed. The payload carries `error` |
| `call_recording_skipped` | Recording was enabled but no audio was captured |

```json theme={null}
{
  "conversation_id": "conv-1",
  "timestamp": 1788852000.123,
  "event_id": "018f3a2b-7c3d-7e4f-9a10-000000000090",
  "call_recording_available": {
    "call_id": "call-1",
    "provider": "s3",
    "bucket": "recordings",
    "key": "conv-1-call-1.wav",
    "uri": "s3://recordings/conv-1-call-1.wav",
    "content_type": "audio/wav"
  }
}
```

## Inspector

Inspector shows these ProtoJSON events in the conversation log, including
messages, memory, skills, tools, and the other types on this page. Older flat
events in the same conversation still appear.

## TypeScript consumers

Studio installs the same schema as `@rasahq/rasa-events` from the Rasa Artifact
Registry (same auth pattern as `@rasahq/rasa-inspector`). Until that package is
published, parse against the golden fixtures and the `.proto` file in-repo.
Inspector, which ships in this repository, reads that same schema directly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.