How to Export Data from Crisp: Methods, API Limits & Formats

How to Export Data from Crisp: Methods, API Limits & Formats

Last verified against Crisp REST API v1, June 2025. Endpoint paths, rate limit tiers, and UI export behavior confirmed against current documentation and live API responses.

Crisp lets you export contact profiles as CSV directly from the dashboard, but conversation data cannot be exported natively — it requires the REST API or a third-party tool. This asymmetry is the single most important thing to understand before planning any Crisp data export, migration, or backup. (help.crisp.chat)

What Data Can You Export from Crisp?

Crisp's data model centers on Conversations (called sessions), People (contact profiles), Operators, Helpdesk Articles (knowledge base), Campaigns, and Inboxes. The exportability of each object depends entirely on the method you use.

[For engineering] The messages endpoint silently omits the original field for email-originated messages. To get the full original HTML of an email, you need a separate call to GET /v1/website/{id}/conversation/{session}/original/{original_id} per message. This is not documented prominently and will cause data loss if missed during migration. In practice, we've seen workspaces where 30–40% of conversations originate from email — skipping the original endpoint means losing formatted HTML, inline images referenced by CID, and email headers (From, Reply-To, CC) that may be critical for audit trails.

If you use Crisp's Ticket Center, tickets are stored as regular conversations — there is no separate ticket export object. (help.crisp.chat)

Export Methods: Every Way to Get Data Out of Crisp

Crisp does not offer direct database access or a Google Takeout-style data download. There are five real export paths:

[For PMs] The native UI export requires zero engineering — contact CSVs, shortcut CSVs, analytics CSVs, and per-conversation transcripts are all self-serve. Everything involving full chat history, attachments, assignee mapping, or knowledge base structure needs developer time or a managed partner. (help.crisp.chat)

Native UI Exports: What You Can Do Without Code

Crisp provides several self-serve export options from the dashboard. None of them cover bulk conversation history.

Export Contact Profiles

1. Log in to app.crisp.chat
2. Navigate to the Contacts tab
3. Click Actions (upper right corner) → Export Contact Profiles
4. Wait for the export to process — you'll receive an email notification when it's ready

Crisp supports All contacts, Filtered contacts, and Selected contacts exports. Manual multi-select is capped at 100 contacts at a time. (help.crisp.chat)

What you get: A CSV file containing email, nickname, phone, address, company, segments, custom data keys, and timestamps.

What's missing: Conversation history linked to each contact is not included — you get the profile, not the chat transcripts. Custom data values are flattened into the CSV; nested JSON objects lose their structure. The export is capped at 200,000 contacts.

Export Message Shortcuts

Go to Settings → Inbox Settings → Message Shortcuts → ... → Export. Crisp downloads your shortcuts as CSV, including the bang trigger, the shortcut text, and the optional tag. If you plan to round-trip edits back into Crisp later, keep the file UTF-8. (help.crisp.chat)

Export Analytics Reports

Open Analytics, choose the report you need, then use the report action menu and click Export Data. This covers response-time, resolution-time, ratings, conversation volume, and other metrics — but it is not a replacement for raw message export. Deleted conversations may still count in some reports, and spam conversations are excluded. (help.crisp.chat)

Export Individual Transcripts

Open a conversation, use the action menu, then click Send transcript. Crisp can also send transcripts automatically after a conversation becomes inactive, but this is per-conversation delivery — not a bulk export mechanism.

API-Based Export: Endpoints, Pagination, and Rate Limits

[For Engineering] The Crisp REST API (V1) at https://api.crisp.chat/v1/ provides read access to every core object. There is no dedicated "bulk export" endpoint — you paginate through list endpoints and fan out to messages, files, and metadata per conversation.

Authentication

Crisp offers two authentication methods:

• Website Tokens: Generated from your Crisp workspace settings. Best for single-workspace scripts. No Marketplace account required.
• Plugin Tokens: Generated via the Crisp Marketplace. Support multi-workspace access, configurable daily quotas, and fine-grained token scopes.

Both use HTTP Basic Auth with an identifier and key pair. Plugin tokens also require the X-Crisp-Tier: plugin header. (docs.crisp.chat)

