Troubleshooting

Common Issues

This guide covers the most common problems you may encounter when setting up and running the WhatsApp Attendance Bot.

Messages Sent at Wrong Time

Symptoms

Bot sends messages at unexpected times
Check-in sent when you expected check-out, or vice versa
Messages arrive hours before or after the intended time

Causes

Timezone Mismatch

GitHub Actions runs on UTC time, but your local timezone may be different.Solution:

Identify your timezone offset from UTC
Calculate the correct cron schedule
Update .github/workflows/main.yml

Example for Mexico CST (UTC-6):

schedule:
  - cron: '0 15 * * 1-5'  # 9:00 AM CST = 15:00 UTC
  - cron: '0 21 * * 1-5'  # 3:00 PM CST = 21:00 UTC

Example for EST (UTC-5):

schedule:
  - cron: '0 14 * * 1-5'  # 9:00 AM EST = 14:00 UTC
  - cron: '0 20 * * 1-5'  # 3:00 PM EST = 20:00 UTC

Example for IST (UTC+5:30):

schedule:
  - cron: '30 3 * * 1-5'  # 9:00 AM IST = 03:30 UTC
  - cron: '30 9 * * 1-5'  # 3:00 PM IST = 09:30 UTC

Incorrect Time Logic in bot.py

The function at bot.py:13 uses a simple hour comparison:

mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"

This means:

Hours 0-17 UTC: Check-in message
Hours 18-23 UTC: Check-out message

Solution:If your check-out is scheduled after 18:00 UTC but you’re getting check-in messages, adjust the threshold:

# Example: Change to 20 if your check-out is at 21:00 UTC
mensaje = "..." if ahora_hora < 20 else "..."

Missing GitHub Secrets

Symptoms

Workflow runs but fails with errors
API returns 401 Unauthorized or 400 Bad Request
Python errors: TypeError: unsupported operand type(s) for +: 'NoneType' and 'str'

Cause

One or more required secrets are not configured in your GitHub repository.

Solution

GitHub Secrets are case-sensitive. Ensure you use the exact names: INSTANCE_ID, TOKEN, and GROUP_ID.

Go to your repository on GitHub
Click Settings > Secrets and variables > Actions
Verify these three secrets exist:
- INSTANCE_ID
- TOKEN
- GROUP_ID
If any are missing, click New repository secret and add them
Re-run the workflow

How to Verify Secrets

Add a debug step to your workflow (remove after testing):

- name: Debug Secrets
  run: |
    echo "INSTANCE_ID is set: ${{ secrets.INSTANCE_ID != '' }}"
    echo "TOKEN is set: ${{ secrets.TOKEN != '' }}"
    echo "GROUP_ID is set: ${{ secrets.GROUP_ID != '' }}"

Ultramsg API Errors

HTTP 401 Unauthorized

Cause: Invalid or expired TOKEN Solution:

Log in to Ultramsg Dashboard
Navigate to your instance
Copy the correct token
Update the TOKEN secret in GitHub

HTTP 400 Bad Request

Cause: Invalid GROUP_ID format or parameters Solution:

Verify GROUP_ID format: [country_code][number]@g.us
- Example: [email protected] (Mexico)
- Must include @g.us suffix for groups
Use the group’s phone number, not a personal number
Update the GROUP_ID secret with the correct format

HTTP 429 Too Many Requests

Cause: Exceeded Ultramsg rate limits Solution:

Check your Ultramsg plan limits
Ensure you’re not running the workflow too frequently
Consider upgrading your Ultramsg plan

HTTP 500 Internal Server Error

Cause: Ultramsg service issue Solution:

Check Ultramsg status page
Wait and try again later
Contact Ultramsg support if issue persists

Workflow Not Triggering

Symptoms

Scheduled time passes but workflow doesn’t run
No workflow runs appear in the Actions tab

Causes and Solutions

Inactive Repository

Cause: GitHub disables scheduled workflows in repositories with no activity for 60 days.Solution:

Make a commit to the repository (can be a simple README update)
Push the commit to GitHub
The schedule will resume

Prevent this:Set a reminder to make a commit every 50 days, or use the workflow_dispatch trigger to run manually.

Incorrect Cron Syntax

Cause: Invalid cron expression in .github/workflows/main.ymlSolution:Verify your cron syntax:

# Format: 'minute hour day month day_of_week'
- cron: '0 15 * * 1-5'  # Valid: Monday-Friday at 15:00 UTC

Common mistakes:

Using 12-hour format: cron: '0 3 * * 1-5' for 3 PM (should be 15)
Wrong day range: cron: '0 15 * * 1-7' (should be 1-5 for weekdays)

Test your cron expression at crontab.guru

Workflow File Not in Correct Location

