Skip to main content
GET
Get contacts by status

Overview

Get contacts filtered by their conversation status (unattended, attended, ai-attended, ai-away) with calculated waiting times. This endpoint helps you identify contacts that need attention and prioritize responses based on how long they’ve been waiting. Perfect for building priority queues, monitoring SLAs, and ensuring no customer is left waiting too long.

Use Cases

  • Priority Queue: Display contacts sorted by waiting time
  • SLA Monitoring: Track contacts approaching SLA thresholds
  • Workload Distribution: Identify unattended conversations for assignment
  • Response Urgency: Find contacts waiting longest for response
  • Status Dashboard: Monitor conversations by status
  • Customer Service Quality: Ensure timely responses to all customers

Authentication

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

Query Parameters

Status Values

Response Structure

Contact Object

Example Requests

Get Unattended Contacts

Filter by Pipeline

Example Response

Common Use Cases

1. Display Priority Queue

2. SLA Alert System

3. Auto-Assignment Based on Wait Time

4. Status Dashboard

Waiting Time Calculation

The waiting_time field is calculated as:
  • Unit: Seconds
  • Sorted: Longest waiting time first
  • Real-time: Calculated at query time
To convert to minutes:

Pagination

  • Each page returns up to 50 contacts
  • Contacts sorted by waiting_time DESC (longest wait first)
  • Use total field to determine total matching contacts

Error Responses

Important Notes

  • Sorted by Urgency: Longest waiting contacts appear first
  • Active Tickets: Only shows contacts with active tickets
  • Real-time: Waiting time calculated dynamically
  • Status Filter Required: Must specify a status

Headers

x-api-key
string
required

API key

Query Parameters

page
string
required

Page number

Example:

"1"

orderBy
enum<string>
Available options:
contact_created_at,
ticket_created_at,
last_inbound_message,
last_outbound_message,
id
channel
enum<string>
required
Available options:
whatsapp,
playground,
instagram,
webchat,
web-whatsapp,
messenger,
sms
pipelineId
string
required

Pipeline ID

Example:

"1234567890"

status
enum<string>
required

Status

Available options:
unattended,
attended,
ai-attended,
ai-away

Response

200 - application/json

Returns contacts with pending responses

id
string

Contact ID

name
string

Contact name

created_at
string<date-time>

Contact creation date