import { Callout } from '../views/docs/prose';

## Conversations

These endpoints let you retrieve, inspect, and delete conversation data for completed calls.

<Callout>
  All requests require an `Authorization: Bearer YOUR_GUAVA_API_KEY` header. See the <a href="/docs/api-overview">API Overview</a> for details.
</Callout>

### Get conversation details

```
GET /v1/conversations/{call_id}
```

Retrieve metadata about a single conversation.

#### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `call_id` | string | Yes | ID of the call |

#### Response

A JSON object with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `call_id` | string | ID of the call |
| `ts` | string | Date of the call in ISO 8601 format |
| `direction` | string | `"inbound"` or `"outbound"` (from the perspective of your agent) |
| `from_number` | string | Phone number that initiated the call |
| `to_number` | string | Phone number that received the call |
| `duration_sec` | integer | How long the call lasted in seconds |
| `campaign_id` | string (nullable) | Outbound campaign that initiated this call, if applicable |

#### Errors

| Status | Description |
|--------|-------------|
| 401 | Invalid authentication |
| 404 | The call with this ID does not exist |

#### Example

```bash
curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://api.goguava.ai/v1/conversations/6064ab9663dc4eb0
```

---

### Get conversation transcript

```
GET /v1/conversations/{call_id}/transcript
```

Download the transcript for a conversation as a list of turns.

#### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `call_id` | string | Yes | ID of the call |

#### Response

A JSON array of turn objects. Each turn has:

| Field | Type | Description |
|-------|------|-------------|
| `speaker` | string | `"HUMAN"` or `"AGENT"` |
| `text` | string | What was said by the speaker |
| `offset_ms` | integer | Milliseconds into the call when this turn began |

#### Errors

| Status | Description |
|--------|-------------|
| 401 | Invalid authentication |
| 404 | The call with this ID does not exist |

#### Example

```bash
curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://api.goguava.ai/v1/conversations/6064ab9663dc4eb0/transcript
```

---

### Get conversation recording

```
GET /v1/conversations/{call_id}/recording
```

Download the audio recording for a conversation in WAV format.

#### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `call_id` | string | Yes | ID of the call |

#### Response

WAV audio file.

#### Errors

| Status | Description |
|--------|-------------|
| 401 | Invalid authentication |
| 404 | The call with this ID does not exist |

#### Example

```bash
curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  -o recording.wav \
  https://api.goguava.ai/v1/conversations/6064ab9663dc4eb0/recording
```

---

### Delete a conversation

```
DELETE /v1/conversations/{call_id}
```

Permanently delete a conversation and its associated data.

#### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `call_id` | string | Yes | ID of the call |

#### Response

None (empty body).

#### Errors

| Status | Description |
|--------|-------------|
| 401 | Invalid authentication |
| 404 | The call with this ID does not exist |

#### Example

```bash
curl -X DELETE -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://api.goguava.ai/v1/conversations/6064ab9663dc4eb0
```