Conversations

List conversations

Retrieves a paginated list of conversations. Standard users see only conversations belonging to their own genies. Admin users see all conversations.

string

required

conversations

string

required

all

object

Show properties

string[]

Filter conversations to specific genies by UUID array. When omitted, returns conversations for all genies the user owns.

number

Maximum number of records to return per page. Defaults to 30, maximum 500.

string

Cursor returned from a previous response as nextCursor. Pass it unchanged to fetch the next page.

string

Relative time filter. Format: {value}{unit} where unit is h (hours), d (days), or m (minutes). For example, "24h" returns conversations from the last 24 hours.

boolean

When true, excludes conversations with type = "mailbox".

string

Filter by conversation type. Accepted values:

"regular" — conversations that are not setup or mailbox type
"setup" — setup conversations
"mailbox" — mailbox-originated conversations

string

Filter by the channel the conversation originated from. Accepted values:

"phone" — inbound phone calls
"email" — email conversations
"app" — mobile or native app
"link" — link or QR code
"web" — web widget (default fallback for unrecognized sources)

string

Admin only. Filter conversations to genies owned by this user ID.

const response = await ApiService.invoke({
  resource: "conversations",
  action: "list",
  data: {
    agentIds: ["agent-uuid"],
    limit: 30,
    channel: "phone",
    conversationType: "regular",
  },
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "conversations",
    "action": "list",
    "data": {
      "agentIds": ["agent-uuid"],
      "limit": 30,
      "channel": "phone",
      "conversationType": "regular"
    }
  }'

Response

Conversation[]

Array of conversation objects, each joined with basic genie info.

Show Conversation object

number

Unique conversation identifier.

string | null

ID of the genie this conversation belongs to.

string | null

External agent ID from the voice platform.

string | null

ID of the user who owns the genie.

string | null

Conversation status.

string | null

Conversation type.

object | null

Arbitrary metadata associated with the conversation.

boolean

Whether the conversation has been viewed.

string

ISO 8601 timestamp of when the conversation was created.

object | null

Joined genie data.

Show properties

string

Genie ID.

string

Genie name.

string | null

Opaque cursor string. Pass as cursor in the next request to fetch the next page. null when there are no more results.

boolean

Whether more results are available beyond this page.

Get conversation

Retrieves a single conversation by ID, including analysis details and associated media. The conversation is automatically marked as viewed on fetch. If analysis details exist but are incomplete, analysis runs automatically before the response is returned.

string

required

conversations

string

required

get

string

required

The conversation ID.

const response = await ApiService.invoke({
  resource: "conversations",
  action: "get",
  id: "123",
});

curl -X POST https://api.helpgenie.ai/v1/conversations \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "get",
    "id": "123"
  }'

Response

Returns the full conversation object spread directly into data, with nested genie, analysis details, and media.

string

Unique conversation identifier.

string | null

ID of the genie this conversation belongs to.

string | null

Conversation status.

object | null

Arbitrary metadata associated with the conversation.

boolean

Whether the conversation has been viewed. Always true after a successful get call — the conversation is marked viewed automatically.

string

ISO 8601 timestamp.

object | null

The genie that handled this conversation, including its full configuration and lead-info preset.

object[] | null

Analysis details for this conversation. Contains summary, transcript, goals, topics, lead_info, and analysis_result. If these fields were missing when the conversation was fetched, analysis is triggered automatically and the populated details are returned in this response.

object[]

Media records (recordings, attachments) associated with this conversation. Empty array when no media exists.

Show item properties

string

Media record ID.

object

Media metadata, including conversations_id.

Sync conversations

Triggers a sync of conversations from the voice agent system for a specific genie.

string

required

conversations

string

required

sync

object

required

Show properties

string

required

The genie ID to sync conversations for. The user must own this genie.

const response = await ApiService.invoke({
  resource: "conversations",
  action: "sync",
  data: {
    agentId: "agent-uuid",
  },
});

Response

boolean

true if the sync completed without errors.

boolean

true if new conversation data was pulled from the voice agent system.

object

The synced conversation record with the latest data from the voice agent system.

Show properties

number

Unique conversation identifier.

string

ID of the genie this conversation belongs to.

string

Updated conversation status from the voice platform.

object | null

Conversation metadata, including any data synced from the voice platform.

string

ISO 8601 timestamp.

Sync pulls the latest conversation data from the voice agent system, including updated transcripts, status, and metadata. The authenticated user must own the genie specified by agentId. A 403 FORBIDDEN error is returned otherwise.

