List Conversations - eigi.ai Documentation

Overview

This endpoint returns a paginated list of conversations based on the API key owner’s agents. It supports comprehensive filtering by status, type, date range, time of day, and more.

Authentication

X-API-Key

string

required

Your eigi.ai API key. Must be prefixed with vk_.

Query Parameters

Pagination

page

integer

default:"1"

Page number to retrieve (minimum: 1)

page_size

integer

default:"10"

Number of items per page (minimum: 1, maximum: 100)

Search & Filters

string

Search text to filter conversations by content in metadata or transcript

conversation_id

string

Filter by specific conversation ID

agent_id

string

Filter conversations by specific agent ID

conversation_type

string

Filter by conversation type. Options: DAILY, TELEPHONY, WHATSAPP, CHAT

calling_type

string

Filter by call direction. Options: INBOUND, OUTBOUND

conversation_status

string

Filter by conversation status. Options: IN_PROGRESS, COMPLETED, DISCONNECTED, FAILED

Date & Time Filters

from_date

datetime

Filter conversations created on or after this date (ISO 8601 format)Example: 2025-12-01T00:00:00Z

to_date

datetime

Filter conversations created on or before this date (ISO 8601 format)Example: 2025-12-31T23:59:59Z

from_time

string

Filter by time of day - start time (HH:MM format, 24-hour)Example: 09:00

to_time

string

Filter by time of day - end time (HH:MM format, 24-hour)Example: 17:00

timezone_offset

integer

default:"330"

Timezone offset in minutes from UTC for time filtering. Examples: IST is 330 (UTC+5:30), EST is -300 (UTC-5:00), PST is -480 (UTC-8:00).

Response

status

string

Status of the request: success or error

message

string

Human-readable message describing the result (e.g., “Retrieved 5 conversations”)

data

array

Array of conversation objects matching the filter criteria. Each conversation contains: - agent_id: ID of the agent - conversation_id: Unique UUID for the conversation - conversation_type: DAILY, TELEPHONY, WHATSAPP, or CHAT - conversation_analysis: AI analysis results (null if not analyzed) - conversation_status: IN_PROGRESS, COMPLETED, DISCONNECTED, or FAILED

notes: Additional notes - conversation_transcript: Array of messages with role, content, timestamp - created_by: User ID who created the conversation - conversation_metadata: Type-specific metadata - created_at: Creation timestamp - updated_at: Last update timestamp - id: Internal document ID

pagination

object

Pagination information containing: - total: Total number of conversations matching filters - page: Current page number - page_size: Number of items per page - total_pages: Total number of pages available

curl -X GET "https://prod.eigi.ai/v1/public/conversations?page=1&page_size=5" \
  -H "X-API-Key: vk_your_api_key_here"

{
  "status": "success",
  "message": "Retrieved 5 conversations",
  "data": [
    {
      "agent_id": "68ea2517dbb84c09bae1ba0a",
      "conversation_id": "a28e7071-508e-4d45-8887-085531aafaba",
      "conversation_type": "CHAT",
      "conversation_analysis": null,
      "conversation_status": "IN_PROGRESS",
      "notes": null,
      "conversation_transcript": [
        {
          "role": "user",
          "content": "hi",
          "timestamp": "2025-12-03T14:14:23.735228+00:00"
        },
        {
          "role": "assistant",
          "content": "Hi there! How can I help you today?",
          "timestamp": "2025-12-03T14:14:23.738544+00:00"
        }
      ],
      "created_by": null,
      "conversation_metadata": {
        "last_activity": "2025-12-03T14:15:20.985321+00:00",
        "session_status": "active"
      },
      "created_at": "2025-12-03T14:14:22.719000",
      "updated_at": "2025-12-03T14:15:20.985000",
      "id": "69316c7d6519e8d49433e40b"
    },
    {
      "agent_id": "68ea2517dbb84c09bae1ba0a",
      "conversation_id": "35d33a43-176c-405c-92bf-db972035df28",
      "conversation_type": "TELEPHONY",
      "conversation_analysis": [{ "is_good": true }],
      "conversation_status": "COMPLETED",
      "notes": "Re-analysis completed successfully",
      "conversation_transcript": null,
      "created_by": "68ea1dc3a8f78b1cbdfed6f5",
      "conversation_metadata": {
        "dynamic_variables": {
          "agent_id": "68ea2517dbb84c09bae1ba0a"
        },
        "to_mobile_number": "+919156685436",
        "from_mobile_number": "918035315228",
        "calling_type": "OUTBOUND",
        "telephony_provider": "PLIVO",
        "conversation_recording_url": "https://aps1.media.plivo.com/v1/Account/.../Recording/xxx.mp3",
        "conversation_duration": 14
      },
      "created_at": "2025-11-29T10:20:31.364000",
      "updated_at": "2025-11-29T13:56:06.618000",
      "id": "69316c7d6519e8d49433e40f"
    }
  ],
  "pagination": {
    "total": 53,
    "page": 1,
    "page_size": 5,
    "total_pages": 11
  }
}