Core Endpoints

• List Conversations: GET /v1/website/{website_id}/conversations/{page_number} with per_page=20..50
• Get Conversation: GET /v1/website/{website_id}/conversation/{session_id}
• Get Messages: GET /v1/website/{website_id}/conversation/{session_id}/messages
• List Files: GET /v1/website/{website_id}/conversation/{session_id}/files/{page_number}
• Get Original Email: GET /v1/website/{website_id}/conversation/{session_id}/original/{original_id}
• List People: GET /v1/website/{website_id}/people/profiles/{page_number}
• Get People Data: GET /v1/website/{website_id}/people/data/{people_id}
• People Events: GET /v1/website/{website_id}/people/events/{people_id}/list/{page_number}
• List Operators: GET /v1/website/{website_id}/operators/list
• List Inboxes: GET /v1/website/{website_id}/inboxes/list/{page_number}
• Helpdesk Articles: GET /v1/website/{website_id}/helpdesk/locale/{locale}/articles/{page_number}

A migration-grade export usually pulls more than one endpoint per object. Crisp stores people profiles, people data, and people events as separate resources — one contact endpoint does not equal a full customer record. (docs.crisp.chat)

Pagination

Conversations use page-number pagination. The List Conversations endpoint accepts page_number in the URL path and per_page as a query parameter (between 20 and 50, defaulting to 20). A 206 Partial Content response indicates more pages are available; a 200 OK response indicates the final page.

Messages within a conversation use timestamp-based cursor pagination via the timestamp_before parameter. Each call returns a batch of messages; you pass the earliest timestamp from the current batch as timestamp_before in the next call to page backward through history.

People profiles also use page-number pagination with the same 20–50 per-page range.

This creates an N+1 extraction pattern: you first list conversation pages, then make individual requests for each conversation's messages. There is no way to request a bulk dump of all messages across all conversations in a single call.

Rate Limits

Crisp uses a multi-level rate limiting system:

Key detail: Plugin tokens are exempt from API Global and API Route per-minute rate limits. They can send bursts of requests without triggering per-minute throttling. They are only constrained by a daily quota — 5,000 requests/day by default — that can be increased by request through the Marketplace. Website tokens have a default daily quota of 10,000 requests/day but are also subject to per-minute route limits. (docs.crisp.chat)

When you hit a limit, the API returns 429 Too Many Requests or 420 Enhance Your Calm. There is no documented Retry-After header — you must implement exponential backoff. In practice, a 5-second initial backoff with doubling (5s → 10s → 20s → 40s → 60s cap) handles both per-minute and daily-quota scenarios. When you receive a 420 close to midnight UTC, waiting for the daily quota reset is more efficient than backing off indefinitely.

Observed Failure Modes During Large Exports

Beyond documented limits, these are failure patterns that emerge during real extraction runs:

• Mid-pagination 500 errors: The List Conversations endpoint occasionally returns HTTP 500 on pages in the 800–1,200 range for workspaces with 50K+ conversations. These are transient — retry with backoff resolves them, but your script must handle mid-run failures without restarting from page 1. Checkpoint the last successful page number.
• Empty message arrays on valid sessions: Some conversations (particularly those created by automated triggers or bot interactions) return an empty messages array despite having a non-zero messages_count in the conversation metadata. These are typically system-generated sessions with no user-visible content.
• Timestamp collision in cursor pagination: When multiple messages share the exact same millisecond timestamp (common in bot-generated rapid-fire messages), the timestamp_before cursor can enter an infinite loop returning the same batch. Detect this by comparing the full message set between iterations, not just the oldest timestamp.
• CDN file URL accessibility: Files on storage.crisp.chat remain accessible as long as the workspace exists and the conversation hasn't been deleted. We have not observed URL expiration on active workspaces, but files from deleted conversations return 404. Download attachments during export rather than relying on URL persistence post-migration.
• Deleted operator ghost references: Messages sent by operators who were later removed from the workspace retain their user_id but return no matching entry from the operators list endpoint. Your export must handle orphaned operator IDs gracefully — map them to a "Deleted Agent" placeholder or preserve the raw ID for audit purposes.

