User Data Export APIs

The User Data Export API allows you to retrieve comprehensive user data stored in OpenDialog. This enables third-party applications to access user information, attributes, and complete conversation histories for analysis, compliance, and integration purposes.

Overview

The User Data Export endpoint provides access to all user data collected during interactions with your conversational application, including:

User profile information and attributes
Complete conversation history with timestamps
Message metadata and interaction details
Request/response logs for audit trails

The endpoint returns paginated results, allowing you to retrieve large datasets in manageable chunks. All requests are secured with API token authentication and protected by rate limiting.

Export User Data

Retrieve comprehensive user data within a specified date range with optional pagination.

Endpoint: GET /public/api/user-data-export

Authentication: API Token required

Headers:

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Query Parameters:

from (optional, string) - Start date for the export range (format: YYYY-MM-DD HH:MM:SS). Required if to is provided.
to (optional, string) - End date for the export range (format: YYYY-MM-DD HH:MM:SS). Required if from is provided.
exportType (required, string) - Export format type. Currently only json is supported.
perPage (optional, integer) - Number of records per page (default: 20)
page (optional, integer) - Page number for pagination (default: 1)

Example Request:

GET /public/api/user-data-export?from=2023-03-01%2000:00:00&to=2023-03-01%2023:59:59&exportType=json&perPage=100&page=1

Response:

{
  "data": [
    {
      "user_12345": {
        "chatbot_user_data": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "external_id": "ext_123",
          "ip_address": "192.168.1.100",
          "country": "United States",
          "browser_language": "en-US",
          "os": "Windows",
          "browser": "chrome 112.0.0",
          "timezone": "America/New_York",
          "custom": {
            "selected_scenario": "customer_support",
            "language": "en"
          }
        },
        "user_attributes": [
          {
            "name": "first_seen",
            "type": "attribute.core.timestamp",
            "value": {
              "scalar_value": 1683037966
            }
          },
          {
            "name": "last_seen",
            "type": "attribute.core.timestamp",
            "value": {
              "scalar_value": 1683037966
            }
          }
        ],
        "interactions": [
          {
            "author": "them",
            "type": "text",
            "date": "2023-05-02T14:32:50.000000Z",
            "text": "Hello! How can I help you today?",
            "data": {
              "text": "Hello! How can I help you today?",
              "disable_text": false,
              "internal": false,
              "hidetime": false,
              "hideavatar": false,
              "time": "02:32 PM",
              "date": "Tue 2 May",
              "attribute_name": null,
              "meta": []
            },
            "request": {
              "url": "https://workspace.cloud.opendialog.ai/incoming/webchat",
              "source_ip": "192.168.1.100"
            },
            "response": {
              "http_status": 200,
              "request_length": "0.760402"
            }
          },
          {
            "author": "user_12345",
            "type": "text",
            "date": "2023-05-02T14:32:55.000000Z",
            "text": "I need help with my order",
            "data": {
              "text": "I need help with my order"
            },
            "request": {
              "url": "https://workspace.cloud.opendialog.ai/incoming/webchat",
              "source_ip": "192.168.1.100"
            },
            "response": {
              "http_status": 200,
              "request_length": "0.521048"
            }
          }
        ]
      }
    }
  ],
  "meta": {
    "pagination": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 1,
      "perPage": 20,
      "to": 1,
      "total": 1
    },
    "filters": {
      "exportType": "json",
      "perPage": "20",
      "page": "1",
      "from": "2023-03-01T00:00:00.000000Z",
      "to": "2023-03-01T23:59:59.000000Z"
    }
  }
}

Response Structure:

The response contains two main sections:

data - Array of user objects:

Each object key is the user ID
chatbot_user_data - User profile information collected by the chatbot:
- Basic info: first_name, last_name, email, external_id
- Device/location: ip_address, country, browser_language, os, browser, timezone
- Custom attributes: scenario-specific attributes
user_attributes - Built-in OpenDialog attributes and scenario-specific attributes:
- Each attribute has: name, type, and value
- Includes timestamps for first_seen and last_seen
interactions - Complete conversation history:
- author: “them” (bot) or user_id (user message)
- type: Message type (text, button_response, form_response, etc.)
- date: ISO 8601 timestamp
- text: Message content
- data: Additional interaction metadata
- request: Request details (URL, source IP)
- response: Response details (HTTP status, request length)

meta - Pagination and filter metadata:

pagination: Current page info, total pages, total records
filters: Applied request filters for reference

Query Parameters Details

Date Filtering

Both from and to parameters must be provided together to filter by date:

GET /public/api/user-data-export?from=2024-01-01%2000:00:00&to=2024-01-31%2023:59:59&exportType=json

Date format: YYYY-MM-DD HH:MM:SS (24-hour format)

Pagination

Use perPage and page parameters to control pagination:

GET /public/api/user-data-export?exportType=json&perPage=50&page=2

Default perPage: 20
Default page: 1
Maximum recommended perPage: 100-500 (depending on data volume)

Export Type

Currently only JSON export is supported:

GET /public/api/user-data-export?exportType=json

Use Cases

Export user data for data subject access requests:

GET /public/api/user-data-export?from=2024-01-01%2000:00:00&to=2024-01-31%2023:59:59&exportType=json&perPage=100&page=1

Conversation Analytics

Analyze user interactions and conversation patterns:

GET /public/api/user-data-export?from=2024-01-15%2000:00:00&to=2024-01-16%2023:59:59&exportType=json&perPage=200

