> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/conversations/sse-events.md).

# SSE Events

The platform publishes real-time events to workspace subscribers via Server-Sent Events (SSE). Each event has a fixed `event_type` discriminator and a typed payload. Events are immutable once published.

Fields that may contain protected health information are annotated in the schema with `x-phi: true`. Consumers that persist or log event payloads can use this annotation to apply redaction or access controls.

## Consuming the Stream

The stream is a standard SSE connection authenticated with a workspace-scoped credential, and every event is scoped to the workspace that produced it. Clients should reconnect automatically with backoff when the connection drops. New event types may be added over time - ignore event types you do not recognize rather than treating them as errors.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/events/stream" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Workspace Events

### Call Events

| Event Type       | Description                         | Key Fields                                                                    |
| ---------------- | ----------------------------------- | ----------------------------------------------------------------------------- |
| `call.started`   | A call session began                | `call_sid`, `direction`, `service_id`, `caller_id`                            |
| `call.ended`     | A call session ended                | `call_sid`, `direction`, `duration_seconds`, `completion_reason`, `escalated` |
| `call.escalated` | A call was escalated to an operator | `call_sid`, `escalation_id`, `trigger`, `reason`                              |

### Text Events

| Event Type               | Description                                         | Key Fields                                                                                         |
| ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `text.started`           | A text session began                                | `session_id`, `service_id`, `channel_kind`, `entity_id`                                            |
| `text.completed`         | A text session ended                                | `session_id`, `duration_seconds`, `turn_count`, `completion_reason`, `final_state`, `channel_kind` |
| `text.agent_message`     | The agent produced a message in a text conversation | `conversation_id`, `text`                                                                          |
| `text.tool_started`      | A tool call started during a text turn              | `conversation_id`, `call_id`, `tool_name`, `depth`                                                 |
| `text.background_result` | A background tool call finished                     | `conversation_id`, `call_id`, `tool_name`, `depth`, `succeeded`, `result`, `duration_ms`           |

### Surface Events

| Event Type                | Description                           | Key Fields                                                                                            |
| ------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `surface.created`         | A surface was created                 | `surface_id`, `entity_id`, `channel`, `fields_count`, `source`, `form_template_id`, `review_required` |
| `surface.delivered`       | A surface was delivered to a patient  | `surface_id`, `entity_id`, `channel`, `channel_address`, `delivery_status`, `message_id`, `short_url` |
| `surface.updated`         | A surface was updated                 | `surface_id`                                                                                          |
| `surface.archived`        | A surface was archived                | `surface_id`                                                                                          |
| `surface.submitted`       | A surface was submitted by a patient  | `surface_id`, `entity_id`, `submitted_at`, `fields_submitted`                                         |
| `surface.field_saved`     | A single field was saved on a surface | `surface_id`, `entity_id`, `field_key`                                                                |
| `surface.opened`          | A surface was opened by a patient     | `surface_id`, `entity_id`                                                                             |
| `surface.reshaped`        | A surface was reshaped                | `surface_id`, `original_surface_id`                                                                   |
| `surface.pending_review`  | A surface is pending review           | `surface_id`, `entity_id`, `source`, `form_template_id`, `review_required`                            |
| `surface.review_approved` | A surface review was approved         | `surface_id`                                                                                          |
| `surface.review_rejected` | A surface review was rejected         | `surface_id`, `reason`                                                                                |

### Encounter Events

| Event Type          | Description                     | Key Fields                          |
| ------------------- | ------------------------------- | ----------------------------------- |
| `encounter.updated` | An encounter entity was updated | `encounter_entity_id`, `session_id` |

### Narrative Events

| Event Type                   | Description                                  | Key Fields                                                                                   |
| ---------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `self_image.brief_generated` | A narrative brief was generated or refreshed | `target_entity_id`, `target_entity_type`, `event_id`, `version`, `confidence`, `event_count` |

### Review Events

| Event Type         | Description               | Key Fields                                               |
| ------------------ | ------------------------- | -------------------------------------------------------- |
| `review.submitted` | A review action was taken | `action`, `item_id`, `entity_id`, `entity_type`, `count` |

The `action` field is one of: `approve`, `reject`, `correct`, `batch_approve`, `batch_reject`.

### Simulation Events

| Event Type               | Description                    | Key Fields                                                                                       |
| ------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------ |
| `simulation.turn_stored` | A simulation turn was recorded | `service_id`, `run_id`, `session_id`, `turn_index`, `state_before`, `state_after`, `is_terminal` |

### Trigger Events

| Event Type          | Description                                  | Key Fields                             |
| ------------------- | -------------------------------------------- | -------------------------------------- |
| `trigger.fired`     | An automation trigger was activated          | `trigger_id`, `trigger_name`, `manual` |
| `trigger.completed` | An automation trigger completed successfully | `trigger_id`, `trigger_name`, `status` |
| `trigger.failed`    | An automation trigger failed                 | `trigger_id`, `trigger_name`, `status` |

### Operator Events

