> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vambe.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve conversations by AI contact

## Overview

Retrieve conversations with a contact, automatically grouped into conversation threads. Messages are intelligently organized by time gaps and context, making it easy to understand the flow of communication.

This endpoint is ideal when you want to display conversation history in a chat-like interface with messages grouped into distinct conversation sessions.

## Use Cases

* **Chat Interface**: Display conversation history in a threaded chat UI
* **Conversation Analysis**: Analyze conversation patterns and engagement
* **Context Building**: Get conversation context for AI or agent responses
* **Support Ticket View**: Show conversation threads for support tickets
* **Activity Timeline**: Display communication timeline with grouped sessions
* **Export Conversations**: Export conversation history for records

## Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

```
x-api-key: your_api_key_here
```

## Path Parameters

| Parameter     | Type          | Required | Description                      |
| ------------- | ------------- | -------- | -------------------------------- |
| `aiContactId` | string (UUID) | Yes      | Unique identifier of the contact |

## Query Parameters

| Parameter  | Type   | Required | Description                                   |
| ---------- | ------ | -------- | --------------------------------------------- |
| `daysBack` | number | No       | Number of days back to retrieve conversations |

<Note>
  **Days Back**: If not provided, retrieves all conversations. Use this to limit
  results to recent conversations only.
</Note>

## Response Structure

Returns an array of conversation objects. Each conversation represents a grouped thread of messages:

### Conversation Object

| Field                  | Type          | Description                                          |
| ---------------------- | ------------- | ---------------------------------------------------- |
| `conversation_id`      | number        | Unique numeric identifier for the conversation       |
| `conversation_date`    | string (ISO)  | Timestamp when the conversation started              |
| `stage_id`             | string (UUID) | Pipeline stage during this conversation              |
| `conversation_channel` | string (UUID) | Channel/phone identifier                             |
| `platform`             | string        | Communication channel (whatsapp, web-whatsapp, etc.) |
| `phone_number_channel` | string        | Your WhatsApp phone number (with +)                  |
| `conversation_detail`  | array         | Array of message objects in this conversation        |

### Message Object

Each message in the `conversation_detail` array contains:

| Field                 | Type           | Description                                          |
| --------------------- | -------------- | ---------------------------------------------------- |
| `id`                  | string         | Unique message identifier (numeric string)           |
| `body`                | string         | Message content/text                                 |
| `created_at`          | string (ISO)   | Message timestamp                                    |
| `direction`           | string         | "inbound" (from contact) or "outbound" (to contact)  |
| `platform_contact_id` | string (UUID)  | Platform-specific contact identifier                 |
| `status`              | string         | Message status (read, sent, delivered)               |
| `type`                | string         | Message type (text, image, video, reaction, etc.)    |
| `user_id`             | string \| null | Agent who sent the message (if outbound by human)    |
| `assistant_id`        | string \| null | AI assistant that sent the message (if AI-generated) |

## Example Request

### Get All Conversations

```bash theme={null}
curl --request GET \
  'https://api.vambe.me/api/public/contact/df980fc8-b6db-4820-bf22-2969482d106d/conversations' \
  --header 'x-api-key: your_api_key_here'
```

### Get Last 7 Days of Conversations

```bash theme={null}
curl --request GET \
  'https://api.vambe.me/api/public/contact/df980fc8-b6db-4820-bf22-2969482d106d/conversations?daysBack=7' \
  --header 'x-api-key: your_api_key_here'
```

## Example Response

```json theme={null}
[
  {
    "conversation_id": 1,
    "conversation_date": "2024-09-30T10:00:00.000Z",
    "stage_id": "550e8400-e29b-41d4-a716-446655440000",
    "conversation_channel": "ccfe327c-e5df-4063-b99f-9795033b0be3",
    "platform": "web-whatsapp",
    "phone_number_channel": "+56999315943",
    "conversation_detail": [
      {
        "id": "46964423",
        "created_at": "2024-09-30T10:02:00.000Z",
        "body": "Es el #12345",
        "direction": "inbound",
        "platform_contact_id": "2b52e5a6-f290-4678-9138-882c39d94b92",
        "status": "read",
        "type": "text",
        "user_id": null,
        "assistant_id": null
      },
      {
        "id": "46964282",
        "created_at": "2024-09-30T10:01:30.000Z",
        "body": "Por supuesto! ¿Cuál es tu número de pedido?",
        "direction": "outbound",
        "platform_contact_id": "2b52e5a6-f290-4678-9138-882c39d94b92",
        "status": "sent",
        "type": "text",
        "user_id": "c6382bff-da3a-44c6-90b7-65038be5725c",
        "assistant_id": null
      },
      {
        "id": "46964114",
        "created_at": "2024-09-30T10:00:00.000Z",
        "body": "Hola! Necesito ayuda con mi pedido",
        "direction": "inbound",
        "platform_contact_id": "2b52e5a6-f290-4678-9138-882c39d94b92",
        "status": "read",
        "type": "text",
        "user_id": null,
        "assistant_id": null
      }
    ]
  },
  {
    "conversation_id": 2,
    "conversation_date": "2024-09-29T15:30:00.000Z",
    "stage_id": "660e8400-e29b-41d4-a716-446655440001",
    "conversation_channel": "ccfe327c-e5df-4063-b99f-9795033b0be3",
    "platform": "whatsapp",
    "phone_number_channel": "+56999315943",
    "conversation_detail": [
      {
        "id": "46950000",
        "created_at": "2024-09-29T15:30:00.000Z",
        "body": "Gracias por la ayuda!",
        "direction": "inbound",
        "platform_contact_id": "2b52e5a6-f290-4678-9138-882c39d94b92",
        "status": "read",
        "type": "text",
        "user_id": null,
        "assistant_id": null
      }
    ]
  }
]
```

