Conversation Insights

After a chat ends, use the /v2/conversation/* endpoints to fetch summaries, mentioned entities, and exports for analytics or follow-up. This guide focuses on the most-used endpoints: /products, /recipes, and /summarize, and also covers list/detail, flags, and export helpers.

These examples assume you already created a session token as described in API Dependencies and you will authenticate each request with organization-id and x-session headers. Include kiosk headers (kiosk-id, x-kiosk, x-temp-kiosk, x-device-id) when calling from kiosk devices.

Quick reference

Mentions: products and recipes

Use these to drive recommended follow-up, cart nudges, or CRM tagging.

curl -X POST "https://api.retrend.ai/v2/conversation/products" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"cid\":\"CONVERSATION_UUID\"}"

Response (ProductsResponse):

{
  "products": ["PID-1", "PID-2"]
}

Hydrate each product_id with /v2/info/product.

Recipe mentions:

curl -X POST "https://api.retrend.ai/v2/conversation/recipes" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"cid\":\"CONVERSATION_UUID\"}"

Response (RecipesResponse):

{
  "recipes": ["RID-1", "RID-2"]
}

Hydrate each recipe_id with /v2/info/recipe.

Summaries

POST /v2/conversation/summarize

curl -X POST "https://api.retrend.ai/v2/conversation/summarize" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"cid\":\"CONVERSATION_UUID\",\"summary_type\":\"web\"}"

Request body (SummarizeRequest):

• cid (UUID) — required conversation ID.
• summary_type — enum SummaryType (e.g., web, agent, or other values defined in the spec).

Response (SummarizeResponse):

• store_num — store number for context.
• summary — generated text for the audience requested.

List and detail

List conversations

POST /v2/conversation/list supports filtering and cursor pagination.

Common filters (all optional unless noted):

• start_date, end_date (ISO datetime, required) — inclusive window.
• channels (["kiosk","mobile"]), intents (string[]), store_id, min_duration_sec, product_name, product_id.
• cursor — opaque ISO timestamp to fetch items strictly before start_time.
• page_size — default 50.

Example:

curl -X POST "https://api.retrend.ai/v2/conversation/list" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"start_date\":\"2024-05-01T00:00:00Z\",\"end_date\":\"2024-05-31T23:59:59Z\",\"channels\":[\"kiosk\"],\"page_size\":25}"

Response (ConversationListResponse):

• items — array of ConversationSummaryItem with cid, start_time, end_time, channel, intent, store_id, preview_products.
• next_cursor — use to fetch the next page; null when complete.

Conversation detail

POST /v2/conversation/detail

curl -X POST "https://api.retrend.ai/v2/conversation/detail" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"cid\":\"CONVERSATION_UUID\"}"

Response (ConversationDetailResponse) includes:

• Identifiers: cid, store_id, store_num, kiosk_num, is_kiosk.
• Summaries: short_summary (internal), web_summary (customer-facing) when available.
• Mentions: product_ids, recipe_ids.

Flags (availability checks)

POST /v2/conversation/flags quickly tells you which artifacts exist before fetching them.

Response (FlagsResponse):

• summary, products, recipes, party_plan — booleans indicating presence.

Export

POST /v2/conversation/export returns a synchronous payload and MIME type.

Required body fields:

• start_date, end_date — ISO datetimes.
• format — one of json, csv_conversations, csv_product_mentions.

Optional filters mirror /conversation/list: channels, intents, store_id, min_duration_sec, product_name, product_id.

Example:

curl -X POST "https://api.retrend.ai/v2/conversation/export" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"start_date\":\"2024-05-01T00:00:00Z\",\"end_date\":\"2024-05-31T23:59:59Z\",\"format\":\"csv_conversations\"}"

Response (ConversationExportResponse):

• mime_type — e.g., text/csv or application/json.
• payload — serialized export content.

Implementation tips

• Hydrate IDs: /conversation/products and /conversation/recipes return IDs; fetch /info/product and /info/recipe to render details.
• Paginate with cursors: keep next_cursor from /conversation/list and pass it as cursor for the next page.
• Guard with flags: call /conversation/flags before pulling summaries to avoid unnecessary fetches.
• Audience-specific summaries: choose summary_type appropriate for your UI (web/customer vs. internal/agent).