Cause: Workflow file is not in .github/workflows/ directorySolution:Ensure your workflow file is at: .github/workflows/main.yml

# Verify the file exists
ls -la .github/workflows/main.yml

GitHub Actions Disabled

Cause: Actions are disabled for the repositorySolution:

Go to repository Settings > Actions > General
Under “Actions permissions”, select Allow all actions
Save the settings

Message Not Received in WhatsApp

Symptoms

Workflow runs successfully (status 200)
No message appears in WhatsApp group

Causes and Solutions

WhatsApp Instance Not Connected

Cause: Your Ultramsg instance is not connected to WhatsAppSolution:

Log in to Ultramsg Dashboard
Check instance connection status
If disconnected, scan the QR code to reconnect
Keep the browser tab open until connection is established

Wrong Group ID

Cause: GROUP_ID doesn’t match your WhatsApp groupSolution:

Send a message to your group from WhatsApp Web
In Ultramsg dashboard, go to Chats
Find your group and copy its ID
Update the GROUP_ID secret in GitHub

The ID should look like: [email protected]

Bot Not Added to Group

Cause: The phone number linked to your Ultramsg instance isn’t in the groupSolution:

Add the phone number (linked to Ultramsg) to the WhatsApp group
Ensure it has permission to send messages
Test by running the workflow manually

Python Dependencies Error

Symptoms

Workflow fails with: ModuleNotFoundError: No module named 'requests'

Cause

The requests library is not installed before running the script.

Solution

Verify your workflow includes the install step at .github/workflows/main.yml:23-24:

- name: Install dependencies
  run: pip install requests

If you add more dependencies, update this step:

- name: Install dependencies
  run: pip install requests python-dotenv

Or use a requirements.txt file:

- name: Install dependencies
  run: pip install -r requirements.txt

Manual Testing

Test the Workflow Manually

The workflow includes workflow_dispatch trigger at .github/workflows/main.yml:9:

workflow_dispatch: # Allows manual execution

To run manually:

Go to Actions tab in your repository
Select Registro WhatsApp Automático workflow
Click Run workflow button
Select branch and click Run workflow

Test the Script Locally

# Set environment variables
export INSTANCE_ID="your_instance_id"
export TOKEN="your_token"
export GROUP_ID="[email protected]"

# Run the script
python bot.py

Expected output:

Status: 200, Response: {"sent":"true","message":"Message sent successfully"}

Getting Help

If you’re still experiencing issues:

Check the Actions tab for detailed error logs
Review Ultramsg dashboard for API logs and errors
Verify all three secrets are correctly set
Test with workflow_dispatch before relying on the schedule

GitHub Actions scheduled workflows may experience delays of up to 10 minutes during high load periods. This is normal behavior and not a configuration issue.

Getting Started

Configuration

Guides

Reference

Common Issues

Messages Sent at Wrong Time

Symptoms

Causes

Missing GitHub Secrets

Symptoms

Cause

Solution

How to Verify Secrets

Ultramsg API Errors

HTTP 401 Unauthorized

HTTP 400 Bad Request

HTTP 429 Too Many Requests

HTTP 500 Internal Server Error

Workflow Not Triggering

Symptoms

Causes and Solutions

Message Not Received in WhatsApp

Symptoms

Causes and Solutions

Python Dependencies Error

Symptoms

Cause

Solution

Manual Testing

Test the Workflow Manually

Test the Script Locally

Getting Help

Build docs developers (and LLMs) love

Getting Started

Configuration

Guides

Reference

​Common Issues

​Messages Sent at Wrong Time

​Symptoms

​Causes

​Missing GitHub Secrets

​Symptoms

​Cause

​Solution

​How to Verify Secrets

​Ultramsg API Errors

​HTTP 401 Unauthorized

​HTTP 400 Bad Request

​HTTP 429 Too Many Requests

​HTTP 500 Internal Server Error

​Workflow Not Triggering

​Symptoms

​Causes and Solutions

​Message Not Received in WhatsApp

​Symptoms

​Causes and Solutions

​Python Dependencies Error

​Symptoms

​Cause

​Solution

​Manual Testing

​Test the Workflow Manually

​Test the Script Locally

​Getting Help

Build docs developers (and LLMs) love

Common Issues

Messages Sent at Wrong Time

Symptoms

Causes

Missing GitHub Secrets

Symptoms

Cause

Solution

How to Verify Secrets

Ultramsg API Errors

HTTP 401 Unauthorized

HTTP 400 Bad Request

HTTP 429 Too Many Requests

HTTP 500 Internal Server Error

Workflow Not Triggering

Symptoms

Causes and Solutions

Message Not Received in WhatsApp

Symptoms

Causes and Solutions

Python Dependencies Error

Symptoms

Cause

Solution

Manual Testing

Test the Workflow Manually

Test the Script Locally

Getting Help