## Common Use Cases

### 1. Display Chat Interface

```javascript theme={null}
const displayConversations = async (contactId) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/contact/${contactId}/conversations`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const conversations = await response.json();

  conversations.forEach((conv) => {
    console.log(`\n--- Conversation ${conv.conversation_id} ---`);
    console.log(
      `Started: ${new Date(conv.conversation_date).toLocaleString()}`,
    );
    console.log(`Messages: ${conv.conversation_detail.length}`);
    console.log(`Platform: ${conv.platform}`);

    conv.conversation_detail.forEach((msg) => {
      const label = msg.direction === 'inbound' ? 'Customer' : 'Agent/AI';
      const timestamp = new Date(msg.created_at).toLocaleTimeString();
      const sender = msg.user_id
        ? 'Agent'
        : msg.assistant_id
          ? 'AI'
          : 'Customer';
      console.log(`[${timestamp}] ${sender}: ${msg.body}`);
    });
  });

  return conversations;
};
```

### 2. Get Recent Conversations Only

```javascript theme={null}
const getRecentConversations = async (contactId, days = 30) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/contact/${contactId}/conversations?daysBack=${days}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const conversations = await response.json();
  console.log(
    `Found ${conversations.length} conversations in last ${days} days`,
  );

  return conversations;
};
```

### 3. Analyze Conversation Patterns

```javascript theme={null}
const analyzeConversations = async (contactId) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/contact/${contactId}/conversations`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const conversations = await response.json();

  const stats = {
    totalConversations: conversations.length,
    totalMessages: conversations.reduce(
      (sum, conv) => sum + conv.conversation_detail.length,
      0,
    ),
    averageMessagesPerConversation:
      conversations.reduce(
        (sum, conv) => sum + conv.conversation_detail.length,
        0,
      ) / conversations.length,
    mostRecentConversation: conversations[0]?.conversation_date,
    messagesByAgent: conversations.reduce((sum, conv) => {
      return (
        sum + conv.conversation_detail.filter((m) => m.user_id !== null).length
      );
    }, 0),
    messagesByAI: conversations.reduce((sum, conv) => {
      return (
        sum +
        conv.conversation_detail.filter((m) => m.assistant_id !== null).length
      );
    }, 0),
    messagesByCustomer: conversations.reduce((sum, conv) => {
      return (
        sum +
        conv.conversation_detail.filter((m) => m.direction === 'inbound').length
      );
    }, 0),
  };

  console.log('Conversation Analysis:', stats);
  return stats;
};
```

### 4. Export Conversation History

