List Conversations

GET /external/v1/conversations

Returns a paginated list of conversations, including AI qualification data (score, stage, reasons, objections). Conversations can be filtered by contact, opportunity or status.

Authentication

Requires conversations:read permission.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number for pagination
limit	integer	50	Items per page (1-100)
contact_id	string	-	Filter by contact
opportunity_id	string	-	Filter by opportunity
status	string	-	Filter by conversation status
created_after	string (ISO 8601)	-	Only conversations created on/after this timestamp
created_before	string (ISO 8601)	-	Only conversations created on/before this timestamp
updated_after	string (ISO 8601)	-	Only conversations updated on/after this timestamp
updated_before	string (ISO 8601)	-	Only conversations updated on/before this timestamp
last_message_after	string (ISO 8601)	-	Only conversations whose last message is on/after this timestamp
last_message_before	string (ISO 8601)	-	Only conversations whose last message is on/before this timestamp

Incremental sync

For a live inbox sync, last_message_after is usually the best key: GET /conversations?last_message_after=2026-06-08T00:00:00Z. An invalid date returns 400 VALIDATION_ERROR.

Request

cURL

curl --request GET \
  --url "https://app.getraze.com/external/v1/conversations?opportunity_id=opp_abc123" \
  --header "X-API-Key: YOUR_API_KEY"

Node.js

const axios = require('axios');

const response = await axios.get('https://app.getraze.com/external/v1/conversations', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  params: { opportunity_id: 'opp_abc123', limit: 50 }
});

console.log(response.data);

Python

import requests

response = requests.get(
    'https://app.getraze.com/external/v1/conversations',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'opportunity_id': 'opp_abc123', 'limit': 50}
)

print(response.json())

Response

{
  "success": true,
  "data": [
    {
      "id": "conv_88",
      "status": "active",
      "channel": "LINKEDIN",
      "is_group": false,
      "group_name": null,
      "contact_id": "cnt_abc123",
      "opportunity_id": "opp_abc123",
      "campaign_id": "camp_001",
      "ai_agent_id": "agent_07",
      "assigned_user_id": "usr_42",
      "sector_id": "sec_01",
      "qualification_score": 85,
      "qualification_stage": "qualified",
      "qualification_reasons": ["budget_ok", "decision_maker"],
      "objections_history": [],
      "last_message_at": "2026-01-20T14:00:00Z",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-20T14:00:00Z",
      "contact_name": "John Doe",
      "contact_email": "john@example.com",
      "contact_phone": "+5511999999999",
      "contact_company": "Acme Inc",
      "opportunity_title": "Acme Inc - Plan Pro",
      "campaign_name": "Q1 Outbound",
      "ai_agent_name": "Qualifier Bot",
      "assigned_user_name": "Maria Silva",
      "assigned_user_email": "maria@acme.com",
      "sector_name": "Inbound"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 12,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Response Fields

Field	Type	Description
id	string	Conversation identifier
status	string	Conversation status
channel	string	Channel of the conversation (e.g. LINKEDIN, WHATSAPP, INSTAGRAM)
is_group	boolean	Whether this is a group conversation
group_name	string	Group name when applicable (nullable)
contact_id	string	Linked contact (nullable)
opportunity_id	string	Linked opportunity (nullable)
campaign_id	string	Linked campaign (nullable)
ai_agent_id	string	AI agent handling the conversation (nullable)
assigned_user_id	string	Seller assigned to the conversation (nullable)
sector_id	string	Sector/team (nullable)
qualification_score	integer	AI qualification score (nullable)
qualification_stage	string	AI qualification stage/classification (nullable)
qualification_reasons	array	Reasons behind the qualification (nullable)
objections_history	array	Objections detected/handled by the AI (nullable)
last_message_at	string	ISO 8601 timestamp of the last message
created_at	string	ISO 8601 creation timestamp
*_name / *_email	string	Resolved labels for the linked entities