Testing & Troubleshooting

Overview

Before relying on the automated schedule, it’s important to test your bot configuration. This guide covers manual testing and troubleshooting common problems.

Manual Testing with workflow_dispatch

The workflow includes workflow_dispatch which allows manual execution:

.github/workflows/main.yml

on:
  schedule:
    - cron: '0 15 * * 1-5'
    - cron: '0 21 * * 1-5'
  workflow_dispatch: # Permite ejecutarlo manualmente para probar

Running Manually on GitHub

Navigate to Actions

Go to your GitHub repository
Click the Actions tab at the top
You’ll see a list of workflows on the left sidebar

Select Workflow

Click on Registro WhatsApp Automático (or your workflow name) in the left sidebar.

Run Workflow

Click the Run workflow dropdown button (top right)
Select the branch (usually main or master)
Click the green Run workflow button

The workflow will start immediately and typically completes in 10-20 seconds.

View Results

Wait a few seconds for the run to appear
Click on the workflow run
Click on the run-bot job
Expand the Execute Script step
Check the output for status and response

Expected Output

A successful run shows:

Run python bot.py
Status: 200, Response: {"sent":"true","message":"ok","id":"..."}

The message sent depends on the current UTC time. If you run it before 18:00 UTC, it sends the “Entrada” message. After 18:00 UTC, it sends “Salida”.

Local Testing

For faster iteration, test the bot locally before pushing to GitHub:

Setup Local Environment

Clone Repository

git clone https://github.com/your-username/your-repo.git
cd your-repo

Install Dependencies

pip install requests

Set Environment Variables

Create a .env file or export variables:

Linux/Mac
Windows (CMD)
Windows (PowerShell)

export INSTANCE_ID="your_instance_id"
export TOKEN="your_token"
export GROUP_ID="your_group_id"

set INSTANCE_ID=your_instance_id
set TOKEN=your_token
set GROUP_ID=your_group_id

$env:INSTANCE_ID="your_instance_id"
$env:TOKEN="your_token"
$env:GROUP_ID="your_group_id"

Never commit your actual credentials to the repository. Add .env to your .gitignore file.

Run the Script

python bot.py

You should see output like:

Status: 200, Response: {"sent":"true","message":"ok"}

Testing Different Time Conditions

Since the message depends on UTC hour, you can temporarily modify the logic for testing:

bot.py

# Original code
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"

# For testing - force "Entrada" message
ahora_hora = 10  # Simulate morning
mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"

# For testing - force "Salida" message  
ahora_hora = 20  # Simulate evening
mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"

Remember to revert these changes before committing to GitHub.

Troubleshooting Common Issues

Issue: 401 Unauthorized

Symptoms:

Status: 401, Response: {"error":"Unauthorized"}

Causes and Solutions:

Check TOKEN Secret

Go to repository Settings > Secrets and variables > Actions
Verify TOKEN secret exists and is not expired
Update the token if needed from your UltraMsg dashboard

Verify Instance ID

The INSTANCE_ID must match your active UltraMsg instance:

Log in to UltraMsg dashboard
Check your instance ID (format: instance12345)
Update the INSTANCE_ID secret if it’s incorrect

Issue: 404 Not Found

Symptoms:

Status: 404, Response: {"error":"Chat not found"}

Causes and Solutions:

Verify Group ID Format

WhatsApp group IDs must follow the format:

[email protected]

Must include country code (e.g., 52 for Mexico)
Must end with @g.us for groups
Must include the group unique identifier after the dash

Get Correct Group ID

To find your group ID:

Send a test message to the group through UltraMsg dashboard
Use the UltraMsg API to list chats:

curl "https://api.ultramsg.com/{instance_id}/chats?token={token}"

Find your group in the response and copy its ID

Issue: Workflow Not Running on Schedule

Symptoms:

Workflow doesn’t execute at scheduled times
No runs appear in Actions tab

Causes and Solutions:

Check Workflow File Location

Ensure the workflow file is at:

.github/workflows/main.yml

The .github/workflows/ directory must be at the root of your repository.

Verify YAML Syntax

Invalid YAML prevents the workflow from running:

Go to Actions tab
Look for syntax error messages
Use a YAML validator to check your file

GitHub shows a red X next to the file in the repository if there’s a syntax error.

Check Repository Activity

GitHub may disable scheduled workflows for inactive repositories:

Make a commit to re-enable workflows
Ensure the repository isn’t archived
Verify workflows are enabled in Settings > Actions > General

Understand Schedule Delays

GitHub Actions scheduled workflows may have delays:

Typically run within 5-15 minutes of scheduled time
During high load, delays can be longer
Not guaranteed to be exact

For critical time-sensitive notifications, consider using an external service with webhooks.

Issue: Wrong Message Sent

Symptoms:

“Salida” message sent in the morning
“Entrada” message sent in the evening

Causes and Solutions:

Check Time Threshold Logic

The condition at bot.py:13 determines the message:

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"

If UTC hour < 18 → “Entrada”
If UTC hour ≥ 18 → “Salida”

Verify Schedule Times

Check your cron schedule matches your timezone:

