Listar Conversas

GET /external/v1/conversations

Retorna uma lista paginada de conversas, incluindo dados de qualificacao por IA (score, etapa, motivos, objecoes). As conversas podem ser filtradas por contato, oportunidade ou status.

Autenticacao

Requer permissao conversations:read.

Parametros de Query

Parametro	Tipo	Padrao	Descricao
page	integer	1	Numero da pagina
limit	integer	50	Itens por pagina (1-100)
contact_id	string	-	Filtrar por contato
opportunity_id	string	-	Filtrar por oportunidade
status	string	-	Filtrar por status da conversa
created_after	string (ISO 8601)	-	Apenas conversas criadas a partir deste timestamp
created_before	string (ISO 8601)	-	Apenas conversas criadas ate este timestamp
updated_after	string (ISO 8601)	-	Apenas conversas atualizadas a partir deste timestamp
updated_before	string (ISO 8601)	-	Apenas conversas atualizadas ate este timestamp
last_message_after	string (ISO 8601)	-	Apenas conversas cuja ultima mensagem e a partir deste timestamp
last_message_before	string (ISO 8601)	-	Apenas conversas cuja ultima mensagem e ate este timestamp

Sync incremental

Para sincronizar uma inbox ao vivo, last_message_after costuma ser a melhor chave: GET /conversations?last_message_after=2026-06-08T00:00:00Z. Data invalida retorna 400 VALIDATION_ERROR.

Requisicao

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())

Resposta

{
  "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 - Plano Pro",
      "campaign_name": "Q1 Outbound",
      "ai_agent_name": "Qualificador 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
  }
}

Campos de Resposta

Campo	Tipo	Descricao
id	string	Identificador da conversa
status	string	Status da conversa
channel	string	Canal da conversa (ex.: LINKEDIN, WHATSAPP, INSTAGRAM)
is_group	boolean	Se e uma conversa em grupo
group_name	string	Nome do grupo quando aplicavel (nullable)
contact_id	string	Contato vinculado (nullable)
opportunity_id	string	Oportunidade vinculada (nullable)
campaign_id	string	Campanha vinculada (nullable)
ai_agent_id	string	Agente de IA que atende a conversa (nullable)
assigned_user_id	string	Vendedor atribuido a conversa (nullable)
sector_id	string	Setor/time (nullable)
qualification_score	integer	Score de qualificacao da IA (nullable)
qualification_stage	string	Etapa/classificacao da qualificacao da IA (nullable)
qualification_reasons	array	Motivos por tras da qualificacao (nullable)
objections_history	array	Objecoes detectadas/tratadas pela IA (nullable)
last_message_at	string	Timestamp ISO 8601 da ultima mensagem
created_at	string	Timestamp ISO 8601 de criacao
*_name / *_email	string	Labels resolvidos das entidades vinculadas