Quality Assurance

Review conversations for training and quality monitoring:

GET /public/api/user-data-export?exportType=json&perPage=50

System Integration

Export data for CRM, data warehouse, or analytics platform integration:

GET /public/api/user-data-export?from=2024-01-01%2000:00:00&to=2024-12-31%2023:59:59&exportType=json&perPage=100

User Data Portability

Provide users with their complete data history:

GET /public/api/user-data-export?exportType=json

Error Responses

400 Bad Request

{
  "message": "Invalid date format. Expected format: YYYY-MM-DD HH:MM:SS"
}

401 Unauthorized

{
  "message": "Unauthenticated."
}

422 Unprocessable Entity - Missing Required Parameters

{
  "message": "The given data was invalid.",
  "errors": {
    "exportType": ["The export type field is required."],
    "to": ["The to field is required when from is present."]
  }
}

422 Unprocessable Entity - Invalid Parameter

{
  "message": "The given data was invalid.",
  "errors": {
    "exportType": ["The export type must be json."],
    "perPage": ["The per page must be an integer."]
  }
}

429 Too Many Requests

{
  "message": "Too many export requests. Please try again later."
}

500 Internal Server Error

{
  "error": "An error occurred while processing your export request."
}

Best Practices

Rate Limiting

Be aware that the endpoint has rate limiting to prevent abuse
Space out requests if making multiple exports
Consider caching results to minimize repeated requests
Batch export requests during off-peak hours for large datasets

Pagination Strategy

Use reasonable perPage values (50-100 recommended)
For large datasets, implement progressive pagination
Monitor response times and adjust perPage accordingly
Store pagination state to resume interrupted exports

Date Range Filtering

Use narrow date ranges for faster queries
Export data incrementally rather than all-at-once
Schedule regular exports to keep data current
Consider time zones when filtering by date

Data Privacy

Access only data you need for your use case
Implement proper access controls on exported data
Comply with data protection regulations (GDPR, CCPA, etc.)
Securely store and transmit exported data
Delete data when no longer needed

Example Usage

Python Example

import requests
from datetime import datetime, timedelta

# Configuration
base_url = "https://your-workspace.cloud.opendialog.ai"
api_token = "YOUR_API_TOKEN"
headers = {
    "Authorization": f"Bearer {api_token}",
    "Accept": "application/json"
}

# Export user data
params = {
    "from": "2024-01-01 00:00:00",
    "to": "2024-01-31 23:59:59",
    "exportType": "json",
    "perPage": 50,
    "page": 1
}

response = requests.get(
    f"{base_url}/public/api/user-data-export",
    headers=headers,
    params=params
)

if response.status_code == 200:
    data = response.json()
    users = data['data']
    pagination = data['meta']['pagination']

    print(f"Retrieved {len(users)} user(s)")
    print(f"Page {pagination['currentPage']} of {pagination['lastPage']}")

    for user_data in users:
        for user_id, user_info in user_data.items():
            print(f"User: {user_id}")
            print(f"Email: {user_info['chatbot_user_data'].get('email')}")
            print(f"Interactions: {len(user_info['interactions'])}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

cURL Example

# Export user data for a specific date range
curl -X GET \
  'https://your-workspace.cloud.opendialog.ai/public/api/user-data-export?from=2024-01-01%2000:00:00&to=2024-01-31%2023:59:59&exportType=json&perPage=50' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

# Export all user data (no date filter)
curl -X GET \
  'https://your-workspace.cloud.opendialog.ai/public/api/user-data-export?exportType=json&perPage=100&page=1' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

# Paginate through results
curl -X GET \
  'https://your-workspace.cloud.opendialog.ai/public/api/user-data-export?exportType=json&perPage=50&page=2' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

JavaScript Example

const exportUserData = async () => {
  const baseUrl = 'https://your-workspace.cloud.opendialog.ai';
  const apiToken = 'YOUR_API_TOKEN';

  const params = new URLSearchParams({
    from: '2024-01-01 00:00:00',
    to: '2024-01-31 23:59:59',
    exportType: 'json',
    perPage: 50,
    page: 1
  });

  try {
    const response = await fetch(`${baseUrl}/public/api/user-data-export?${params}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${apiToken}`,
        'Accept': 'application/json'
      }
    });

    if (response.ok) {
      const data = await response.json();
      console.log('Users:', data.data);
      console.log('Pagination:', data.meta.pagination);

      // Process each user
      data.data.forEach(userObj => {
        Object.entries(userObj).forEach(([userId, userInfo]) => {
          console.log(`User: ${userId}`);
          console.log(`Interactions: ${userInfo.interactions.length}`);
        });
      });
    } else {
      console.error('Error:', response.status);
      console.error(await response.json());
    }
  } catch (error) {
    console.error('Request failed:', error);
  }
};

exportUserData();

Data Export Workflow

A typical data export workflow:

Prepare Request: Define date ranges and pagination parameters
Make Request: Call the API with required parameters
Handle Response: Process the returned data
Check Pagination: Determine if additional pages exist
Loop Through Pages: Fetch remaining pages if needed
Process Data: Transform or store the exported data
Audit Log: Log the export for compliance purposes

Notes

The last_seen attribute may be filtered from responses for privacy
Date format is strict: must be YYYY-MM-DD HH:MM:SS with spaces
The from and to parameters work together for filtering
Pagination metadata helps you determine how many requests are needed
Rate limiting is applied to prevent abuse
API token must have appropriate permissions to export data