# Chat Transcript

Retrieve the full conversation transcript for a chat session.

---

Pull the full conversation transcript for any chat session in your AVCodex agent. Useful for logging conversations, syncing chat data to your CRM or PM tool, or building analytics on top of your AVCodex agent.

> **Note:** This endpoint uses the same API key as the Chat Completions API. Find your key in the **Share** tab of your agent.

## Endpoint

```
GET https://app.avcodex.com/api/v1/chat/transcript/{sessionId}
```

## Authentication

Include your agent's API key as a Bearer token:

```bash
Authorization: Bearer YOUR_API_KEY
```

This is the same API key used for the [Chat Completions API](/docs/api/reference). Both your test and live API keys are accepted.

## Path parameters

| Parameter   | Type           | Required | Description                          |
|-------------|----------------|----------|--------------------------------------|
| `sessionId` | string (UUID)  | Yes      | The chat session ID to retrieve.     |

## Example request

```bash
curl https://app.avcodex.com/api/v1/chat/transcript/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response

### Success (200)

```json
{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Boardroom 4 commissioning Q&A",
  "messageCount": 6,
  "userMessageCount": 3,
  "botMessageCount": 3,
  "messages": [
    {
      "role": "user",
      "content": "Hi, I have a question about the Q-SYS Core firmware in Boardroom 4.",
      "timestamp": "2026-01-15T10:30:00.000Z"
    },
    {
      "role": "assistant",
      "content": "Happy to help. What firmware version is currently loaded?",
      "timestamp": "2026-01-15T10:30:02.000Z"
    }
  ],
  "createdAt": "2026-01-15T10:29:55.000Z",
  "updatedAt": "2026-01-15T10:35:12.000Z"
}
```

### Response fields

| Field                | Type    | Description                                 |
|----------------------|---------|---------------------------------------------|
| `sessionId`          | string  | The chat session ID.                        |
| `title`              | string  | Auto-generated session title (may be null). |
| `messageCount`       | number  | Total number of messages.                   |
| `userMessageCount`   | number  | Number of user messages.                    |
| `botMessageCount`    | number  | Number of assistant messages.               |
| `messages`           | array   | Ordered list of messages.                   |
| `messages[].role`    | string  | `"user"` or `"assistant"`.                  |
| `messages[].content` | string  | The message text.                           |
| `messages[].timestamp` | string | ISO 8601 timestamp.                         |
| `createdAt`          | string  | When the session was created.               |
| `updatedAt`          | string  | When the session was last updated.          |

## Error responses

### Authentication failed (401)

```json
{ "error": "Missing API key" }
```
No `Authorization` header provided.

```json
{ "error": "Invalid API key" }
```
The API key is incorrect or does not belong to any agent.

### Session not found (404)

```json
{ "error": "Session not found" }
```
The session ID does not exist or does not belong to your agent. For security, the same error is returned in both cases.

### Server error (500)

```json
{ "error": "Failed to fetch session" }
```

## Common use cases

### Webhook integration

If your AVCodex agent uses a [Custom Action](/docs/custom-actions/overview) to send data to a webhook, include the session ID in the webhook payload and fetch the full transcript from your backend:

```python
# Your webhook handler receives the session ID
session_id = webhook_payload["chatSessionId"]

# Fetch the full transcript
import requests

response = requests.get(
    f"https://app.avcodex.com/api/v1/chat/transcript/{session_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
transcript = response.json()

# Store or process the transcript
for message in transcript["messages"]:
    print(f"{message['role']}: {message['content']}")
```

### CRM sync

After a conversation ends, fetch the transcript and attach it to a contact record in your CRM (HubSpot, Salesforce, ConnectWise):

```javascript
const response = await fetch(
  `https://app.avcodex.com/api/v1/chat/transcript/${sessionId}`,
  {
    headers: { Authorization: `Bearer ${process.env.AVCODEX_API_KEY}` },
  }
);

const { messages, messageCount } = await response.json();

// Format for a CRM note
const note = messages
  .map((m) => `${m.role === "user" ? "Tech" : "Agent"}: ${m.content}`)
  .join("\n\n");
```

## Security

- Each API key is scoped to a single agent. You can only retrieve transcripts for sessions that belong to your agent.
- Attempting to access a session from a different agent returns a `404` (not `403`) to avoid leaking information about session existence.
- Both test and live API keys are accepted.

*AVCodex · Your AV expertise. Amplified by AI.*