Get contacts by days

Overview

Retrieve contacts that had their last message within a specified number of days. This endpoint works across all communication channels (WhatsApp, Instagram, Web Chat, SMS, etc.) providing a unified view of recent contact activity. Perfect for identifying active contacts, tracking engagement, and filtering contacts by recency across your entire customer base.

Use Cases

Active Contacts Dashboard: Show contacts who messaged in the last 7, 30, or 90 days
Engagement Metrics: Track how many contacts are actively engaging
Re-engagement Campaigns: Find contacts who haven’t messaged recently
Activity Reports: Generate reports of contact activity over time
Cross-Channel Analytics: See all active contacts regardless of channel
CRM Sync: Export recently active contacts to external systems

Authentication

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

x-api-key: your_api_key_here

Query Parameters

Parameter	Type	Required	Description
`days`	number	Yes	Number of days to filter contacts (1-365)
`stage_id`	string	No	Stage ID (UUID) to filter contacts by stage

Response Structure

Returns an array of contact objects:

Field	Type	Description
`id`	string (UUID)	Unique identifier for the contact
`name`	string	Contact’s full name
`phone`	string \| null	Contact’s phone number
`email`	string \| null	Contact’s email address
`platform`	string	Communication channel (whatsapp, instagram, etc.)
`last_message_at`	string (ISO)	Timestamp of the last message sent/received
`chat_status`	string	Current chat status (UNATTENDED, ATTENDED, etc.)
`created_at`	string (ISO)	Contact creation timestamp
`client_id`	string (UUID)	Your organization ID
`ai_customer_id`	string (UUID)	Associated customer profile ID
`default_stage_id`	string (UUID)	Current pipeline stage
`blocked`	boolean	Whether the contact is blocked
`is_chat_read`	boolean	Whether the chat has been read by an agent

Example Request

Basic Request (All Contacts)

curl --request GET \
  'https://api.vambe.ai/api/public/contacts?days=30' \
  --header 'x-api-key: your_api_key_here'

Request with Stage Filter

curl --request GET \
  'https://api.vambe.ai/api/public/contacts?days=30&stage_id=123e4567-e89b-12d3-a456-426614174000' \
  --header 'x-api-key: your_api_key_here'

Example Response

[
  {
    "id": "df980fc8-b6db-4820-bf22-2969482d106d",
    "name": "Maria Rodriguez",
    "phone": "+56912345678",
    "email": "[email protected]",
    "platform": "whatsapp",
    "last_message_at": "2024-09-30T14:25:33.000Z",
    "chat_status": "ATTENDED",
    "created_at": "2024-01-15T10:00:00.000Z",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "ai_customer_id": "660e8400-e29b-41d4-a716-446655440001",
    "default_stage_id": "770e8400-e29b-41d4-a716-446655440002",
    "blocked": false,
    "is_chat_read": true
  },
  {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "name": "Carlos Silva",
    "phone": "+56987654321",
    "email": null,
    "platform": "instagram",
    "last_message_at": "2024-09-29T18:10:22.000Z",
    "chat_status": "UNATTENDED",
    "created_at": "2024-03-20T09:30:00.000Z",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "ai_customer_id": "990e8400-e29b-41d4-a716-446655440004",
    "default_stage_id": "aa0e8400-e29b-41d4-a716-446655440005",
    "blocked": false,
    "is_chat_read": false
  }
]

Common Use Cases

1. Get Contacts from Last 7 Days

const getRecentContacts = async () => {
  const response = await fetch(
    'https://api.vambe.ai/api/public/contacts?days=7',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const contacts = await response.json();
  console.log(`Found ${contacts.length} contacts active in the last 7 days`);

  return contacts;
};

2. Track Engagement by Channel

const getContactsByChannel = async (days) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/contacts?days=${days}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const contacts = await response.json();

  // Group by platform
  const byChannel = contacts.reduce((acc, contact) => {
    const channel = contact.platform || 'unknown';
    if (!acc[channel]) acc[channel] = [];
    acc[channel].push(contact);
    return acc;
  }, {});

  console.log('Contacts by channel:', {
    whatsapp: byChannel.whatsapp?.length || 0,
    instagram: byChannel.instagram?.length || 0,
    webchat: byChannel.webchat?.length || 0,
  });

  return byChannel;
};

3. Find Unattended Contacts

const getUnattendedContacts = async (days) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/contacts?days=${days}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const contacts = await response.json();

  // Filter unattended
  const unattended = contacts.filter(
    (c) => c.chat_status === 'UNATTENDED' && !c.is_chat_read,
  );

  console.log(`${unattended.length} unattended contacts need attention`);

  return unattended;
};

4. Re-engagement Campaign Data