```javascript theme={null}
const exportConversationHistory = async (contactId) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/contact/${contactId}/conversations`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const conversations = await response.json();

  // Convert to readable format
  const transcript = conversations
    .map((conv) => {
      const header = `\n===== Conversation ${conv.conversation_id} =====\nDate: ${new Date(conv.conversation_date).toLocaleString()}\nPlatform: ${conv.platform}\nMessages: ${conv.conversation_detail.length}\n\n`;

      const messages = conv.conversation_detail
        .reverse() // Most recent last for readability
        .map((msg) => {
          const timestamp = new Date(msg.created_at).toLocaleTimeString();
          let sender = 'Customer';
          if (msg.direction === 'outbound') {
            sender = msg.user_id
              ? 'Agent'
              : msg.assistant_id
                ? 'AI Assistant'
                : 'System';
          }
          return `[${timestamp}] ${sender}: ${msg.body}`;
        })
        .join('\n');

      return header + messages;
    })
    .join('\n\n');

  return transcript;
};
```

## Key Features

### Agent vs AI Detection

This endpoint provides visibility into who sent each outbound message:

* **`user_id` present**: Message was sent by a human agent
* **`assistant_id` present**: Message was sent by AI assistant
* **Both null**: Message sent by customer (inbound)

```javascript theme={null}
conv.conversation_detail.forEach((msg) => {
  if (msg.direction === 'outbound') {
    if (msg.user_id) {
      console.log('Sent by human agent');
    } else if (msg.assistant_id) {
      console.log('Sent by AI assistant');
    } else {
      console.log('System message');
    }
  }
});
```

### Message Types

The endpoint supports various message types:

* **`text`**: Regular text messages
* **`image`**: Image messages
* **`video`**: Video messages
* **`audio`**: Audio/voice messages
* **`reaction`**: Emoji reactions to messages
* **`document`**: File/document attachments

## How Conversations Are Grouped

Messages are automatically grouped into conversations based on:

1. **Time Gaps**: Messages separated by long periods are in different conversations
2. **Context Changes**: Stage changes or significant topic shifts create new conversations
3. **Chronological Order**: Conversations are ordered by most recent first

Each conversation has a unique `conversation_id` (numeric) that you can use for reference.

## When to Use This Endpoint

**✅ Use `/conversations` when**:

* Building a chat interface with conversation threads
* You want messages automatically grouped
* Displaying conversation history to users
* Analyzing conversation patterns
* Exporting readable conversation transcripts

**❌ Don't use when**:

* You need all messages in a flat list → Use `/v2/{aiContactId}/messages`
* You need pagination for large message sets → Use `/v2/{aiContactId}/messages`
* You want to process messages sequentially → Use `/v2/{aiContactId}/messages`

## Error Responses

| Status Code | Description                                  |
| ----------- | -------------------------------------------- |
| 401         | Unauthorized - Invalid or missing API key    |
| 404         | Not Found - Contact not found                |
| 500         | Internal Server Error - Something went wrong |

## Performance Considerations

* **All Messages**: Without `daysBack`, returns all conversations (can be large)
* **Use daysBack**: For better performance, limit to recent conversations
* **No Pagination**: All matching conversations returned at once
* **Grouped Data**: Response is larger than flat message list due to grouping

## Related Endpoints

* [GET /api/public/contact/v2/{aiContactId}/messages](/reference/contact/get-messages-paginated) - Get messages with pagination (recommended for large datasets)
* [GET /api/public/contact/{aiContactId}/info](/reference/contact/get-info-of-an-ai-contact) - Get contact info
* [POST /api/public/contact/{aiContactId}/update-metadata](/reference/contact/update-contact-metadata) - Update contact metadata

## Comparison with Messages Endpoint

| Feature                  | Conversations (This)                         | Messages v2                         |
| ------------------------ | -------------------------------------------- | ----------------------------------- |
| **Structure**            | Grouped: `conversation_detail` arrays        | Flat list of messages               |
| **Grouping Logic**       | Auto-grouped by time gaps & context          | No grouping                         |
| **Pagination**           | No pagination                                | Required (`page` parameter)         |
| **Time Filtering**       | `daysBack` parameter                         | Via page iteration                  |
| **Agent/AI Detection**   | ✅ `user_id` & `assistant_id` fields          | Limited info                        |
| **Conversation Context** | ✅ `conversation_id`, `stage_id` per thread   | No conversation grouping            |
| **Response Size**        | Larger (nested structure)                    | Smaller (flat structure)            |
| **Best For**             | Chat UI, conversation threads                | Bulk processing, exports, analytics |
| **Field Names**          | `conversation_detail`, `direction` lowercase | Different structure                 |
| **Message Order**        | Within conversations                         | Global chronological                |


## OpenAPI

````yaml get /api/public/contact/{aiContactId}/conversations
openapi: 3.0.0
info:
  title: Vambe AI API
  description: Vambe AI documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.vambe.me
    description: Production Server
security: []
tags:
  - name: Vambe AI
    description: ''
paths:
  /api/public/contact/{aiContactId}/conversations:
    get:
      tags:
        - Contact
      summary: Retrieve conversations by AI contact
      operationId: PublicAiContactController_getConversations
      parameters:
        - name: x-api-key
          in: header
          description: API key required to authorize the request
          required: true
          schema:
            type: string
        - name: aiContactId
          required: true
          in: path
          description: ID of the AI contact
          schema:
            type: string
        - name: daysBack
          required: false
          in: query
          description: Number of days back to retrieve conversations
          schema:
            type: number
      responses:
        '200':
          description: Conversations retrieved successfully.
        '404':
          description: AI contact not found.

````