> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hollr.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hollr.ai/_mcp/server.

# Conversations

Every call placed through HollrAI can produce a conversation record. Conversations are the API surface for reading call outcomes and the data generated from the interaction.

Typical uses include retrieving transcripts, reading AI-generated summaries, checking sentiment, accessing recording information, and correlating a call with your own identifiers.

## The conversation object

| Field                     | Type       | Description                                      |
| ------------------------- | ---------- | ------------------------------------------------ |
| `id`                      | `uuid`     | Unique identifier for the conversation.          |
| `campaignId`              | `uuid`     | Campaign the call was placed under.              |
| `callSid`                 | `string`   | Telephony provider identifier for the call.      |
| `streamSid`               | `string`   | Identifier for the underlying audio stream.      |
| `fromNumber` / `toNumber` | `string`   | Phone numbers on either end of the call.         |
| `direction`               | `string`   | `inbound` or `outbound`.                         |
| `status`                  | `string`   | Current status of the call.                      |
| `duration`                | `integer`  | Call length in seconds.                          |
| `aiSummary`               | `string`   | AI-generated summary of the conversation.        |
| `userSentiment`           | `string`   | AI-inferred sentiment of the caller.             |
| `recordingUrl`            | `string`   | Recording URL, when available.                   |
| `messages`                | `object[]` | Turn-by-turn conversation data.                  |
| `tag`                     | `string`   | Optional label associated with the conversation. |
| `timesCalled`             | `integer`  | Number of times the contact has been called.     |
| `source`                  | `string`   | Source of the call, when tracked.                |

## List conversations

#### List all conversations

Supports pagination and filters such as status, direction, tag, date range, and sorting.

```bash
curl "https://api.hollr.ai/v1/conversation/conversations?limit=20&direction=outbound" \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

#### List conversations for a campaign

The campaign-specific endpoint uses `POST` and accepts the campaign ID in the request body.

```bash
curl -X POST "https://api.hollr.ai/v1/conversation/conversations/campaign" \
  -H "hollr-api-key: $HOLLR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "CAMPAIGN_ID"
  }'
```

#### Get a single conversation

```bash
curl https://api.hollr.ai/v1/conversation/conversation/CONVERSATION_ID \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

#### Get a conversation by call SID

Useful when your system already has the telephony provider's call identifier.

```bash
curl https://api.hollr.ai/v1/conversation/conversation/call/CALL_SID \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

## Update or delete a conversation

Conversation updates are partial. For example:

```bash
curl -X PUT https://api.hollr.ai/v1/conversation/conversation/CONVERSATION_ID \
  -H "hollr-api-key: $HOLLR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "confirmed",
    "userSentiment": "positive"
  }'
```

Delete a conversation with:

```bash
curl -X DELETE https://api.hollr.ai/v1/conversation/conversation/CONVERSATION_ID \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

## Pagination

List endpoints return a `pagination` object alongside results:

```json
{
  "page": 1,
  "limit": 50,
  "totalCount": 128,
  "totalPages": 3
}
```

Pass `page` and `limit` to move through additional pages.