# Post-conversation

An Exchange records a conversation with an Assistant. Read its transcript, events, resources, and extracted data through the API, or use Hooks to trigger workflows after completion.

## Overview

At call startup, the system registers an Exchange with `status: "inProgress"`. After the conversation ends, it updates the Exchange to `status: "completed"` with its messages, events, duration, and any recording or extracted data. Entity changes can trigger automated workflows.

:::info{title="Note"}

Integration API keys can query and read Exchanges but cannot create, update, or delete them. If registration at call startup fails, the system attempts to create the completed record at the end.

:::

## The Exchange entity

A running conversation has `status: "inProgress"`. Final conversation data becomes available when the Exchange has `status: "completed"`.

### Field descriptions

| Field            | Type     | Description                                                                  |
| ---------------- | -------- | ---------------------------------------------------------------------------- |
| `id`             | `string` | Unique identifier (UUID) for the Exchange               |
| `status`         | `string` | Conversation status: `"inProgress"` or `"completed"`                                    |
| `type`           | `string` | Conversation type (e.g., `"voice"`)                                          |
| `messages`       | `array`  | Conversation messages - see [Messages](/docs/messages)                      |
| `events`         | `array`  | Timeline of conversation events - see [Events](/docs/events)                   |
| `resources`      | `array`  | Configuration metadata and media references - see [Resources](/docs/resources) |
| `data`           | `object` or `null` | Structured data extracted after the conversation                     |
| `projectId`      | `string` | Reference to the parent Project                                              |
| `organizationId` | `string` | Reference to the parent Organisation                                         |
| `createdAt`      | `Date`   | Timestamp when the Exchange was created                 |
| `updatedAt`      | `Date`   | Timestamp of the last update                                                 |

## Exchange example

This response excerpt records a technical support call:

```json
{
  "id": "72770d5a-5b25-4118-ba88-786972b29de7",
  "status": "completed",
  "type": "voice",
  "messages": [
    {
      "message": "Hi, welcome to the technical support, how may I assist you today ?",
      "from": "assistant",
      "time": "2025-12-15T16:04:51.002484"
    },
    {
      "message": "Hi, I'm having technical difficulties connecting to your service this morning and I'd like to report a bug.",
      "from": "user",
      "time": "2025-12-15T16:04:58.229180"
    },
    {
      "message": "I'm sorry to hear that you're experiencing issues. Could you please describe the problem in more detail? What exactly happens when you try to connect?",
      "from": "assistant",
      "time": "2025-12-15T16:05:06.000673"
    }
  ],
  "events": [
    {
      "type": "session_start",
      "time": "2025-12-15T16:04:46.420863"
    },
    {
      "type": "tool_call",
      "time": "2025-12-15T16:05:29.074603",
      "data": {
        "toolName": "getSystemStatus",
        "arguments": "{}",
        "isMcpTool": true
      }
    }
  ],
  "resources": [
    {
      "key": "assistant_id",
      "value": "efc242e6-4aab-4cc5-9a7d-ce7fb0cf0188",
      "type": "string"
    }
  ],
  "data": null,
  "projectId": "4111b855-ca91-40f0-897f-93292a09da58",
  "organizationId": "281d82f5-a30d-44be-8e66-c35ff2cef718",
  "createdAt": "2025-12-15T16:04:46.420Z",
  "updatedAt": "2025-12-15T16:05:55.095Z"
}
```

## Post-conversation processing with the Hook service

The Hook Service triggers Processes registered for `conversational.exchange` and the matching entity event. A normal call produces a `CREATE` event at startup and an `UPDATE` event on completion. For post-conversation processing, register `UPDATE` and have the Process check that `status` is `"completed"` before running its actions.

### How it works

<Mermaid chart={`flowchart LR
    A[Conversation ends] --> B[Exchange updated to completed]
    B --> C{Hooks registered?}
    C -->|Yes| D[Process 1]
    C -->|Yes| E[Process 2]
    C -->|Yes| F[Process N...]
    C -->|No| G[Done]
    D --> G
    E --> G
    F --> G`} />

1. The system updates the Exchange with final conversation data.
2. The Hook Service finds Hooks registered for `conversational.exchange` and the `UPDATE` event.
3. Matching Processes run in parallel with the Exchange data as context. Add a [Rule](/docs/rules) to each Process that checks for `status: "completed"` before running further steps.

### The Process entity

A Process contains the workflow steps the Hook Service executes:

| Field            | Type     | Description                              |
| ---------------- | -------- | ---------------------------------------- |
| `id`             | `string` | Unique identifier (UUID) for the Process |
| `name`           | `string` | Human-readable name for the Process      |
| `description`    | `string` | Description of what the Process does     |
| `steps`          | `array`  | Array of workflow steps to execute       |
| `projectId`      | `string` | Reference to the parent Project          |
| `organizationId` | `string` | Reference to the parent Organisation     |

### Registering a Process for post-conversation processing

To trigger a Process when a conversation ends, create a Hook that links the Process to the `conversational.exchange` entity and the `UPDATE` event:

```http
POST /data_next/automation/hooks/
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "name": "Post-Conversation Analysis",
  "description": "Analyse completed conversations for quality metrics",
  "entity": "conversational.exchange",
  "events": ["UPDATE"],
  "processId": "<your-process-id>",
  "projectId": "<your-project-id>"
}
```

When the completed Exchange is saved, the Hook Service executes the linked Process with the Exchange data as context. To also handle the fallback where startup registration failed and the completed record is created at the end, subscribe to both `CREATE` and `UPDATE` and keep the completed-status check in the Process.

See [Workflows](/docs/overview-2) for the available step types and execution instructions.

## Reading Exchanges via API

Query the Exchange API to retrieve conversation history, analyse patterns, or export data.

### Common query patterns

**Get all Exchanges for a Project:**

```
GET /data_next/conversational/exchanges?where={"projectId":"<your-project-id>"}
```

**Get Exchanges by status:**

```
GET /data_next/conversational/exchanges?where={"status":"completed"}
```

**Get a specific Exchange by ID:**

```
GET /data_next/conversational/exchanges/<exchange-id>
```

## What's next

- [Messages](/docs/messages)
- [Events](/docs/events)
- [Resources](/docs/resources)
