Skip to main content

Smart Arena Beekeeper Integration - User Guide

Updated over 2 weeks ago

Overview

The Beekeeper Chat Integration enables Smart Arena to send notifications via the Beekeeper mobile communication platform instead of (or in addition to) email. This provides real-time chat-based notifications for frontline and deskless workers who may not regularly check email.

How It Works

  1. Configure Integration: Set up your Beekeeper API credentials in Smart Arena

  2. Automatic Routing: When enabled, notifications are routed to Beekeeper chat instead of email

  3. User Matching: Users are matched by their Beekeeper username (stored in SmartArena's "Mapping Code" field)

  4. Queue Processing: Messages are queued and sent automatically every minute

  5. Delivery Options: Choose between Beekeeper-only or dual delivery (Beekeeper + email)

Prerequisites

Beekeeper Account Requirements

Before setting up this integration, you must have:

  • Active Beekeeper Account: Your organization must have an active Beekeeper subscription

  • API Access: Contact Beekeeper support to enable API access for your account

  • OAuth Access Token: Generate an API access token from your Beekeeper admin panel

  • Tenant ID: Your unique Beekeeper identifier (e.g., "mycompany" from https://mycompany.beekeeper.io)

Getting Beekeeper API Credentials

To obtain your API credentials:

  1. Log in to your Beekeeper admin dashboard

  2. Navigate to Settings → Integrations → API

  3. Click Generate New Access Token

  4. Copy the generated OAuth access token (keep it secure!)

  5. Note your Tenant ID (visible in your Beekeeper URL)

Important: Keep your access token secure. Never share it publicly or commit it to version control.

User Setup Requirements

For users to receive Beekeeper notifications:

  • Mapping Code: Each Smart Arena user must have their Beekeeper username entered in the Mapping Code field

  • Active Beekeeper Account: Users must have active accounts in your Beekeeper workspace

  • Username Match: The mapping code must exactly match the Beekeeper username (case-sensitive)

Example:

  • Beekeeper username: john.doe

  • SmartArena Mapping Code: john.doe ✅

Configuration

Step 1: Access the Beekeeper Integration Settings

  1. Log in to SmartArena as an administrator

  2. Navigate to Organizations → Manage

  3. Go to the Integrations tab

  4. Locate Beekeeper Chat Integration

  5. Click the Setup button

Step 2: Enter API Credentials

On the Beekeeper setup page, configure the following:

Beekeeper Access Token (Required)

  • Enter your OAuth access token from Beekeeper

  • This is a secure password field (token will be encrypted in the database)

  • Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... (truncated)

Tenant ID (Required)

  • Enter your Beekeeper tenant identifier

  • This is the subdomain in your Beekeeper URL

  • Example: If your URL is <https://acmecorp.beekeeper.io,> enter acmecorp

Also Send Email Notifications (Optional)

  • Toggle ON for dual delivery: Messages sent to both Beekeeper AND email

  • Toggle OFF for Beekeeper-only: Messages sent ONLY to Beekeeper (email disabled)

Best Practice:

  • During initial testing, enable "Also Send Email" to ensure users don't miss notifications

  • Once confident in the setup, disable email to reduce inbox clutter

Step 3: Test Connection

Before saving, verify your credentials:

  1. Click the Test Beekeeper Connection button

  2. Wait for the connection test to complete

  3. Verify you see "Connection Successful"

If connection fails:

  • Verify access token is correct (no extra spaces or characters)

  • Verify tenant ID matches your Beekeeper URL exactly

  • Check with Beekeeper support that API access is enabled

  • Ensure your SmartArena server can reach <https://{tenant_id}.beekeeper.io>

Step 4: Save Configuration

  1. Click the Save button

  2. Wait for confirmation: "Beekeeper integration settings saved successfully"

  3. You will be redirected to the Integrations overview page

Step 5: Activate Integration

After saving, the integration is disabled by default:

  1. On the Integrations tab, locate Beekeeper Chat Integration

  2. Toggle the switch from OFF to ON

  3. Status should change from "Not Connected" to "Connected"

Important: The integration must be toggled ON to start routing notifications to Beekeeper.

Notification Delivery

When a SmartArena notification is triggered:

  1. Check Integration: System checks if Beekeeper is enabled for the user's organization

  2. Check User: System verifies the user has a mapping code (Beekeeper username)

  3. Convert Message: HTML email content is converted to Beekeeper markdown format

  4. Queue Message: Message is added to the beekeeper_queue table

  5. Process Queue: Automated cron job runs every minute to send queued messages

  6. Send to Beekeeper: API call sends the message via Beekeeper API

  7. Delivery Confirmation: User receives chat notification in their Beekeeper mobile app

Message Format

SmartArena automatically converts email notifications to Beekeeper-compatible format:

Original Email:

Beekeeper Message:

Dual Delivery Mode

When "Also Send Email" is enabled:

  • ✅ Message sent to Beekeeper chat

  • ✅ Message sent to email

  • Users receive both notifications

When "Also Send Email" is disabled:

  • ✅ Message sent to Beekeeper chat only

  • ❌ No email sent

  • Lower email volume for users

Message Queue and Processing

Queue Processing

  • Frequency: Messages are processed every minute by an automated cron job (smartarena:send-beekeeper)

  • Batch Size: Up to 200 messages per minute

  • Prioritization: Messages are processed in order: fewest retry attempts first, then oldest first

Message States

Messages in the queue can have the following states:

Retry Logic

Smart Arena automatically retries failed messages:

  • Maximum Retries: 5 attempts

  • Retry Timing: Exponential backoff (1s, 2s, 4s, 8s, 16s between attempts)

  • Retry Reasons: Network errors, Beekeeper server errors (5xx)

  • No Retry: Authentication errors (401/403), User not found (404 - triggers username resolution)

Username Resolution

If a user is not found in Beekeeper (404 error):

  1. System attempts to resolve the username to a Beekeeper UUID

  2. If successful, the UUID is cached in the user's beekeeper_user_id field

  3. Future messages use the cached UUID for faster delivery

  4. If resolution fails, message is blocked (user doesn't exist in Beekeeper)

This automatic resolution handles cases where Beekeeper uses UUIDs internally instead of usernames.

Monitoring

Checking Integration Status

To verify the integration is working:

  1. Navigate to Organizations → Manage → Integrations

  2. Locate Beekeeper Chat Integration

  3. Check the status:

    • ✅ Connected (green): Integration is active

    • ⚠️ Not Connected (orange): Integration is configured but inactive

    • ❌ Not Configured (gray): No credentials entered

Log Monitoring

SmartArena logs all Beekeeper activity to the Laravel log:

Log Location: app/storage/logs/laravel-YYYY-month.log

Search for: SendBeekeeperCommand: or Beekeeper

Example log entries:

[2026-02-12 08:30:15] SendBeekeeperCommand: Checking for new Beekeeper messages [2026-02-12 08:30:16] Beekeeper message sent successfully to user abc123 [2026-02-12 08:30:17] SendBeekeeperCommand: Sent: 45 Failed: 2 Blocked: 0 Total: 47

Troubleshooting - Common Issues

Users Not Receiving Beekeeper Notifications

Symptoms: Users report not receiving notifications in Beekeeper

Possible Causes:

  1. Integration Not Active

    • Solution: Check integration toggle is ON in Organizations → Manage → Integrations

  2. Missing Mapping Code

    • Solution: Verify user has mapping code populated in their Smart Arena profile

    • Check: Users → Manage → Edit User → Mapping Code field

  3. Username Mismatch

    • Solution: Ensure mapping code exactly matches Beekeeper username (case-sensitive)

    • Example: John.Doe ≠ john.doe

  4. User Not in Beekeeper

    • Solution: Verify user exists in your Beekeeper workspace

    • Check Beekeeper admin panel for user list

  5. "Also Send Email" Enabled

    • Check: If users receive email but not Beekeeper, integration may not be routing correctly

    • Review logs for "Beekeeper routing skipped" messages

Connection Test Fails

Symptoms: "Connection Failed" when testing credentials

Solutions:

  1. Invalid Access Token

    • Regenerate token in Beekeeper admin panel

    • Ensure no extra spaces when copying/pasting

    • Verify token hasn't expired

  2. Incorrect Tenant ID

    • Verify against your Beekeeper URL

    • Example: URL <https://acmecorp.beekeeper.io> → Tenant ID acmecorp

    • Check for typos (case-sensitive)

  3. Network/Firewall Issues

    • Ensure Smart Arena server can reach <https://{tenant_id}.beekeeper.io>

    • Check firewall rules allow HTTPS outbound traffic

    • Test connectivity: curl <https://{tenant_id}.beekeeper.io/api/2/status>

  4. API Not Enabled

    • Contact Beekeeper support to verify API access is enabled for your account

Messages Stuck in Queue

Symptoms: Messages remain in "Pending" state for extended periods

Check:

  1. Cron Job Running: Verify smartarena:send-beekeeper command is scheduled and running

    # Check if cron job is configured crontab -l | grep send-beekeeper

  2. Large Queue Backlog: If queue is very large, processing may take time

    • Queue processes 200 messages per minute

    • Example: 2000 messages = 10 minutes to clear

  3. Blocked Organization: Check logs for "No active Beekeeper integration" messages

    • Verify integration is ON

    • Check credentials are valid

High Failure/Blocked Rate

Symptoms: Many messages in "Blocked" state

Common Errors:

  • User not found in Beekeeper: Mapping code doesn't match any Beekeeper user

  • Authentication failed: Access token expired or invalid

  • Server error (5xx): Beekeeper experiencing technical issues

Debug Mode

For detailed troubleshooting, check Laravel logs with full context:

tail -f app/storage/logs/laravel-$(date +%Y-%B | tr '[:upper:]' '[:lower:]').log | grep -i beekeeper
​

Look for:

  • Beekeeper routing skipped: Why messages weren't routed to Beekeeper

  • Detected unresolved username: Username resolution attempts

  • Pre-send resolution successful: UUID caching occurred

  • User not found in Beekeeper: Invalid mapping codes

Getting Help

If issues persist:

  1. Check Laravel Logs: Review logs for specific error messages

  2. Test Connection: Re-test connection in Beekeeper setup page

  3. Verify User Setup: Ensure at least one user has correct mapping code

  4. Contact Support: Provide the following information:

    • Organization ID

    • Example user with mapping code

    • Screenshot of integration status

    • Recent log entries (sanitized of sensitive data)

    • Error messages from queue

Best Practices

Security

  • Rotate Access Token: Change your Beekeeper API token every 90 days

  • Limit Access: Only grant integration setup permissions to trusted administrators

  • Monitor Usage: Regularly review message queue for unusual activity

  • Audit Logs: Check logs weekly for authentication failures or blocked messages

User Management

  • Standardize Usernames: Use consistent naming conventions (e.g., firstname.lastname)

  • Sync Mapping Codes: Keep mapping codes in sync with Beekeeper usernames

  • Bulk Updates: Use SFTP import or API for large-scale mapping code updates

  • New User Onboarding: Include mapping code in user creation workflows

Performance

  • Queue Size: Monitor queue size to prevent backlogs

    • Healthy: < 1000 pending messages

    • Warning: 1000-5000 pending messages

    • Critical: > 5000 pending messages (contact support)

  • Dual Delivery: Use sparingly to reduce system load

    • Enable during testing/transition periods

    • Disable once users are trained on Beekeeper notifications

  • Cache Management: System automatically caches UUIDs to improve performance

    • First message to user: Username resolution (slower)

    • Subsequent messages: Cached UUID lookup (faster)

Message Content

  • Keep It Concise: Mobile users prefer short, actionable notifications

  • Clear Subject Lines: First line of Beekeeper message should be clear

  • Avoid HTML: Complex HTML may not render well in chat (system auto-converts)

  • Test Formatting: Send test notifications to verify markdown conversion

Notification Types

SmartArena sends the following notifications via Beekeeper when enabled:

Course Notifications

  • Enrollment Confirmation: User enrolled in a course

  • Course Assignment: User assigned required training

  • Course Completion: Congratulations on completing a course

  • Certificate Issued: Certificate ready for download

  • Deadline Reminder: Upcoming course deadline

  • Overdue Notice: Course deadline passed

Assessment Notifications

  • Quiz Available: New quiz unlocked

  • Quiz Results: Quiz score and feedback

  • Retake Notification: Failed quiz, retake available

System Messages

  • User-to-User Messages: Messages from admins/managers

  • Registration Emails: Account activation (if password not provided during import)

  • Password Reset: Password reset instructions (falls back to email only)

Administrative Notifications

  • Enrollment by Admin: Admin enrolled you in course

  • Progress Reports: Manager review of your progress

  • Custom Notifications: Organization-specific custom messages

Note: All notifications respect the user's notification preferences in Smart Arena, even when delivered via Beekeeper.

Technical Details

API Endpoints Used

  • Status Check: GET /api/2/status - Verify API connectivity

  • Send Message: POST /api/2/chats/users/{userId}/messages - Send chat message

  • Get User by Username: GET /api/2/users/by_name/{username} - Resolve username to UUID

Authentication

  • Method: OAuth 2.0 Bearer Token

  • Header: Authorization: Token {access_token}

  • Content-Type: application/json; charset=UTF-8

Message Payload

{ "body": "**Course Enrollment**\n\nYou have been enrolled in \"Safety Training 101\"." }

Database Schema

Table: beekeeper_queue

Column

Type

Description

id

INT

Primary key

organization_id

INT

Organization ID

user_id

INT

SmartArena user ID (nullable)

recipient_mapping_code

VARCHAR

Beekeeper username or UUID

message

LONGTEXT

Markdown-formatted message body

is_sending

BOOLEAN

Currently being processed

is_sent

BOOLEAN

Successfully delivered

is_blocked

BOOLEAN

Blocked after retry limit

tries

INT

Number of send attempts

error_message

TEXT

Last error message (nullable)

created_at

TIMESTAMP

Queue insertion time

sent_at

TIMESTAMP

Successful delivery time (nullable)

Table: users (additional field)

Column

Type

Description

beekeeper_user_id

VARCHAR(100)

Cached Beekeeper UUID (nullable)

Markdown Conversion

HTML elements are converted to Beekeeper markdown:

HTML

Beekeeper Markdown

<h1>Title</h1>

**Title**

<b>Bold</b>

**Bold**

<i>Italic</i>

*Italic*

<a href="url">Link</a>

[Link](url)

<ul><li>Item</li></ul>

- Item

<p>Paragraph</p>

Line break

Migration from Email to Beekeeper

Phased Rollout Strategy

Phase 1: Testing (1-2 weeks)

  1. Enable Beekeeper integration

  2. Set "Also Send Email" to ON (dual delivery)

  3. Set up mapping codes for a small pilot group (5-10 users)

  4. Send test notifications

  5. Gather feedback from pilot group

  6. Resolve any username mapping issues

Phase 2: Partial Deployment (2-4 weeks)

  1. Expand to 25-50% of users

  2. Continue dual delivery (Beekeeper + email)

  3. Train users on Beekeeper notifications

  4. Monitor queue for issues

  5. Adjust mapping codes as needed

Phase 3: Full Deployment (1 month+)

  1. Deploy mapping codes to all users

  2. Continue dual delivery for transition period

  3. Communicate: "Primary notifications now via Beekeeper"

  4. Monitor user feedback and support tickets

Phase 4: Email Sunset (after 1-2 months)

  1. Announce email notifications will be disabled soon

  2. Verify all users have mapping codes

  3. Disable "Also Send Email" (Beekeeper-only)

  4. Monitor closely for missed notifications

  5. Keep fallback to email for critical messages if needed

Related Articles
API Documentation
Coursly AI: Smart Arena integration
Smart Arena Gecko Integration: Data Synchronization Guide
Smart Arena HANFA Integration - User Guide
Smart Arena SFTP User Import - User Guide
Did this answer your question?