Skip to main content

Export Your Conversation History with the Rep AI API

Updated

What this is

Rep AI gives you direct, API-key-authenticated access to your own conversation history so your developer or data team can pull raw chat transcripts into your own systems — a data warehouse, BI tool, CDP, or attribution/ML pipeline. There are two ways to retrieve conversations:

  • Look up one shopper — get every conversation tied to a single email address.

  • Bulk export by date range — pull all conversations between two dates, with optional topic and satisfaction filters and pagination for large pulls.

This is available to every store with an API key — there is no plan requirement and no extra setup beyond the keys you already have.

Good to know up front

All times are in UTC. The dates you send and the timestamps you get back are UTC — no time-zone conversion happens on our side.

History goes back up to 1 year. If you ask for a start date older than one year, we automatically move it to the one-year mark and tell you in the response (see clamped below).

Before you start: your keys

Everything you need is on the Settings → API Keys page in your Rep AI console. You will use two values:

  • Account Key — identifies your store. Goes in the account_key query parameter.

  • API Key — your secret authentication token. Goes in the Authorization: Bearer YOUR_API_KEY header.

Keep your API Key secret — treat it like a password, and never put it in front-end/browser code.

Base URL: https://server.hellorep.ai

Option A — Look up one shopper's conversations

Returns all conversations for a single email address.

GET /external/v1/conversations

Parameters:

  • account_key(required) — your Account Key.

  • email(required) — the shopper's email address.

  • offset(optional) — number of records to skip (default 0).

  • limit(optional) — page size (default 50, max 250).

curl -X GET "https://server.hellorep.ai/external/v1/conversations?account_key=YOUR_ACCOUNT_KEY&email=shopper@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Option B — Export conversations by date range

Returns all conversations whose start time falls within a UTC date range.

GET /external/v1/conversations/export

Parameters:

  • account_key(required) — your Account Key.

  • from(required) — start of range, UTC. Full timestamp (2026-05-01T00:00:00Z) or date only (2026-05-01, treated as start of that day UTC).

  • to(required) — end of range, UTC. Same formats. Must be later than from.

  • topics(optional) — comma-separated list of conversation topics. These are the topics Rep's AI assigns to conversations, and they are specific to your store, so there is no universal list. Use the exact topic names as they appear in the topic filter on your Console's Conversations page. Up to 50 values.

  • satisfactions(optional) — comma-separated customer-satisfaction values. This is a fixed set of exactly three values: SATISFIED, NEUTRAL, or DISSATISFIED (case-insensitive). Up to 50 values.

  • cursor(optional) — the nextCursor value from your previous response, to fetch the next page.

  • limit(optional) — page size (default 100, max 200).

Filters combine with the date range — for example topics and satisfactions together returns only conversations that match both inside the window.

Example — export May 2026, only satisfied conversations:

curl -X GET "https://server.hellorep.ai/external/v1/conversations/export?account_key=YOUR_ACCOUNT_KEY&from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z&satisfactions=SATISFIED" \
  -H "Authorization: Bearer YOUR_API_KEY"

What comes back:

  • result — the list of conversations (same shape as Option A: full transcript, shopper details, location, page visits, add-to-carts, order info, labels).

  • hasMore — true if there are more pages to fetch.

  • nextCursor — token to pass back as cursor for the next page; null on the last page.

  • fromUtc / toUtc — the exact UTC window we used.

  • clamped — true if your from was older than 1 year and was moved to the 1-year boundary.

  • clampedFromUtc — the original from you requested, when clamping was applied (otherwise null).

Timestamps inside each conversation (start time, end time, message times) are Unix epoch milliseconds in UTC.

Paging through large exports

  1. Make your first request with from, to, and any filters.

  2. If hasMore is true, take nextCursor and send it as the cursor parameter on your next request.

  3. Repeat until hasMore is false.

Keep your filters identical while paging. A cursor is tied to the exact from, to, topics, satisfactions, and limit it was created with. If you change any of them mid-export, the cursor is rejected and you will need to restart from the first page.

Fair-use limits

Bulk export is rate-limited per API key to keep things fast for everyone. If you go over, you will get an HTTP 429 response with a Retry-After header (in seconds) and a retryAfterSeconds field telling you how long to wait before retrying. Build a short pause-and-retry into your integration and you will never notice it in normal use.

Troubleshooting

  • 401 "Missing Authorization header" — no API key sent. Add the Authorization: Bearer YOUR_API_KEY header.

  • 401 "Invalid API key for account…" — key and Account Key do not match. Re-copy both from Settings → API Keys.

  • 400 "Missing account_key / from / to…" — a required parameter is missing. Include all required parameters.

  • 400 "Invalid date format…" — date is not valid ISO-8601 UTC. Use 2026-05-01 or 2026-05-01T00:00:00Z.

  • 400 "'from' must be earlier than 'to'" — range is backwards or empty. Make sure from is before to.

  • 400 "'to' must be within the 1-year historical horizon" — the whole range is older than 1 year. Choose a range within the last 12 months.

  • 400 "Invalid satisfaction value…" — a satisfaction value is not one of SATISFIED, NEUTRAL, DISSATISFIED. Use one of those.

  • 400 "cursor does not match the request filters…" — filters changed mid-export. Restart paging from the first page.

  • 429 Rate limit exceeded — too many requests too quickly. Wait the seconds in Retry-After, then retry.

For first-time API setup and the full list of other API capabilities (catalog sync, order events, and more), see the help article "Connect Your Non-Shopify Website to Rep AI with Our Backend Integration."

Powered by Zendesk