Skip to navigation
AccountCall dataAPI and export

List conversations

Use the List Conversations API to retrieve conversation transcripts with metadata, timestamps, and states programmatically. Each conversation response includes a state field containing all conversation variables (conv.state values) set during the call – both built-in keys and custom variables your agent writes.

New integrations should use the Data API – List conversations endpoint (https://api.{region}.poly.ai/v1/agents/{agent_id}/conversations). It is the official supported offering. The legacy Conversations API v3 (https://api.{region}.platform.polyai.app/v3/{account_id}/{project_id}/conversations) remains available for existing integrations.

Push and pull

PolyAI supports both push and pull API models, offering flexible synchronization options:

Pull model Push model Periodic request Conversation data Real-time webhook Your system PolyAI API PolyAI Your system

  • Pull API: On-demand metadata retrieval through the List Conversations endpoint. Ideal for periodic data collection or workflows where updates are less time-sensitive.

  • Push API: Automatically sends updates (new conversations or completed interactions) to your system in real time. Best suited for dashboards requiring prompt updates.

For triggering instant communication updates for real-time use cases, like determining where to route a call, it is recommended to use handoff states.

Best practices

  1. Pull: Use this model for scheduled reporting or when real-time updates are unnecessary.

  2. Push: Use push updates for real-time synchronization, such as live agent dashboards.

  3. If you need real-time updates, use push. If periodic batch retrieval is sufficient, use pull.

Integration with other workflows

The List Conversations API can fit into a larger data-sharing workflow:

  1. Manual access using the studio: View richly-detailed conversation transcripts and recordings directly in the PolyAI platform.

  2. End of call metadata retrieval: Automate metadata syncing after conversations using push or pull APIs.

  3. Handoff metadata integration: Provide your live customer agent with a quick identifier indicating what kind of call they have just received.