Analyze conversation

Runs an analysis on a specific conversation.

string

required

conversations

string

required

analyze

string

required

The conversation ID to analyze.

object

Additional parameters to pass to the analysis function.

const response = await ApiService.invoke({
  resource: "conversations",
  action: "analyze",
  id: "123",
  data: {
    // optional analysis parameters
  },
});

Response

Returns a detailed analysis object generated by the handle-conversation edge function.

object

The analysis result for the conversation.

Show Analysis object

string

Overall sentiment of the conversation. One of positive, negative, neutral, or mixed.

string

A concise natural-language summary of the conversation.

string[]

Array of topics discussed during the conversation.

object[]

Extracted action items or follow-ups.

Show ActionItem object

string

Description of the action item.

string | null

Who the action item is assigned to, if identifiable.

string

Priority level: high, medium, or low.

object

Timing breakdown for the conversation.

Show properties

number

Total duration of the conversation in seconds.

number

Time the genie spent speaking.

number

Time the caller spent speaking.

number

Total silence or dead air time.

string

The ID of the analyzed conversation.

string

ISO 8601 timestamp of when the analysis was performed.

Analysis is performed asynchronously. For longer conversations, the response may take several seconds to return while the analysis is generated.

Update conversation

Updates metadata or fields on an existing conversation. Standard users can only update their own conversations.

string

required

conversations

string

required

update

string

required

The conversation ID to update.

object

required

Fields to update. Can be provided directly or nested under an updates key. Allowed fields: agent_id, el_agent_id, metadata, status, type, user_id, viewed.

Show properties

string

Updated conversation status.

object

Updated metadata object.

boolean

Mark conversation as viewed or unviewed.

const response = await ApiService.invoke({
  resource: "conversations",
  action: "update",
  id: "123",
  data: {
    viewed: true,
    metadata: { notes: "Follow up required" },
  },
});

Response

Returns the updated conversation object directly in data.

Delete conversation

Permanently deletes a conversation. Standard users can only delete their own conversations. Admin users can delete any conversation.

string

required

conversations

string

required

delete

string

required

The conversation ID to delete.

const response = await ApiService.invoke({
  resource: "conversations",
  action: "delete",
  id: "123",
});

Response

boolean

true if the conversation was deleted.

string

The ID of the deleted conversation.

This action is permanent and cannot be undone.

Mark all viewed

Marks all conversations as viewed for the authenticated user.

string

required

conversations

string

required

mark-all-viewed

const response = await ApiService.invoke({
  resource: "conversations",
  action: "mark-all-viewed",
});

Response

boolean

true if the operation completed.

Clear agent data

Permanently deletes all conversation history and activity records for a specific genie. Typically used when reassigning a genie to a different customer to ensure no prior data carries over.

This action is irreversible and restricted to admin users. All conversations, inbox records, conversation details, and activity logs for the specified genie are permanently removed.

string

required

conversations

string

required

clear-agent-data

object

required

Show properties

string

required

The genie ID whose conversation history should be cleared.

boolean

true if the operation completed successfully.

number

The number of conversation records that were deleted.

const response = await ApiService.invoke({
  resource: "conversations",
  action: "clear-agent-data",
  data: {
    agentId: "agent-uuid",
  },
});

curl -X POST https://api.helpgenie.ai/v1/conversations \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "conversations",
    "action": "clear-agent-data",
    "data": {
      "agentId": "agent-uuid"
    }
  }'

{
  "success": true,
  "data": {
    "success": true,
    "deletedConversations": 42
  }
}

Error responses

Status	Code	Description
400	`VALIDATION_ERROR`	Missing required fields (e.g. conversation ID)
403	`FORBIDDEN`	User does not own the genie (for sync)
404	`NOT_FOUND`	Conversation not found or access denied
500	`INTERNAL_ERROR`	Server error

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List conversations

Response

Get conversation

Response

Sync conversations

Response

Analyze conversation

Response

Update conversation

Response

Delete conversation

Response

Mark all viewed

Response

Clear agent data

Error responses

​List conversations

​Response

​Get conversation

​Response

​Sync conversations

​Response

​Analyze conversation

​Response

​Update conversation

​Response

​Delete conversation

​Response

​Mark all viewed

​Response

​Clear agent data

​Error responses

List conversations

Response

Get conversation

Response

Sync conversations

Response

Analyze conversation

Response

Update conversation

Response

Delete conversation

Response

Mark all viewed

Response

Clear agent data

Error responses