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

Days Back: If not provided, retrieves all conversations. Use this to limit results to recent conversations only.

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

curl --request GET \
  'https://api.vambe.ai/api/public/contact/df980fc8-b6db-4820-bf22-2969482d106d/conversations' \
  --header 'x-api-key: your_api_key_here'

Get Last 7 Days of Conversations

curl --request GET \
  'https://api.vambe.ai/api/public/contact/df980fc8-b6db-4820-bf22-2969482d106d/conversations?daysBack=7' \
  --header 'x-api-key: your_api_key_here'

Example Response

[
  {
    "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

const displayConversations = async (contactId) => {
  const response = await fetch(
    `https://api.vambe.ai/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

const getRecentConversations = async (contactId, days = 30) => {
  const response = await fetch(
    `https://api.vambe.ai/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

const analyzeConversations = async (contactId) => {
  const response = await fetch(
    `https://api.vambe.ai/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

const exportConversationHistory = async (contactId) => {
  const response = await fetch(
    `https://api.vambe.ai/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)

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:

Time Gaps: Messages separated by long periods are in different conversations
Context Changes: Stage changes or significant topic shifts create new conversations
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

GET /api/public/contact/v2//messages - Get messages with pagination (recommended for large datasets)
GET /api/public/contact//info - Get contact info
POST /api/public/contact//update-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

Headers

x-api-key

string

required

API key required to authorize the request

Path Parameters

aiContactId

string

required

ID of the AI contact

Query Parameters

daysBack

number

Number of days back to retrieve conversations

Response

Conversations retrieved successfully.

Contact Management

Tags & Labels

Conversations & Messages

Tickets & Support

Team Management

Deprecated

Retrieve conversations by AI contact

Overview

Use Cases

Authentication

Path Parameters

Query Parameters

Response Structure

Conversation Object

Message Object

Example Request

Get All Conversations

Get Last 7 Days of Conversations

Example Response

Common Use Cases

1. Display Chat Interface

2. Get Recent Conversations Only

3. Analyze Conversation Patterns

4. Export Conversation History

Key Features

Agent vs AI Detection

Message Types

How Conversations Are Grouped

When to Use This Endpoint

Error Responses

Performance Considerations

Comparison with Messages Endpoint

Headers

Path Parameters

Query Parameters

Response

Contact Management

Tags & Labels

Conversations & Messages

Tickets & Support

Team Management

Deprecated

​Overview

​Use Cases

​Authentication

​Path Parameters

​Query Parameters

​Response Structure

​Conversation Object

​Message Object

​Example Request

​Get All Conversations

​Get Last 7 Days of Conversations

​Example Response

​Common Use Cases

​1. Display Chat Interface

​2. Get Recent Conversations Only

​3. Analyze Conversation Patterns

​4. Export Conversation History

​Key Features

​Agent vs AI Detection

​Message Types

​How Conversations Are Grouped

​When to Use This Endpoint

​Error Responses

​Performance Considerations

​Related Endpoints

​Comparison with Messages Endpoint

Headers

Path Parameters

Query Parameters

Response

Overview

Use Cases

Authentication

Path Parameters

Query Parameters

Response Structure

Conversation Object

Message Object

Example Request

Get All Conversations

Get Last 7 Days of Conversations

Example Response

Common Use Cases

1. Display Chat Interface

2. Get Recent Conversations Only

3. Analyze Conversation Patterns

4. Export Conversation History

Key Features

Agent vs AI Detection

Message Types

How Conversations Are Grouped

When to Use This Endpoint

Error Responses

Performance Considerations

Related Endpoints

Comparison with Messages Endpoint