Reading and syncing conversations

Every call and chat is a conversation, read the same way whichever door it came through: the console, the widget, a phone line, a campaign or this API. Reading needs conversations:read; a transcript also needs transcripts:read, and a recording recordings:read.

List them

#!/bin/sh
# List conversations
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

Newest first, 20 a page unless you ask for up to 100. Filter by agent, project, channel, direction, status (repeat it for several), disposition, the analysis's outcome, who ended it, mode, numbers, campaign, your own external_id, and when it started or changed. Each page has has_more and a next_cursor: send it back as cursor, with the same filters, for the next page. A cursor works only for the key, the mode and the filters that made it.

Find one by what was said

#!/bin/sh
# Find conversations by what was said. Each one comes with the passage that matched.
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?q=refund&limit=10" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

q searches the transcripts, the same search as the console's, and needs transcripts:read as well. A word also finds longer words that start with it, so refund finds refunded. Put a phrase in quotes to find it as written, and write -word to leave out conversations that have the word. Every other filter still applies. Each result carries match: the passage that matched, as plain text. A key may search 30 times a minute. A conversation can be found about a minute after it ends.

Read one

#!/bin/sh
# Read a conversation with its transcript
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

The conversation carries its status and how it ended, its numbers, the values it started with and where each came from, your metadata, the lookup's result, the answers collected, the analysis, the recording's state and its times. include=transcript adds what was said. The transcript alone:

#!/bin/sh
# Read a transcript
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

Entries are in order: user is the person, assistant the agent, tool a tool the agent used, and note something the platform recorded, like a handover.

The recording

A link to the audio works for five minutes, so download it straight away rather than storing the link:

#!/bin/sh
# Get a link to a recording. The link works for five minutes, so download the audio straight away.
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

The file is stereo Ogg: the caller on the left, the agent on the right. Each key may ask for 60 links a minute and 2,000 a day, and every link is recorded in your organization's audit log.

What it cost

Ask for include=cost, which needs billing:read as well:

#!/bin/sh
# Read what a conversation cost
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

cost.credits is what the conversation cost: its own charge and every analysis of it, less any refund. A chat is charged as it goes, so an open chat's cost can still grow. Every charge behind the number is in the credit history.

Run the analysis again

Run the agent's analysis on a conversation that has ended: again, after you change the agent's analysis settings, or for the first time on one that was never analysed. This needs analysis:run:

#!/bin/sh
# Analyse a conversation again. It costs credit, like any analysis.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

The answer is the conversation with its new analysis, and conversation.analyzed is sent again. Each run costs credit, like the first one, and an organization may run 10 a minute. A conversation still in progress is refused with 409 conversation_in_progress, and one where too little was said with 422 conversation_too_short.

Keep your copy in sync

Ask for what changed instead of reading everything again:

#!/bin/sh
# Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

With order=changed, the oldest change comes first. Read until has_more is false, keep the last page's next_cursor, and next time start from it: you get every conversation that changed since, once, in order. Changes from the last minute wait for a later page, so a conversation still being written is never skipped. Every conversation has a revision that only goes up: of two copies, keep the higher.

Delete one

Deleting needs conversations:delete, a permission no starting point in the console includes:

#!/bin/sh
# Delete a conversation. With its recording, for good.
curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

The transcript, the recording and any pictures go with it, for good. A call still in progress is refused with 409 conversation_in_progress: end it first. A chat that is still open is charged for what it used, then deleted. What it cost stays in the credit history. It is listed below with the reason api, conversation.deleted is sent to your receivers, and the organization's audit log records which key deleted it.

Deleted conversations

A conversation can be deleted — by the organization's retention, from the console, through this API, or with its agent or project. Ask for those too, and remove them from your copy:

#!/bin/sh
# List deleted conversations
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/deleted" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

Deletions are listed for 30 days.

What a test key sees

A test key reads, searches and deletes only conversations made with test keys, and a live key never sees them. A real conversation asked for with a test key is 404, as if it did not exist. Running the analysis again on a test call gives its sample analysis again, at no cost; a test chat is analysed by the agent's real model, and charged.