const getContactsForReengagement = async () => {
  // Get contacts from 30-60 days ago (active before but not recently)
  const recent30 = await fetch(
    'https://api.vambe.ai/api/public/contacts?days=30',
    {
      headers: { 'x-api-key': 'your_api_key_here' },
    },
  ).then((r) => r.json());

  const recent60 = await fetch(
    'https://api.vambe.ai/api/public/contacts?days=60',
    {
      headers: { 'x-api-key': 'your_api_key_here' },
    },
  ).then((r) => r.json());

  // Contacts in 60 days but not in 30 days
  const recent30Ids = new Set(recent30.map((c) => c.id));
  const reengageTargets = recent60.filter((c) => !recent30Ids.has(c.id));

  console.log(`${reengageTargets.length} contacts for re-engagement campaign`);

  return reengageTargets;
};

5. Export to External CRM

const exportRecentContactsToCRM = async (days) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/contacts?days=${days}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const contacts = await response.json();

  // Export to external CRM
  for (const contact of contacts) {
    await fetch('https://external-crm.com/api/contacts/sync', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer crm_token',
      },
      body: JSON.stringify({
        external_id: contact.id,
        name: contact.name,
        phone: contact.phone,
        email: contact.email,
        platform: contact.platform,
        last_activity: contact.last_message_at,
        status: contact.chat_status,
      }),
    });
  }

  console.log(`Exported ${contacts.length} contacts to CRM`);
};

6. Filter Contacts by Pipeline Stage

const getContactsByStage = async (days, stageId) => {
  const response = await fetch(
    `https://api.vambe.ai/api/public/contacts?days=${days}&stage_id=${stageId}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const contacts = await response.json();
  console.log(`Found ${contacts.length} contacts in stage ${stageId}`);

  return contacts;
};

// Example: Get all leads from the last 30 days
const leadStageId = '123e4567-e89b-12d3-a456-426614174000';
const leads = await getContactsByStage(30, leadStageId);

7. Activity Dashboard

const buildActivityDashboard = async () => {
  const periods = [
    { label: 'Today', days: 1 },
    { label: 'Last 7 days', days: 7 },
    { label: 'Last 30 days', days: 30 },
    { label: 'Last 90 days', days: 90 },
  ];

  const dashboard = {};

  for (const period of periods) {
    const response = await fetch(
      `https://api.vambe.ai/api/public/contacts?days=${period.days}`,
      {
        headers: {
          'x-api-key': 'your_api_key_here',
        },
      },
    );

    const contacts = await response.json();

    dashboard[period.label] = {
      total: contacts.length,
      unattended: contacts.filter((c) => c.chat_status === 'UNATTENDED').length,
      attended: contacts.filter((c) => c.chat_status === 'ATTENDED').length,
      byChannel: contacts.reduce((acc, c) => {
        acc[c.platform] = (acc[c.platform] || 0) + 1;
        return acc;
      }, {}),
    };
  }

  console.log('Activity Dashboard:', dashboard);
  return dashboard;
};

Query Parameters Details

Days Parameter

The days parameter filters contacts where last_message_at is within the specified number of days from now:

Days Value	Description	Use Case
`1`	Last 24 hours	Today’s activity
`7`	Last week	Weekly engagement report
`30`	Last month	Monthly active contacts
`90`	Last quarter	Quarterly analysis
`180`	Last 6 months	Semi-annual review
`365`	Last year (maximum allowed)	Annual customer base analysis

Stage ID Parameter

The optional stage_id parameter filters contacts by their current pipeline stage. Only contacts with an active ticket in the specified stage will be returned.

Parameter	Type	Required	Description
`stage_id`	string	No	UUID of the pipeline stage to filter by

Stage Filtering: When stage_id is provided, only contacts with an active ticket (active_ticket_v2) in that specific stage are returned. Contacts without an active ticket or in a different stage are excluded.

Response Ordering

Contacts are returned ordered by last_message_at in descending order (most recent first).

Cross-Channel Support

This endpoint returns contacts from all channels:

Platform	Description
`whatsapp`	WhatsApp Business API
`web-whatsapp`	WhatsApp Web (QR)
`instagram`	Instagram Direct Messages
`webchat`	Web chat widget
`sms`	SMS messages
`messenger`	Facebook Messenger
`tiktok`	TikTok Direct Messages
`voice`	Voice calls
`playground`	Test/playground channel

Error Responses

Status Code	Description
400	Bad Request - Invalid days parameter (must be 1-365)
401	Unauthorized - Invalid or missing API key
500	Internal Server Error - Something went wrong

Important Notes

Days Range: Must be between 1 and 365 days
Null Values: Some fields like email or phone may be null
Performance: Response time increases with larger days values
All Channels: Unlike the deprecated WhatsApp-specific endpoint, this returns contacts from ALL channels
Contact Count: No pagination - returns all contacts matching the criteria
Stage Filtering: When stage_id is provided, only contacts with an active ticket in that stage are returned. The stage ID must be a valid UUID.
Combined Filters: Both days and stage_id can be used together to find contacts active within a time period AND in a specific pipeline stage

Performance Considerations

Cache Results: Consider caching responses for frequently used days values
Large Datasets: For days values > 90, expect larger response sizes
Rate Limiting: Be mindful of rate limits when making frequent requests

