Calls API

The Calls API allows you to programmatically access call logs from your echowin account. You can list calls with filtering and search, and retrieve detailed information including transcripts and recording URLs.

Rate Limits

List Calls: 200 requests per hour
Get Call Details: 500 requests per hour
Max Results Per Page: 100 calls

GET/api/v1/calls

Get a paginated list of calls with optional filtering and search

Query Parameters

pageinteger(default: 1)

Page number

limitinteger(default: 20)

Number of results per page (max 100)

searchstring

Search in phone numbers (from/to), transcripts, and summaries

callTypestring(default: all)

Filter by call type: all, incoming, or outgoing

agentIdstring

Filter by agent ID (UUID)

minDurationinteger

Minimum call duration in seconds

maxDurationinteger

Maximum call duration in seconds

dateFromstring

Start date for filtering (ISO 8601 format)

dateTostring

End date for filtering (ISO 8601 format)

sortBystring(default: createdAt)

Sort field: createdAt, duration, or endedAt

sortOrderstring(default: desc)

Sort order: asc or desc

Responses

200Success

{
  "data": [
    {
      "id": "call-uuid-1234",
      "from": "+15551234567",
      "to": "+15559876543",
      "type": "INCOMING",
      "status": "completed",
      "duration": 245,
      "createdAt": "2024-01-15T14:30:00.000Z",
      "endedAt": "2024-01-15T14:34:05.000Z",
      "summary": "Customer inquired about product availability and placed an order.",
      "score": 4.5,
      "flagged": false,
      "favorite": true,
      "spam": false,
      "agent": {
        "id": "agent-uuid-1234",
        "name": "Customer Support Agent"
      },
      "transcript": [
        {
          "speaker": "agent",
          "text": "Hello, thank you for calling. How can I help you today?",
          "timestamp": "2024-01-15T14:30:05.000Z"
        },
        {
          "speaker": "caller",
          "text": "Hi, I wanted to check if you have the XYZ product in stock.",
          "timestamp": "2024-01-15T14:30:15.000Z"
        }
      ],
      "recordingUrl": "https://cr.files.echo.win/recording-key-abc123"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 150,
    "totalPages": 8
  }
}

API Tester

Request URL

GET https://echo.win/api/v1/calls

Query Parameters

page

limit

callType

agentId

minDuration

maxDuration

dateFrom

dateTo

sortBy

sortOrder

API Key

Headers (JSON)

GET/api/v1/calls/:callId

Get detailed information about a specific call including full transcript, activity timeline, and metadata

Path Parameters

callIdstringrequired

The unique identifier (UUID) of the call

Responses

200Success

{
  "data": {
    "id": "call-uuid-1234",
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "INCOMING",
    "status": "completed",
    "duration": 245,
    "createdAt": "2024-01-15T14:30:00.000Z",
    "endedAt": "2024-01-15T14:34:05.000Z",
    "summary": "Customer inquired about product availability and placed an order.",
    "score": 4.5,
    "flagged": false,
    "favorite": true,
    "spam": false,
    "memory": "Customer prefers email communication. Has ordered before.",
    "agent": {
      "id": "agent-uuid-1234",
      "name": "Customer Support Agent"
    },
    "transcript": [
      {
        "speaker": "agent",
        "text": "Hello, thank you for calling. How can I help you today?",
        "timestamp": "2024-01-15T14:30:05.000Z"
      },
      {
        "speaker": "caller",
        "text": "Hi, I wanted to check if you have the XYZ product in stock.",
        "timestamp": "2024-01-15T14:30:15.000Z"
      },
      {
        "speaker": "agent",
        "text": "Yes, we do have the XYZ product available. Would you like to place an order?",
        "timestamp": "2024-01-15T14:30:25.000Z"
      }
    ],
    "activityTimeline": [
      {
        "id": "log-uuid-1",
        "type": "CALL_ANSWERED",
        "sender": null,
        "data": null,
        "toolData": null,
        "timestamp": "2024-01-15T14:30:00.000Z"
      },
      {
        "id": "log-uuid-2",
        "type": "RESPONSE",
        "sender": "agent",
        "data": "Hello, thank you for calling. How can I help you today?",
        "toolData": null,
        "timestamp": "2024-01-15T14:30:05.000Z"
      },
      {
        "id": "log-uuid-3",
        "type": "TOOL_CALL",
        "sender": "agent",
        "data": "Looking up inventory...",
        "toolData": {
          "tool": "check_inventory",
          "result": {
            "inStock": true,
            "quantity": 50
          }
        },
        "timestamp": "2024-01-15T14:30:30.000Z"
      }
    ],
    "recordingUrl": "https://cr.files.echo.win/recording-key-abc123",
    "metadata": {
      "sentiment": {
        "happy": 0.8,
        "sad": 0,
        "angry": 0,
        "neutral": 0.2
      },
      "callQuality": "excellent",
      "technicalIssues": null,
      "usage": {
        "inputTokens": 1500,
        "outputTokens": 800,
        "totalTokens": 2300
      },
      "callCost": 0.15
    }
  }
}

404Call not found

{
  "error": "Call not found"
}

API Tester

Request URL

GET https://echo.win/api/v1/calls/:callId

API Key

Headers (JSON)

Response Fields Reference

Call Object

idUnique identifier for the call

fromCaller's phone number

toRecipient's phone number

typeINCOMING or OUTGOING

durationCall duration in seconds

summaryAI-generated summary of the call

scoreCall quality score (0-5)

recordingUrlURL to the call recording audio file

Transcript Entry

speaker"caller" or "agent"

textThe spoken text

timestampWhen this was spoken (ISO 8601)

Activity Timeline Types

RESPONSEAgent or caller speech

TOOL_CALLAgent used a tool (e.g., check inventory, send email)

TRANSFERCall was transferred

SEND_EMAILEmail was sent during call

SEND_TEXTSMS was sent during call

HANGUPCall ended

API Reference

Calls API

Rate Limits

Table of Contents

Query Parameters

Responses

API Tester

Path Parameters

Responses

API Tester

Response Fields Reference

Call Object

Transcript Entry

Activity Timeline Types