Error Responses

Status Codes

Status Code	Description
200	Successfully retrieved conversations
401	Missing, invalid, inactive, or expired API key
500	Internal server error

Use Cases

Dashboard Analytics

Retrieve all conversations for a date range to build analytics dashboards showing call volumes, success rates, and trends.

Campaign Reporting

Filter by agent and date range to analyze the performance of specific campaigns or outreach efforts.

Business Hours Analysis

Use time filters to analyze conversations during specific business hours and optimize agent availability.

Status Monitoring

Filter by status to monitor failed calls, track in-progress conversations, or review completed interactions.

Export for CRM

Paginate through all conversations to export data for integration with CRM systems or data warehouses.

Filtering Tips

Combine Multiple Filters: You can combine multiple filters for precise results. For example, filter by agent, status, and date range simultaneously.

?agent_id=68ea2517dbb84c09bae1ba0a&conversation_status=COMPLETED&from_date=2025-12-01

Time Zone Handling: The timezone_offset parameter helps filter conversations by local time. For IST (India), use 330 minutes (UTC+5:30).

Pagination Best Practices: Start with a smaller page_size (10-20) for faster responses. Use has_next to determine if more pages are available.

Notes

Only conversations from agents owned by the API key holder are returned
Maximum page_size is capped at 100 items
If page_size exceeds 100, it’s automatically adjusted to 100
If page_size is less than 1, it defaults to 10
Results are sorted by created_at in descending order (newest first)
Empty result sets return an empty array with total: 0

Authorizations

X-API-Key

string

header

required

API key for authentication. Get your API key from the eigi.ai Dashboard under Settings → API Keys.

Query Parameters

page

integer

default:1

Page number (minimum: 1)

Required range: x >= 1

page_size

integer

default:10

Items per page (minimum: 1, maximum: 100)

Required range: 1 <= x <= 100

string

Search text in conversation metadata

conversation_id

string

Filter by specific conversation ID

agent_id

string

Filter by specific agent ID

conversation_type

enum<string>

Filter by conversation type

Available options:

DAILY,

TELEPHONY,

WHATSAPP,

CHAT

calling_type

enum<string>

Filter by call direction

Available options:

INBOUND,

OUTBOUND

conversation_status

enum<string>

Filter by conversation status

Available options:

IN_PROGRESS,

COMPLETED,

DISCONNECTED,

FAILED

from_date

string<date-time>

Filter conversations created on or after this date (ISO 8601)

to_date

string<date-time>

Filter conversations created on or after this date (ISO 8601)

from_time

string

Filter by time of day - start time (HH:MM format)

to_time

string

Filter by time of day - end time (HH:MM format)

timezone_offset

integer

default:330

Timezone offset in minutes from UTC (default: 330 for IST)

Response

Successfully retrieved conversations

conversations

object[]

Show child attributes

conversations.conversation_id

string

Unique identifier for the conversation

conversations.agent_id

string

ID of the agent that handled this conversation

conversations.conversation_type

enum<string>

Type of conversation

Available options:

DAILY,

TELEPHONY,

WHATSAPP,

CHAT

conversations.conversation_status

enum<string>

Current status of the conversation

Available options:

IN_PROGRESS,

COMPLETED,

DISCONNECTED,

FAILED

conversations.calling_type

enum<string>

Direction of the call

Available options:

INBOUND,

OUTBOUND

conversations.mobile_number

string

Phone number involved in the conversation

conversations.duration

number

Total duration of the conversation in seconds

conversations.created_at

string<date-time>

Timestamp when the conversation was created

conversations.updated_at

string<date-time>

Timestamp of the last update

conversations.transcript

object[]

Array of conversation messages

conversations.analysis

object

AI-generated analysis of the conversation

conversations.metadata

object

Custom metadata

total

integer

page

integer

page_size

integer

total_pages

integer

has_next

boolean

has_previous

boolean

Overview

Conversations

Chat

​Overview

​Authentication

​Query Parameters

​Pagination

​Search & Filters

​Date & Time Filters

​Response

​Error Responses

​Status Codes

​Use Cases

​Filtering Tips

​Notes

Authorizations

Query Parameters

Response

Overview

Authentication

Query Parameters

Pagination

Search & Filters

Date & Time Filters

Response

Error Responses

Status Codes

Use Cases

Filtering Tips

Notes