Export Code Example (Python)

import requests
import time
import json
import os
 
WEBSITE_ID = "your_website_id"
BASE_URL = f"https://api.crisp.chat/v1/website/{WEBSITE_ID}"
HEADERS = {
    "Authorization": "Basic YOUR_BASE64_TOKEN",
    "X-Crisp-Tier": "plugin"  # or "website"
}
CHECKPOINT_FILE = "export_checkpoint.json"
 
def load_checkpoint():
    if os.path.exists(CHECKPOINT_FILE):
        with open(CHECKPOINT_FILE) as f:
            return json.load(f)
    return {"last_page": 0, "completed_sessions": []}
 
def save_checkpoint(state):
    with open(CHECKPOINT_FILE, "w") as f:
        json.dump(state, f)
 
def api_get(path, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(f"{BASE_URL}{path}", headers=HEADERS)
        if response.status_code in (429, 420):
            wait = min(60, (2 ** attempt) * 5)
            print(f"Rate limited on {path}, waiting {wait}s (attempt {attempt+1})")
            time.sleep(wait)
            continue
        if response.status_code == 500:
            wait = min(60, (2 ** attempt) * 3)
            print(f"Server error on {path}, retrying in {wait}s")
            time.sleep(wait)
            continue
        response.raise_for_status()
        return response.json().get("data", [])
    raise Exception(f"Failed after {max_retries} retries: {path}")
 
def export_messages(session_id):
    all_messages = []
    timestamp_before = None
    prev_message_ids = set()
 
    while True:
        path = f"/conversation/{session_id}/messages"
        if timestamp_before:
            path += f"?timestamp_before={timestamp_before}"
 
        messages = api_get(path)
        if not messages:
            break
 
        # Detect timestamp collision loop
        current_ids = {m.get("fingerprint", m["timestamp"]) for m in messages}
        if current_ids == prev_message_ids:
            break
        prev_message_ids = current_ids
 
        all_messages.extend(messages)
        oldest = min(m["timestamp"] for m in messages)
 
        if timestamp_before == oldest:
            break
        timestamp_before = oldest
        time.sleep(0.1)
 
    return all_messages
 
def export_all_conversations():
    checkpoint = load_checkpoint()
    page = checkpoint["last_page"] + 1
    completed = set(checkpoint["completed_sessions"])
 
    while True:
        convos = api_get(f"/conversations/{page}?per_page=50")
        if not convos:
            break
 
        for convo in convos:
            session_id = convo["session_id"]
            if session_id in completed:
                continue
 
            messages = export_messages(session_id)
 
            # Write each conversation to disk immediately
            with open(f"export/{session_id}.json", "w") as f:
                json.dump({"session": convo, "messages": messages}, f)
 
            completed.add(session_id)
 
        save_checkpoint({"last_page": page, "completed_sessions": list(completed)})
 
        if len(convos) < 50:
            break
        page += 1
        time.sleep(0.2)

This matches Crisp's actual paging model: conversations use numeric pages with per_page capped at 50, while messages page by timestamp. Key production features: checkpoint/resume support (critical for multi-day extractions that will hit daily quotas), per-conversation disk writes instead of in-memory accumulation, timestamp collision detection, and transient 500 error handling. In a full production script, add file enumeration per session, people data joins, and original email fetching for email-originated messages.

Throughput Math

At the documented default quotas, a website token gets roughly 10,000 requests/day and a default plugin token gets 5,000 requests/day. Here's what that means in practice:

100,000 conversations with message history requires at minimum ~102,000 API requests — 2,000 list calls at 50 conversations per page plus 100,000 message calls (one per conversation, assuming single-page message histories). At the default website token quota, that's roughly 10 days of extraction time. At the default plugin token quota, roughly 20 days. Add one file-list call per conversation and the lower bound jumps to ~202,000 requests. (docs.crisp.chat)

Real-world multipliers that increase request count:

• Conversations with 100+ messages require 2–5 message pagination calls each (not 1)
• Email-originated conversations add 1 original call per email message
• People data enrichment adds 1–2 calls per unique contact
• Transient errors and retries add 5–15% overhead
• A workspace with 100K conversations, 30% email-originated, averaging 15 messages each, realistically requires 250,000–350,000 API requests

Plugin tokens can burst faster within a day since they skip per-minute route limits, but the daily quota is the binding constraint for multi-day extractions. Request a quota increase before starting any large export.

Exporting Attachments and Files

Crisp does not bundle attachments into a downloadable archive. Files shared in conversations are embedded within messages as type: "file" objects containing a url, name, and MIME type.

To export attachments:

1. Extract all messages from conversations via the API
2. Filter for messages where type equals file, animation, or audio
3. Download each file from its url field — these are hosted on Crisp's CDN (typically storage.crisp.chat)
4. Alternatively, use the dedicated List Conversation Files endpoint (GET /v1/website/{id}/conversation/{session}/files/{page}) for a paginated list of all files in a conversation without parsing message payloads

Practical considerations:

• There is no bulk attachment download endpoint
• Inline images pasted into messages are stored as separate file messages and must be downloaded individually
• CDN URLs on storage.crisp.chat remain accessible while the workspace and conversation exist. Files from deleted conversations return 404. We have not observed time-based URL expiration on active workspaces, but download files during export rather than relying on post-migration URL persistence
• Aggressive concurrent downloads (>10 parallel requests) may trigger CDN-level rate limiting — use a semaphore or connection pool capped at 5–8 concurrent downloads
• If migrating to another platform, you must re-host these files so the destination API can ingest them. Crisp file URLs become permanently inaccessible if you close your Crisp workspace

If email fidelity matters, also capture the original email object via GET /v1/website/{id}/conversation/{session}/original/{original_id}. This returns the original MIME type, headers, and stored content — the correct source when you need original HTML rather than the rendered thread.

Exporting Knowledge Base Articles

Crisp provides an API-triggered export for helpdesk articles at POST /v1/website/{website_id}/helpdesk/locale/{locale}/export. This sends the exported articles to the requester's email.

For programmatic extraction with full control, use the read endpoints:

1. GET /v1/website/{id}/helpdesk/locales/{page} — list all locales
2. GET /v1/website/{id}/helpdesk/locale/{locale}/articles/{page} — list articles per locale
3. GET /v1/website/{id}/helpdesk/locale/{locale}/article/{article_id} — get full article content (title, description, content, status, visibility)
4. GET /v1/website/{id}/helpdesk/locale/{locale}/categories/{page} — list categories
5. GET /v1/website/{id}/helpdesk/locale/{locale}/category/{category_id}/sections/{page} — list sections within categories

Article content is returned as a text string. Category–section–article relationships must be reconstructed from the category_id and section_id fields on each article. HTML formatting in articles requires parsing before import into markdown-based systems (e.g., Intercom Articles, Notion, or static site generators).

What Data Cannot Be Exported from Crisp

Be realistic about what you won't get. These objects or data types have no export path or incomplete coverage:

The Chatbot and Automation Portability Gap

[For CTOs] The biggest export gap is chatbot and automation logic. If your team has invested in Crisp's Hugo AI bot, custom chatbot scenarios, or workflow automations, that configuration does not export through any supported mechanism.

What Hugo AI / chatbot scenarios contain that you'll lose:

• Decision tree structures (branching logic, conditional paths)
• Trigger conditions (URL patterns, visitor segment rules, time-based triggers)
• Response templates and rich message formats (carousels, pickers, buttons)
• Handoff rules (when to escalate to a human operator and which inbox)
• Training data and intent configurations for Hugo AI

What you can partially reconstruct:

• Screen-record or screenshot every scenario flow in the Crisp dashboard before cancellation
• Document trigger conditions, branching logic, and response text manually
• Export message shortcuts (which may overlap with bot quick replies)
• Use the Crisp API to list conversations tagged with bot-interaction metadata, which reveals what scenarios were active

Mapping to destination platforms:

• Intercom: Custom Bots / Fin AI — Intercom's bot builder uses a different visual flow model; 1:1 mapping is not possible, but the logic can be recreated
• Zendesk: Answer Bot / Flow Builder — similar branching concept, different trigger model
• Freshdesk: Freddy AI — intent-based rather than flow-based; requires rethinking the bot architecture
• Gorgias: Rules + Macros — no visual bot builder; Crisp bot flows must be decomposed into flat automation rules

Budget 2–5 days of product/engineering time to rebuild a moderately complex chatbot (10–20 scenarios) in any destination platform. Complex Hugo AI setups with trained intents may require 1–2 weeks.

Data Format, Encoding, and Cleanup After Export

Crisp exports contacts as CSV (comma-separated, UTF-8). API responses are JSON (UTF-8). Here are the common cleanup issues:

Timestamps: All API timestamps are Unix epoch in milliseconds (13-digit integer, e.g., 1718366400000, not 10-digit seconds). Most destination platforms like Zendesk, Intercom, or HubSpot require ISO 8601 formatted strings (e.g., 2025-06-14T12:00:00Z). You must transform all timestamp fields before importing. In Python: datetime.utcfromtimestamp(ts / 1000).isoformat() + "Z".

Message content shape: Crisp documents messages.content as a string for text and note types, but as an object for file, animation, audio, picker, field, carousel, and event types. A flat CSV transform fails here — typed JSON normalization works better. (docs.crisp.chat)

HTML in email messages: Email-originated messages contain HTML. The plain text is in the content field; the original HTML requires a separate call to the original endpoint.

Custom data: The data field on people profiles and conversations is a freeform JSON object. CSV exports flatten these keys, which can cause column explosion with varied schemas across contacts. A workspace with 50 different custom data keys across 100K contacts produces a CSV with 50+ extra columns, most of which are null for any given row. Use the API if you need to preserve exact data types and structure.

Segments: Stored as string arrays on both conversations and people profiles. In CSV exports, segments are pipe-delimited (e.g., vip|enterprise|churned).

Orphan sessions: People profiles are deduplicated by email in Crisp, but conversations can have anonymous visitors without an email. These sessions will appear in conversation exports but won't link to a people profile via people_id. In a typical B2C workspace, 20–40% of conversations may be anonymous.

[For PMs] Post-export validation checklist:

• Verify total conversation count matches the Crisp dashboard's reported number
• Confirm message counts per conversation against a random sample of 20–50 conversations
• Check that file/attachment URLs are accessible and download correctly
• Validate that all custom data keys are present in exported JSON
• Ensure timestamps convert correctly to your target platform's format
• Verify people–conversation linkage via people_id — count orphaned sessions
• Spot-check the 20–50 longest conversations end-to-end for completeness
• Compare resolved, unresolved, and pending state distributions against Crisp dashboard analytics
• Check inbox and assignee mappings against the operators list
• Verify operator IDs on messages match entries from the operators endpoint — flag orphaned IDs from deleted agents
• For email-originated conversations, confirm that original endpoint data was captured

Export for Migration vs. Backup vs. Compliance

The reason you're extracting data dictates how you shape the output.

Migration

When moving to another platform (Intercom, Zendesk, Freshdesk, Gorgias), you need:

• Conversations with full message history, preserving from (user/operator), timestamp, and type
• Contact profiles mapped to the destination's contact model
• Attachments downloaded and re-uploaded to the target platform's storage
• ID mapping tables to link source session IDs to destination ticket IDs
• Knowledge base articles with category hierarchy preserved
• Operator data for assignee mapping

Crisp's chat-session model is structurally different from ticket-based platforms. A Crisp "conversation" maps to a single continuous thread; there are no separate ticket fields like priority, SLA timers, or custom ticket fields. Crisp conversations have three states (resolved, unresolved, pending) vs. the richer status models in ticket systems (new, open, pending, on-hold, solved, closed). This requires transformation during migration, not just export.

For how this mapping works in practice, see our Crisp to Gorgias migration guide — which covers state mapping, tag-to-tag translation, and attachment re-hosting — or our Crisp to Intercom migration guide.

Backup

A full-fidelity backup requires:

• Complete people profile export (CSV + API for custom data and events)
• All conversations with all messages (API only)
• All attachments downloaded to local or cloud storage
• Knowledge base articles per locale
• Website settings and inbox configurations
• Campaign definitions and templates
• Operator list with roles and assignments

Crisp does not offer scheduled or automated backup exports. Store the raw JSON payloads exactly as the API returns them. Do not transform the data during backup — transformations risk data loss. Build and schedule your own scripts. A weekly incremental backup (new conversations since last run, filtered by updated_timestamp) is more practical than repeated full extractions.

Compliance (GDPR / DSAR)

Crisp is a French company (Crisp IM SAS) and stores all data on EU servers (OVHcloud data centers in Netherlands and Germany). For GDPR Article 20 data portability requests, Crisp's privacy policy states that users "may contact us anytime if they wish to get an export of their data" but notes that "this may take time, however, as the data is fragmented amongst multiple isolated data-stores." (crisp.chat/en/privacy)

For Data Subject Access Requests, you can use the People API to search for a specific person's profile by email and export their data and linked conversations programmatically — this is faster than waiting for Crisp's manual process. The flow:

1. GET /v1/website/{id}/people/profile/{people_id} — retrieve the full profile
2. GET /v1/website/{id}/people/data/{people_id} — retrieve custom data
3. GET /v1/website/{id}/people/events/{people_id}/list/{page} — retrieve tracked events
4. GET /v1/website/{id}/people/conversations/{people_id}/list/{page} — retrieve linked conversations
5. For each conversation, extract full message history as described above

Do not run a full workspace extraction for a single DSAR; isolate only the specific user's data.

For more on GDPR-compliant data handling during migrations, see our GDPR Compliant Data Migration blueprint.

How Portable Is Crisp Data?

[For CTOs] Portability Rating: Mostly Portable

The real switching cost from Crisp is engineering time, not data lock-in. Your data is accessible, but Crisp makes you work for it. There's no "Download All My Data" button, no bulk export file, no data takeout feature. Everything beyond contacts requires API scripting.

Crisp's terms of service do not restrict data export. There are no contractual barriers to extracting your data, and the API is available on all paid plans (Essentials and above). The N+1 pagination structure makes high-volume extraction slow — pulling years of chat history takes days to weeks at default quotas — but it doesn't prevent it.

Timeline and Resourcing for a Full Data Export

[For PMs] Exporting full conversation histories from Crisp is an engineering project. Small UI exports finish in minutes; full conversation exports scale by quota, fan-out, and validation effort.

Phase breakdown:

1. Scoping (2–4 hours): Inventory objects, count records via dashboard, identify custom data keys, estimate API request count
2. API setup (1–2 hours): Generate tokens, test authentication, verify scopes. Request a quota increase if you're above 10K conversations — Crisp support typically responds within 1–2 business days.
3. Script development (1–3 days): Build pagination logic, checkpoint/resume, error handling, retry logic, attachment downloads, original email fetching
4. Extraction (hours to days): Run export scripts — duration depends on volume, rate limits, and quota. Monitor daily quota consumption and adjust pacing.
5. Validation (2–8 hours): Sample checks, count verification, attachment spot-checks, orphan session audit
6. Cleanup (2–4 hours): Deduplicate, normalize timestamps, flatten custom data for destination format

The math that changes project plans: 100,000 conversations with message history alone requires ~102,000 API requests at minimum (assuming every conversation's messages fit in one page). Real-world multipliers push this to 250,000–350,000 requests. At the default 10,000 requests/day website token quota, that's 25–35 days of extraction time. Request a quota increase before you start. (docs.crisp.chat)

Getting Your Data Out of Crisp

If your goal is a quick spreadsheet export, Crisp gives you enough UI tooling for contacts, shortcuts, analytics, and one-off transcripts. If your goal is a migration-grade data export covering conversations, attachments, and knowledge base content, treat it as an API extraction project with object-by-object scoping, rate limit management, checkpoint/resume logic, attachment hydration, and post-export validation.

The non-negotiable steps for any full export:

1. Inventory your data objects and volumes in the Crisp dashboard
2. Request a rate limit quota increase from Crisp support if you have >10K conversations
3. Build or acquire extraction scripts with checkpoint/resume capability
4. Run extraction, monitoring daily quota usage
5. Validate exported data against dashboard counts and random samples
6. Download all attachments before closing your Crisp workspace