Skip to main content

​
Overview

The WhatsApp Attendance Bot uses GitHub Actions cron schedules to automatically send attendance messages at specific times. Understanding cron syntax and UTC timezone conversion is essential for configuring the bot to run at your desired local times.
GitHub Actions always uses UTC timezone for cron schedules. You must convert your local time to UTC when configuring schedules.

​
Current Schedule Configuration

The bot is currently configured to send messages twice daily on weekdays:
main.yml
schedule:
  # IMPORTANTE: Los horarios son en UTC. 
  # Para México (CST): 9:00 AM es 15:00 UTC | 3:00 PM es 21:00 UTC
  - cron: '0 15 * * 1-5'  # Lunes a Viernes 9:00 AM
  - cron: '0 21 * * 1-5'  # Lunes a Viernes 3:00 PM

​
Scheduled Times

Morning Check-in

UTC: 15:00 (3:00 PM)
CST/Mexico: 9:00 AM
Days: Monday - FridaySends: “Aldo Tolentino \n Entrada \n 9:00 AM”

Afternoon Check-out

UTC: 21:00 (9:00 PM)
CST/Mexico: 3:00 PM
Days: Monday - FridaySends: “Aldo Tolentino\n Salida\n 3:00 PM”

​
Understanding Cron Syntax

Cron expressions consist of five fields that specify when to run: 
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *

​
Example Breakdown

​
0 15 * * 1-5
cron expression
  • 0: At minute 0 (top of the hour)
  • 15: At hour 15 (3:00 PM UTC)
  • *: Every day of the month
  • *: Every month
  • 1-5: Monday through Friday (1=Monday, 5=Friday)
Result: Runs at 15:00 UTC every weekday

​
Timezone Conversion Guide

Since GitHub Actions uses UTC, you must convert your local time to UTC. Here’s how the current schedule converts:

​
Mexico/Central Standard Time (CST/UTC-6)

1

Determine Your Local Time

Example: You want the bot to run at 9:00 AM CST
2

Calculate UTC Offset

CST is UTC-6, meaning CST is 6 hours behind UTC.Formula: UTC = Local Time + 6 hours
3

Convert to UTC

9:00 AM CST + 6 hours = 15:00 UTC (3:00 PM)3:00 PM CST + 6 hours = 21:00 UTC (9:00 PM)
4

Apply to Cron Expression

Use the UTC hour in your cron expression:
- cron: '0 15 * * 1-5'  # 9:00 AM CST
- cron: '0 21 * * 1-5'  # 3:00 PM CST

​
Common Timezone Conversions

Use this table to convert common timezones to UTC for your cron schedules.
TimezoneOffset9:00 AM Local3:00 PM Local9:00 AM in UTC3:00 PM in UTC
CST (Mexico)UTC-69:00 AM3:00 PM15:0021:00
EST (US East)UTC-59:00 AM3:00 PM14:0020:00
PST (US West)UTC-89:00 AM3:00 PM17:0023:00
GMT (UK)UTC+09:00 AM3:00 PM09:0015:00
CET (Central Europe)UTC+19:00 AM3:00 PM08:0014:00
IST (India)UTC+5:309:00 AM3:00 PM03:3009:30
Remember to account for Daylight Saving Time (DST) if your region observes it. During DST, your offset to UTC changes by 1 hour.

​
How Message Content Is Determined

The bot uses UTC hour to determine whether to send a check-in or check-out message:
bot.py
# Determinar si es entrada o salida según la hora (UTC)
# Ejemplo: Si estás en México, 15:00 UTC es 9:00 AM
ahora_hora = datetime.datetime.utcnow().hour
mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"
Logic:
  • If UTC hour < 18 (before 6:00 PM UTC): Send “Entrada” (Check-in) message
  • If UTC hour >= 18 (6:00 PM UTC or later): Send “Salida” (Check-out) message
The 18:00 UTC threshold works for CST schedules. If you change timezones, you may need to adjust this threshold in bot.py to ensure correct message content.

​
Customizing Your Schedule

​
Change Running Times

To modify when the bot runs, edit .github/workflows/main.yml: 
schedule:
  - cron: '0 14 * * 1-5'  # Example: 8:00 AM CST (14:00 UTC)
  - cron: '0 22 * * 1-5'  # Example: 4:00 PM CST (22:00 UTC)

​
Add Weekend Runs

To include Saturday and Sunday: 
schedule:
  - cron: '0 15 * * 0-6'  # 0-6 includes all days (Sunday-Saturday)
  - cron: '0 21 * * 0-6'

​
Add Additional Check-ins

For a third daily message (e.g., lunch break): 
schedule:
  - cron: '0 15 * * 1-5'  # Morning
  - cron: '0 18 * * 1-5'  # Noon CST (18:00 UTC = 12:00 PM CST)
  - cron: '0 21 * * 1-5'  # Afternoon
If you add additional schedules, you’ll need to modify the message logic in bot.py to send appropriate content for each time.

​
Monthly or Specific Date Runs

# Run only on the first day of each month
- cron: '0 15 1 * 1-5'

# Run only in specific months (e.g., January, June, December)
- cron: '0 15 * 1,6,12 1-5'

​
Manual Workflow Execution

The workflow includes workflow_dispatch to allow manual triggering: 
on:
  schedule:
    - cron: '0 15 * * 1-5'
    - cron: '0 21 * * 1-5'
  workflow_dispatch: # Permite ejecutarlo manualmente para probar

​
Running Manually

1

Navigate to Actions Tab

Go to your GitHub repository and click the Actions tab.
2

Select Workflow

Click on “Registro WhatsApp Automático” in the workflows list.
3

Run Workflow

Click the Run workflow dropdown button, then click Run workflow to execute immediately.
4

Verify Execution

Check the workflow run logs and verify the message in your WhatsApp group.
Manual execution is useful for testing configuration changes without waiting for the scheduled time.

​
Cron Schedule Reliability

GitHub Actions cron schedules may experience delays during high-load periods. Schedules are not guaranteed to run at the exact specified time.
Typical delay: 3-10 minutes during peak times Best practices:
  • Don’t rely on exact second-precision timing
  • Schedule critical tasks with buffer time
  • Use manual dispatch for time-sensitive tests

​
Testing Your Schedule

​
Verify Cron Expression

Use online tools to validate your cron syntax:

​
Test Before Committing

  1. Use the manual workflow dispatch to test immediately
  2. Check workflow logs for execution time and output
  3. Verify the message appears in your WhatsApp group
  4. Confirm the message content matches the expected check-in/check-out

​
Troubleshooting

​
Workflow Not Running

Check these common issues:
  • Ensure the schedule is in the main or default branch
  • Verify cron syntax is valid (no syntax errors)
  • Confirm the repository has Actions enabled (Settings > Actions > General)
  • Check if you’ve reached GitHub Actions usage limits

​
Wrong Message Time

Possible causes:
  • Incorrect UTC conversion (recalculate your timezone offset)
  • Daylight Saving Time not accounted for
  • GitHub Actions delay (check actual execution time in logs)

​
Wrong Message Content

Solution:
  • Review the hour threshold in bot.py:13
  • Adjust the ahora_hora < 18 condition for your timezone
  • Test with manual dispatch at different times

​
Next Steps

Environment Variables

Configure required credentials for the bot

Customization

Modify message content and formatting

Build docs developers (and LLMs) love

Get started for freeTalk to us