List conversations
Retrieves a paginated list of conversations. WithoutagentIds, standard users see only conversations belonging to genies they own. With agentIds, they also see conversations of their workspace’s genies (each listed genie is checked against the same access rule as Get genie; genies the caller can’t access are ignored, and an empty result is returned if none are accessible). Admin users see all conversations.
A team member with limited access (see Teams → Access levels) only lists conversations through an inbox view assigned to them:
viewId is required and must be one of their assigned views, otherwise an empty list is returned. Genie and owner filters are ignored for them. An admin impersonating a limited member gets the same results the member would.Response
Opaque cursor string. Pass as
cursor in the next request to fetch the next page. null when there are no more results.Only when
withCounts is true on the first page. Number of conversations matching the filters across all pages.Only when
withCounts is true on the first page. Number of those conversations not yet viewed (viewed is false).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 — passskipAnalysis: true to skip this step and return saved data immediately.
Accepts a numeric database ID, a UUID, or (for older links) an external conversation ID from the voice platform.
Standard users can retrieve conversations of genies they can access — their own and their workspace’s genies. A team member with limited access can retrieve only conversations in their assigned inbox views, and the embedded agent object is reduced to id, name, type, branding and goal. A conversation the caller can’t access returns NOT_FOUND.
The conversation ID. Accepts a numeric database ID, a UUID, or an external voice-platform conversation ID (for older links).
Response
Returns the full conversation object spread directly intodata, with nested genie, analysis details, and media.
Whether the conversation has been viewed. Always
true after a successful get call — the conversation is marked viewed automatically.The genie that handled this conversation, including its full configuration and lead-info preset.
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.Media records (recordings, attachments) associated with this conversation. Empty array when no media exists.
Sync conversations
Triggers a sync of conversations from the voice agent system for a specific genie.Response
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.Response
Returns a detailed analysis object generated by thehandle-conversation edge function.
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 update any allowed field on their own conversations. A teammate with access to the genie (its owner, the team owner or a teammate) can update onlyhandled_at, assigned_to and viewed. Anything else returns NOT_FOUND.
A team member with limited access can update those same three fields only on conversations in their assigned inbox views, and only if their permissions allow it: changing assigned_to needs the take or assign permission and handled_at needs the mark handled permission (see Teams → Access levels). A missing permission returns FORBIDDEN. viewed needs no extra permission.
Fields to update. Can be provided directly or nested under an
updates key.
Allowed fields: agent_id, assigned_to, el_agent_id, elevenlabs_id, handled_at, metadata, status, type, user_id, viewed. Any other key is dropped; a payload with no allowed key is rejected with VALIDATION_ERROR. When updates is present, flat keys on data are ignored.Response
Returns the updated conversation object directly indata.
Delete conversation
Permanently deletes a conversation. Standard users can only delete their own conversations. Admin users can delete any conversation. If the conversation belongs to a genie meeting, the meeting and its stored transcript are deleted with it.Response
Mark all viewed
Marks all conversations as viewed for the authenticated user.Response
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.Get conversation by external ID
Retrieves a single conversation by its external conversation identifier from the voice platform, marks it viewed, and triggers analysis if details are incomplete. Access follows the same rule as Get conversation.Response
Returns the full conversation object (same shape as theget action).
Delete conversation media
Deletes one image attachment from a conversation, or all images if nomediaId is specified.
Recap
Generates a short 2–3 bullet-point recap from a conversation transcript. This is a stateless public endpoint — it reads only the supplied transcript, not stored data.No authentication required for this action.