| Event Type                 | Description                          | Key Fields                                            |
| -------------------------- | ------------------------------------ | ----------------------------------------------------- |
| `operator.registered`      | An operator was registered           | `operator_id`, `timestamp`                            |
| `operator.status_changed`  | An operator's status changed         | `operator_id`, `status`                               |
| `operator.profile_updated` | An operator's profile was updated    | `operator_id`                                         |
| `operator.joined_call`     | An operator joined a call            | `call_sid`, `operator_id`, `mode`                     |
| `operator.left_call`       | An operator left a call              | `call_sid`, `operator_id`, `human_segment_turn_count` |
| `operator.mode_changed`    | An operator's mode changed on a call | `call_sid`, `operator_id`, `mode`                     |
| `operator.wrap_up`         | An operator entered wrap-up          | `call_sid`, `wrap_up_reason`                          |

Operator `status` is one of: `online`, `busy`, `offline`. Operator `mode` is one of: `listen`, `takeover`.

### Pipeline Events

| Event Type                | Description                    | Key Fields                                     |
| ------------------------- | ------------------------------ | ---------------------------------------------- |
| `pipeline.sync_completed` | A data pipeline sync completed | `data_source_id`, `event_count`, `duration_ms` |
| `pipeline.error`          | A data pipeline sync failed    | `data_source_id`, `error`                      |

### Integration Approval Events

| Event Type                      | Description                              | Key Fields                  |
| ------------------------------- | ---------------------------------------- | --------------------------- |
| `integration.approval_granted`  | A pending integration write was approved | `conversation_id`           |
| `integration.approval_rejected` | A pending integration write was rejected | `conversation_id`, `reason` |

### Workspace Membership Events

| Event Type                      | Description                         | Key Fields                           |
| ------------------------------- | ----------------------------------- | ------------------------------------ |
| `workspace.invitation_sent`     | A workspace invitation was sent     | `invitation_id`, `role`, `resent`    |
| `workspace.invitation_accepted` | A workspace invitation was accepted | `entity_id`, `role`                  |
| `workspace.member_added`        | A member was added to the workspace | `entity_id`, `role`                  |
| `workspace.member_role_updated` | A member's role changed             | `entity_id`, `previous_role`, `role` |

### Channel Email Events

Email delivery status events are published when email is sent through a use case channel, letting you track delivery outcomes in real time. They are emitted automatically when the platform receives delivery status updates from the email provider - no configuration is required beyond creating a use case with an email channel.

| Event Type                 | Description                      | Key Fields                                                                          |
| -------------------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
| `channel.email_delivered`  | Email successfully delivered     | `email_id`, `to_address`, `from_address`                                            |
| `channel.email_bounced`    | Email bounced                    | `email_id`, `to_address`, `from_address`, `bounce_type`, `bounce_subtype`           |
| `channel.email_complained` | Recipient filed a spam complaint | `email_id`, `to_address`, `from_address`                                            |
| `channel.email_rejected`   | Email rejected before delivery   | `email_id`, `to_address`, `from_address`                                            |
| `channel.email_delayed`    | Delivery delayed, retrying       | `email_id`, `to_address`, `from_address`                                            |
| `channel.email_opened`     | Recipient opened the email       | `email_id`, `to_address`                                                            |
| `channel.email_clicked`    | Recipient clicked a link         | `email_id`, `to_address`                                                            |
| `channel.email_received`   | An inbound email was received    | `inbound_email_id`, `from_address`, `to_address`, `subject`, `in_reply_to_email_id` |

### Channel Voicemail Events

| Event Type                 | Description                                | Key Fields                                         |
| -------------------------- | ------------------------------------------ | -------------------------------------------------- |
| `channel.voicemail_status` | A voicemail drop reached a terminal status | `voicemail_id`, `recipient_phone_number`, `status` |

Voicemail `status` is one of: `delivered`, `skipped`, `failed`, `not_delivered`.

## Discriminated Unions in the SDK

The OpenAPI specification includes typed schemas for all event types as a discriminated union on the `event_type` field. SDK clients generated from the spec (such as the TypeScript SDK) receive full type safety when handling events:

```typescript
// TypeScript SDK example - exhaustive event handling
switch (event.event_type) {
  case "call.started":
    console.log(`Call ${event.call_sid} started`);
    break;
  case "surface.created":
    console.log(`Surface ${event.surface_id} created for entity ${event.entity_id}`);
    break;
  // ... other event types
}
```

## Observer Events

A separate WebSocket stream delivers per-call observer events (transcripts, state transitions, tool calls, emotion analysis, latency timing) to clients monitoring an active voice session. Observer events use a `type` discriminator rather than `event_type`. The full catalog, field lists, and PHI annotations for observer events live on the [Observer Events](/developer-guide/platform-api/conversations/observer-events.md) page, which is the authoritative reference.

{% content-ref url="/pages/Qm4yWkfviMbMOVLEbCzJ" %}
[Observer Events](/developer-guide/platform-api/conversations/observer-events.md)
{% endcontent-ref %}

## PHI Annotations

The following workspace event fields are annotated as potentially containing PHI:

| Event                      | Field                        |
| -------------------------- | ---------------------------- |
| `call.started`             | `caller_id`                  |
| `surface.delivered`        | `channel_address`            |
| `channel.email_*`          | `to_address`                 |
| `channel.email_received`   | `from_address`, `to_address` |
| `channel.voicemail_status` | `recipient_phone_number`     |

PHI annotations for observer event fields are listed on the [Observer Events](/developer-guide/platform-api/conversations/observer-events.md#phi-annotations) page.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/conversations/sse-events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.