schedule:
  - cron: '0 15 * * 1-5'  # Should be morning in your timezone
  - cron: '0 21 * * 1-5'  # Should be evening in your timezone

For CST (UTC-6):

15:00 UTC = 9:00 AM CST (before 18:00 UTC ✓)
21:00 UTC = 3:00 PM CST (after 18:00 UTC ✓)

Adjust Threshold if Needed

If your afternoon run is before 18:00 UTC, adjust the threshold:

# If your afternoon run is at 17:00 UTC (e.g., 9:00 AM PST)
mensaje = "Name \n Entrada \n 9:00 AM" if ahora_hora < 12 else "Name\n Salida\n 3:00 PM"

Issue: Environment Variables Not Found

Symptoms:

AttributeError: 'NoneType' object has no attribute '...'

Causes and Solutions:

Verify Secret Names

In .github/workflows/main.yml, check the environment variable mapping:

env:
  INSTANCE_ID: ${{ secrets.INSTANCE_ID }}
  TOKEN: ${{ secrets.TOKEN }}
  GROUP_ID: ${{ secrets.GROUP_ID }}

Secret names are case-sensitive and must match exactly.

Confirm Secrets Exist

Go to Settings > Secrets and variables > Actions
Verify all three secrets are listed
Re-add any missing secrets

Check for Typos in bot.py

Ensure environment variable names match:

instance_id = os.getenv('INSTANCE_ID')  # Must match workflow
token = os.getenv('TOKEN')
group_id = os.getenv('GROUP_ID')

Debugging Tips

Add Debug Output

Add print statements to understand what’s happening:

import requests
import os
import datetime

def enviar_registro():
    instance_id = os.getenv('INSTANCE_ID')
    token = os.getenv('TOKEN')
    group_id = os.getenv('GROUP_ID')
    
    # Debug output
    print(f"Instance ID: {instance_id[:8]}...")
    print(f"Group ID: {group_id}")
    
    ahora_hora = datetime.datetime.utcnow().hour
    print(f"Current UTC hour: {ahora_hora}")
    
    mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"
    print(f"Message: {mensaje}")
    
    url = f"https://api.ultramsg.com/{instance_id}/messages/chat"
    payload = {
        "token": token,
        "to": group_id,
        "body": mensaje
    }
    headers = {'content-type': 'application/x-www-form-urlencoded'}
    
    r = requests.post(url, data=payload, headers=headers)
    print(f"Status: {r.status_code}, Response: {r.text}")

Never print full tokens or sensitive credentials, even in GitHub Actions logs. Use truncation like token[:8]... if needed.

Test UltraMsg API Directly

Test your credentials with curl:

curl -X POST "https://api.ultramsg.com/{instance_id}/messages/chat" \
  -d "token={token}" \
  -d "to={group_id}" \
  -d "body=Test message from curl"

If this works but the bot doesn’t, the issue is in your Python code.

Check GitHub Actions Logs

Detailed logs are available for each step:

Go to Actions tab
Click on a workflow run
Click on the run-bot job
Each step can be expanded to see full output
Look for error messages in red

Getting Help

If you’re still having issues:

Check the UltraMsg API documentation
Verify your UltraMsg instance is active and connected
Review the GitHub Actions logs for error details
Test locally with debug output enabled

Keep your UltraMsg instance connected to WhatsApp Web. If it disconnects, you’ll need to scan the QR code again in the UltraMsg dashboard.

Getting Started

Configuration

Guides

Reference

Overview

Manual Testing with workflow_dispatch

Running Manually on GitHub

Expected Output

Local Testing

Setup Local Environment

Testing Different Time Conditions

Troubleshooting Common Issues

Issue: 401 Unauthorized

Issue: 404 Not Found

Issue: Workflow Not Running on Schedule

Issue: Wrong Message Sent

Issue: Environment Variables Not Found

Debugging Tips

Add Debug Output

Test UltraMsg API Directly

Check GitHub Actions Logs

Getting Help

Build docs developers (and LLMs) love

Getting Started

Configuration

Guides

Reference

​Overview

​Manual Testing with workflow_dispatch

​Running Manually on GitHub

​Expected Output

​Local Testing

​Setup Local Environment

​Testing Different Time Conditions

​Troubleshooting Common Issues

​Issue: 401 Unauthorized

​Issue: 404 Not Found

​Issue: Workflow Not Running on Schedule

​Issue: Wrong Message Sent

​Issue: Environment Variables Not Found

​Debugging Tips

​Add Debug Output

​Test UltraMsg API Directly

​Check GitHub Actions Logs

​Getting Help

Build docs developers (and LLMs) love

Overview

Manual Testing with workflow_dispatch

Running Manually on GitHub

Expected Output

Local Testing

Setup Local Environment

Testing Different Time Conditions

Troubleshooting Common Issues

Issue: 401 Unauthorized

Issue: 404 Not Found

Issue: Workflow Not Running on Schedule

Issue: Wrong Message Sent

Issue: Environment Variables Not Found

Debugging Tips

Add Debug Output

Test UltraMsg API Directly

Check GitHub Actions Logs

Getting Help