ConnectMeGroep Werk.nl Outreach Service - Comprehensive Documentation

1. Introduction

The Werk.nl Outreach Service is an automated solution that facilitates connecting with and messaging candidates on Werk.nl, which is a Dutch employment platform. Similar to LinkedIn's outreach capabilities but specifically adapted for the Werk.nl ecosystem, this service enables recruiters and employers to efficiently engage with potential candidates.

2. System Architecture

2.1 High-Level Component Overview

This system is built as an Apify Actor (cloud-based automation platform) with these key components:

1. Core Scraper Engine: Browser automation to interact with Werk.nl
2. Authentication System: Handles login including two-factor authentication via Telegram
3. Session Management: Persists sessions using Firebase
4. Outreach Workflow Engine: Manages the state of candidate outreach
5. Input/Output Processing: Handles structured data for candidates

2.2 Directory Structure

1/
2├── src/                       # Main source code
3│   ├── lib/                   # Utility libraries and settings
4│   ├── models/                # Data models for input/output
5│   ├── services/              # Core service implementations
6│   │   ├── BrowserAgentWerkNL/   # Browser automation implementation
7│   │   ├── SeleniumAgentWerkNL/  # Selenium-based implementation
8│   │   ├── WerkNLOutreachScraper.py # Main scraper implementation
9│   │   ├── FirebaseManager.py # Manages cookie persistence
10│   │   └── TelegramAuthHandler.py # Handles 2FA via Telegram
11│   └── main.py                # Entry point for the Apify Actor
12├── extension_unpacked/        # Unpacked Chrome extension
13├── Dockerfile                 # Container configuration
14├── requirements.txt           # Python dependencies
15└── example_input.json/output.json # Example data formats

3. Core Components

3.1 Data Models

The system uses Pydantic for data validation with these key models:

• MessageData: Stores subject and content for messages

• CandidateInput: Input structure for candidate outreach with fields:

  • candidateId: Unique identifier for the candidate
  • outreach_status: Current state of outreach ("start", "connected")
  • fullName: Candidate's name
  • werkNlUrl: URL to candidate's profile
  • message: Message data for communication

• CandidateOutput: Output structure tracking outreach results

3.2 WerkNLOutreachScraper

This is the primary engine for interacting with Werk.nl using Playwright (browser automation). Key functionalities include:

3.2.1 Authentication

• perform_login(): Handles the complete login flow
• Supports two-factor authentication through Telegram integration
• Navigates through Werk.nl's multi-step login process

3.2.2 Profile Status Management

• define_profile_status(): Determines the current relationship status with a candidate:
  • connection_unknown: Status couldn't be determined
  • connection_not_sent: No connection has been sent
  • connection_accepted: Connected with the candidate
  • connection_pending: Connection request sent but not accepted
  • connection_received: Received a connection request from the candidate

3.2.3 Messaging Capabilities

• can_send_message(): Checks if messaging is possible for a profile
• send_message_to_profile(): Sends personalized messages to connected candidates
• _type_with_delays(): Types messages with random delays for natural interaction

3.2.4 Connection Management

• send_connection_request(): Initiates connection with candidates
• accept_connection(): Accepts incoming connection requests
• run_connect_message(): Orchestrates the complete outreach workflow (connect and message)

3.3 Firebase Integration

The FirebaseManager handles persistent storage of browser cookies to maintain login sessions between runs. This avoids the need for frequent logins and 2FA.

3.4 Telegram Integration

The TelegramAuthHandler provides:

• Integration with a Telegram bot for 2FA code retrieval
• Notification capabilities to inform users about authentication status
• Secure handling of verification codes

3.5 Main Entry Point

The main.py file orchestrates the workflow:

• Initializes the Actor environment
• Configures proxy settings for reliable access
• Loads input data containing candidates
• Initializes and manages the browser automation
• Handles cookie persistence with Firebase
• Processes candidates and returns results

4. Workflow Process

4.1 Outreach Sequence

1. Initialization: Load candidate data and authentication information
2. Authentication: Login to Werk.nl (using stored cookies or credentials + 2FA if needed)
3. Candidate Processing:
   • For each candidate, determine current connection status
   • Based on status and required action, perform:
     • Send connection request
     • Send message to connected candidate
     • Accept incoming connection request
4. Status Tracking: Update candidate status after each action
5. Result Collection: Compile results and return updated candidate statuses

4.2 Outreach States

The system tracks these states for each candidate:

• start: Initial state
• connection_not_sent: No connection initiated yet
• connection_pending: Connection request sent but pending approval
• connection_received: Connection request received from candidate
• connection_accepted: Connected and ready for messaging

5. Technical Implementation Details

5.1 Browser Automation

The system uses:

• Playwright: For primary browser automation
• Selenium: Alternative implementation available in the codebase

5.2 Security Features

• Proxy Configuration: Uses residential proxies from the Netherlands
• Secure 2FA: Telegram integration for receiving verification codes
• Environment Variables: Sensitive data stored in environment variables

5.3 Container Support

The system is containerized with Docker for deployment on Apify platform.

5.4 Input/Output Interface

• Accepts structured JSON input defining candidates and actions
• Returns JSON output with updated candidate statuses
• Compatible with Apify Actor ecosystem

6. Operational Considerations

6.1 Prerequisites

• Werk.nl credentials
• Telegram bot configuration for 2FA
• Firebase configuration for cookie persistence
• Apify proxy configuration

6.2 Limitations

• Dependent on Werk.nl's interface structure
• Subject to Werk.nl's rate limiting and automation policies
• Requires proper configuration of Telegram bot for 2FA
• Network reliability affected by proxy quality

7. Usage Examples

7.1 Basic Outreach Flow

1{
2  "salesObject": {
3    "candidates": [
4      {
5        "candidateId": "7329638",
6        "outreach_status": "start",
7        "fullName": "Jan Jansen",
8        "werkNlUrl": "https://www.werk.nl/werkgevers/mijn-werknl/cvs-zoeken/7329638",
9        "message": {
10          "subject": "Connectieverzoek",
11          "content": "Hallo Jan, ik ben geïnteresseerd in je profiel. Wanneer zou je tijd hebben voor een gesprek?"
12        }
13      }
14    ],
15    "user_id": "recruiter1"
16  }
17}

This documentation provides a comprehensive overview of the Werk.nl Outreach Service, explaining its architecture, components, workflow, and operational aspects in detail.