Comparison with Deprecated Endpoint

Feature	New Endpoint (This)	Deprecated Endpoint
Path	`/api/public/contacts`	`/api/public/whatsapp/contact/contacts`
Channels	All channels	WhatsApp only
Response	AI Contact objects	WhatsApp Contact objects
Ordering	By last_message_at DESC	Not specified
Future Support	✅ Active development	❌ Deprecated

GET /api/public/contact//info - Get detailed contact info
POST /api/public/customer/upsert/info - Create or update contact
POST /api/public/contact//update-metadata - Update contact metadata

Best Practices

1. Choose Appropriate Days Range

// Good: Specific use case
const getWeeklyActive = () => fetch('...?days=7');
const getMonthlyActive = () => fetch('...?days=30');

// Avoid: Unnecessarily large range
const getAll = () => fetch('...?days=365'); // Only if you need a full year

2. Handle Empty Results

const contacts = await fetch('...?days=7').then((r) => r.json());

if (contacts.length === 0) {
  console.log('No contacts in the last 7 days');
} else {
  console.log(`Found ${contacts.length} active contacts`);
}

3. Filter on Client Side

const contacts = await fetch('...?days=30').then((r) => r.json());

// Filter by platform
const whatsappContacts = contacts.filter((c) => c.platform === 'whatsapp');

// Filter by status
const unread = contacts.filter((c) => !c.is_chat_read);

// Filter by date range
const thisWeek = contacts.filter((c) => {
  const msgDate = new Date(c.last_message_at);
  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
  return msgDate > sevenDaysAgo;
});

Headers

x-api-key

string

required

API key needed to authorize the request

Query Parameters

days

number

required

Number of days to filter contacts (1-365)

Required range: 1 <= x <= 365

Example:

30

stage

string<uuid>

stage_id

string

Stage ID to filter contacts

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Contacts retrieved successfully.

string

Example:

"df980fc8-b6db-4820-bf22-2969482d106d"

name

string

Example:

"John Doe"

phone

string

Example:

"+56912345678"

string

Example:

"[email protected]"

platform

string

Example:

"whatsapp"

last_message_at

string

Example:

"2024-09-30T10:00:00.000Z"

chat_status

string

Example:

"ATTENDED"

created_at

string

Example:

"2024-01-15T10:00:00.000Z"

Contact Management

Tags & Labels

Conversations & Messages

Tickets & Support

Team Management

Deprecated

Overview

Use Cases

Authentication

Query Parameters

Response Structure

Example Request

Basic Request (All Contacts)

Request with Stage Filter

Example Response

Common Use Cases

1. Get Contacts from Last 7 Days

2. Track Engagement by Channel

3. Find Unattended Contacts

4. Re-engagement Campaign Data

5. Export to External CRM

6. Filter Contacts by Pipeline Stage

7. Activity Dashboard

Query Parameters Details

Days Parameter

Stage ID Parameter

Response Ordering

Cross-Channel Support

Error Responses

Important Notes

Performance Considerations

Comparison with Deprecated Endpoint

Best Practices

1. Choose Appropriate Days Range

2. Handle Empty Results

3. Filter on Client Side

Headers

Query Parameters

Response

Contact Management

Tags & Labels

Conversations & Messages

Tickets & Support

Team Management

Deprecated

​Overview

​Use Cases

​Authentication

​Query Parameters

​Response Structure

​Example Request

​Basic Request (All Contacts)

​Request with Stage Filter

​Example Response

​Common Use Cases

​1. Get Contacts from Last 7 Days

​2. Track Engagement by Channel

​3. Find Unattended Contacts

​4. Re-engagement Campaign Data

​5. Export to External CRM

​6. Filter Contacts by Pipeline Stage

​7. Activity Dashboard

​Query Parameters Details

​Days Parameter

​Stage ID Parameter

​Response Ordering

​Cross-Channel Support

​Error Responses

​Important Notes

​Performance Considerations

​Comparison with Deprecated Endpoint

​Related Endpoints

​Best Practices

​1. Choose Appropriate Days Range

​2. Handle Empty Results

​3. Filter on Client Side

Headers

Query Parameters

Response

Overview

Use Cases

Authentication

Query Parameters

Response Structure

Example Request

Basic Request (All Contacts)

Request with Stage Filter

Example Response

Common Use Cases

1. Get Contacts from Last 7 Days

2. Track Engagement by Channel

3. Find Unattended Contacts

4. Re-engagement Campaign Data

5. Export to External CRM

6. Filter Contacts by Pipeline Stage

7. Activity Dashboard

Query Parameters Details

Days Parameter

Stage ID Parameter

Response Ordering

Cross-Channel Support

Error Responses

Important Notes

Performance Considerations

Comparison with Deprecated Endpoint

Related Endpoints

Best Practices

1. Choose Appropriate Days Range

2. Handle Empty Results

3. Filter on Client Side