## Conversations

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

All requests require an `Authorization: Bearer YOUR_GUAVA_API_KEY` header. See the [API Overview](/docs/api-overview) for details.

### List conversations

```
GET /v1/conversations
```

List your organization's conversations, newest first. Use the filters below to narrow results — for example, to pull every call to or from a given phone number, with each call's duration, to build a usage or billing report.

#### Parameters

| Name           | Type    | Required | Description                                                                               |
|----------------|---------|----------|-------------------------------------------------------------------------------------------|
| `from_number`  | string  | No       | Only return calls placed from this number. E.164 format (e.g. `+15551234567`).         |
| `to_number`    | string  | No       | Only return calls placed to this number. E.164 format.                                 |
| `direction`    | string  | No       | Only return calls in this direction: "inbound" or "outbound" (from the perspective of your agent). Use "all" or omit for both. |
| `date_from`    | string  | No       | Only return calls at or after this time (ISO 8601, e.g. `2026-06-01T00:00:00Z`).      |
| `date_to`      | string  | No       | Only return calls at or before this time (ISO 8601).                                   |
| `campaign_id`  | string  | No       | Only return calls placed by this outbound campaign.                                     |
| `limit`        | integer | No       | Maximum number of conversations to return, between 1 and 100. Defaults to 50.         |
| `after`        | string  | No       | Pagination cursor. Pass the `next_cursor` from the previous response to fetch the next page. |

#### Response

A JSON object with the following fields:

| Field            | Type                     | Description                                                                                             |
|------------------|--------------------------|---------------------------------------------------------------------------------------------------------|
| `conversations`  | array                    | The matching conversations, newest first. Each is the same object returned by [Get conversation details](#get-conversation-details). |
| `next_cursor`    | string (nullable)        | Pass as `after` to fetch the next page. `null` when there are no more results.                        |
| `has_more`       | boolean                  | `true` if more conversations match than were returned in this response.                                 |

Each conversation includes the call's `duration_sec`, so you can total call time without fetching each conversation individually.

#### Pagination

Conversations are returned newest first. When `has_more` is `true`, request the next page by calling again with `after` set to the `next_cursor` from the previous response. Keep paging until `has_more` is `false` to retrieve the full set.

#### Errors

| Status | Description                                                       |
|--------|-------------------------------------------------------------------|
| 400    | Invalid `limit`, `after` cursor, `campaign_id`, or date value   |
| 401    | Invalid authentication                                             |
| 422    | `from_number` or `to_number` is not a valid E.164 number       |

#### Example

```bash
curl -G https://api.goguava.ai/v1/conversations \
  -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  --data-urlencode 'from_number=+15551234567' \
  --data-urlencode 'date_from=2026-06-01T00:00:00Z'
```

Sample response:

```json
{
  "conversations": [
    {
      "id": "6064ab9663dc4eb0",
      "call_id": "6064ab9663dc4eb0",
      "ts": "2026-06-09T00:12:04.518000+00:00",
      "direction": "outbound",
      "from_number": "+15551234567",
      "to_number": "+15551230001",
      "duration_sec": 142,
      "campaign_id": null,
      "termination_reason": "user-hangup"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```
The `+` in a phone number must be URL-encoded as `%2B` in query strings. The `curl -G --data-urlencode` form above handles this for you.

### 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                               |
|-----------------|--------------------------|-------------------------------------------|
| `id`            | string                   | Unique ID of the conversation            |
| `call_id`       | string                   | ID of the call                           |
| `ts`            | string                   | Date of the call in ISO 8601 format     |
| `direction`     | string                   | "inbound" or "outbound"              |
| `from_number`   | string                   | Phone number that initiated the call     |
| `to_number`     | string                   | Phone number that received the call      |
| `duration_sec`  | integer (nullable)       | How long the call lasted in seconds. `null` until the call completes. |
| `campaign_id`   | string (nullable)        | Outbound campaign that initiated this call, if applicable |
| `termination_reason` | string (nullable)   | How the call ended (e.g. "user-hangup"), if known |

#### 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

#### 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

#### 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

#### Response

None (empty body).

#### Errors

#### Example

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