Skip to main content

​
Communications Module

Access via sdk.communications The Communications module lets you query past conversations with filtering, pagination, and sorting. Use it to build conversation history views, analytics dashboards, or audit trails.

​
Listing Communications

​
list(params): Promise<ListCommunicationsResponse>

Query communication history with filters and pagination. 
const result = await sdk.communications.list({
  filters: {
    type: ['chat'],
    status: ['completed'],
    agentId: 'agent-456',
    fromNumber: ['+15551234567'],
    fromEmail: ['user@example.com'],
    direction: ['inbound'],
    interactor: ['agent'],
  },
  page: 1,
  limit: 20,
  sort: '-createdAt',
  startDate: 1700000000,
  endDate: 1710000000,
});

console.log(result.data);       // Communication[]
console.log(result.pagination); // { page, limit, totalRows, totalPages, sort }

​
Request Parameters

​
ListCommunicationsParams

interface ListCommunicationsParams {
  filters: CommunicationFilters;
  page?: number;      // Page number (default: 1)
  limit?: number;     // Results per page (default: 20)
  sort?: string;      // Sort field with optional '-' prefix for descending
  startDate?: number; // Unix epoch seconds — filter by start time
  endDate?: number;   // Unix epoch seconds — filter by end time
}

​
CommunicationFilters

interface CommunicationFilters {
  /** Filter by communication type */
  type?: CommunicationType[];
  /** Filter by communication direction */
  direction?: CommunicationDirection[];
  /** Filter by status */
  status?: CommunicationStatus[];
  /** Filter by interactor type */
  interactor?: CommunicationInteractor[];
  /** Filter by specific agent */
  agentId?: string;
  /** Filter by customer phone number(s) */
  fromNumber?: string[];
  /** Filter by customer email(s) */
  fromEmail?: string[];
}

​
Filter Values

FilterValuesDescription
type'voice', 'chat', 'email', 'task'Communication channel
direction'inbound', 'outbound'Who initiated the conversation
status'failed', 'in-progress', 'completed'Current status
interactor'agent', 'human'Whether AI agent or human handled it

​
Response

​
ListCommunicationsResponse

interface ListCommunicationsResponse {
  data: Communication[];
  pagination: {
    page: number;
    limit: number;
    totalRows: number;
    totalPages: number;
    sort: string;
  };
}

​
Communication

interface Communication {
  id: string;
  createdAt: number;
  createdBy?: string;
  type: 'voice' | 'chat' | 'email' | 'task';
  status: 'failed' | 'in-progress' | 'completed';
  direction: 'inbound' | 'outbound';
  interactor: 'agent' | 'human';
  agentId: string;
  agentVersion: string;
  locale: string;
  startTime: number;
  endTime: number;
  duration?: number;
  metadata?: Record<string, string>;
}

​
Examples

​
List all completed chats

const result = await sdk.communications.list({
  filters: {
    type: ['chat'],
    status: ['completed'],
  },
  limit: 50,
});

​
Filter by customer phone number

const result = await sdk.communications.list({
  filters: {
    fromNumber: ['+15551234567'],
  },
  sort: '-startTime',
});

​
Date range query

const oneWeekAgo = Math.floor(Date.now() / 1000) - 7 * 24 * 60 * 60;
const now = Math.floor(Date.now() / 1000);

const result = await sdk.communications.list({
  filters: {
    type: ['chat', 'voice'],
  },
  startDate: oneWeekAgo,
  endDate: now,
  page: 1,
  limit: 100,
});

​
Pagination

async function getAllCommunications() {
  const all: Communication[] = [];
  let page = 1;

  while (true) {
    const result = await sdk.communications.list({
      filters: { type: ['chat'] },
      page,
      limit: 100,
    });

    all.push(...result.data);

    if (page >= result.pagination.totalPages) break;
    page++;
  }

  return all;
}

​
Filter by agent

const result = await sdk.communications.list({
  filters: {
    agentId: 'agent-uuid',
    interactor: ['agent'],
    direction: ['inbound'],
  },
  sort: '-createdAt',
  limit: 20,
});