## 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](https://goguava.ai/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](https://goguava.ai/docs/conversations-api#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

```
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:

```
{
  "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 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 (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

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

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

#### Example

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

#### Example

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