opendialog.aiTalk to an expert

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": "[email protected]",
          "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

GDPR and Data Compliance Requests

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:

  1. Prepare Request: Define date ranges and pagination parameters

  2. Make Request: Call the API with required parameters

  3. Handle Response: Process the returned data

  4. Check Pagination: Determine if additional pages exist

  5. Loop Through Pages: Fetch remaining pages if needed

  6. Process Data: Transform or store the exported data

  7. 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

PreviousWebchat Deep Link APIsNextRelease Notes

Last updated