Skip to main content
This guide will walk you through setting up your automated WhatsApp attendance bot. You’ll have a working bot that sends scheduled messages to your WhatsApp group via GitHub Actions.

​
Prerequisites

Before you begin, make sure you have:
  • A GitHub account
  • A WhatsApp account and phone number
  • Access to create a WhatsApp group (if you don’t have one already)
1

Fork the Repository

Start by forking the WhatsApp Attendance Bot repository to your GitHub account:
  1. Visit the repository on GitHub
  2. Click the Fork button in the top-right corner
  3. Select your account as the destination
Forking creates your own copy of the repository, allowing you to configure it with your credentials without affecting the original project.
2

Set Up Ultramsg Account

Ultramsg is the service that will send WhatsApp messages on your behalf.
  1. Go to ultramsg.com and create a free account
  2. After logging in, click Create Instance
  3. Follow the instructions to connect your WhatsApp number by scanning the QR code
  4. Once connected, note down your Instance ID (found in the dashboard)
  5. Navigate to the API section and copy your API Token
Keep your Instance ID and Token secure. Never commit them directly to your repository.
3

Get Your WhatsApp Group ID

You need the Group ID where the bot will send attendance messages.
  1. In your Ultramsg dashboard, go to Chat ID or Get Chat ID
  2. Send a message to your target WhatsApp group from your connected phone
  3. The group ID will appear in the Ultramsg dashboard (format: [email protected])
  4. Copy this Group ID for the next step
The Group ID is a unique identifier for your WhatsApp group. Make sure you’re getting the ID for the correct group.
4

Configure GitHub Secrets

Store your credentials securely as GitHub repository secrets:
  1. Go to your forked repository on GitHub
  2. Click Settings → Secrets and variables → Actions
  3. Click New repository secret and add these three secrets:
Secret NameValueDescription
INSTANCE_IDYour Ultramsg Instance IDFrom Ultramsg dashboard
TOKENYour Ultramsg API TokenFrom Ultramsg API section
GROUP_IDYour WhatsApp Group IDFormat: [email protected]
These secrets are automatically injected into your GitHub Actions workflow as environment variables.
5

Enable GitHub Actions

By default, GitHub Actions might be disabled on forked repositories.
  1. In your repository, go to the Actions tab
  2. If prompted, click I understand my workflows, go ahead and enable them
  3. You should see the workflow named “Registro WhatsApp Automático”
The workflow is configured to run automatically:
  • 9:00 AM (your timezone) - Sends “Entrada” (entry) message
  • 3:00 PM (your timezone) - Sends “Salida” (exit) message
  • Monday to Friday only (no weekend messages)
The cron schedule in the workflow uses UTC time. You may need to adjust the times based on your timezone. See the Configuration guide for details.
6

Test the Bot Manually

Before waiting for the scheduled time, test that everything works:
  1. Go to the Actions tab in your repository
  2. Click on Registro WhatsApp Automático workflow
  3. Click Run workflow dropdown on the right
  4. Click the green Run workflow button
  5. Wait a few seconds and refresh the page
  6. Click on the running workflow to see its progress
The workflow will:
  • Checkout your code
  • Set up Python 3.9
  • Install the requests library
  • Execute the bot script with your secrets
name: Registro WhatsApp Automático

on:
  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
  workflow_dispatch: # Permite ejecutarlo manualmente para probar

jobs:
  run-bot:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install dependencies
        run: pip install requests

      - name: Execute Script
        env:
          INSTANCE_ID: ${{ secrets.INSTANCE_ID }}
          TOKEN: ${{ secrets.TOKEN }}
          GROUP_ID: ${{ secrets.GROUP_ID }}
        run: python bot.py
7

Verify the Message

Check your WhatsApp group to confirm the bot sent a message:
  1. Open WhatsApp on your phone or desktop
  2. Navigate to the group you configured
  3. You should see a message from your connected number with attendance information
The message format depends on the time:
  • Before 6:00 PM UTC: “Aldo Tolentino \n Entrada \n 9:00 AM”
  • After 6:00 PM UTC: “Aldo Tolentino\n Salida\n 3:00 PM”
If the message didn’t arrive, check the Actions workflow logs for error messages. Common issues include incorrect credentials or Group ID format.

​
What’s Next?

Your bot is now running! Here’s what you can do next:

Customize Messages

Learn how to customize the message format, name, and times

Adjust Schedule

Change the cron schedule to match your work hours and timezone

Troubleshooting

Fix common issues and understand error messages

FAQ

Find answers to frequently asked questions

​
Quick Troubleshooting

If something isn’t working, check these common issues:
IssueSolution
No message receivedVerify all three secrets are set correctly in GitHub
Wrong group receiving messagesDouble-check the GROUP_ID format ([email protected])
Messages at wrong timesAdjust cron schedule for your timezone (it uses UTC)
Workflow not runningEnsure GitHub Actions is enabled in your forked repo
”Unauthorized” errorRegenerate your Ultramsg API token and update the secret
The bot determines whether to send “Entrada” or “Salida” based on UTC time. If the hour is before 18:00 UTC, it sends “Entrada”, otherwise “Salida”.

Build docs developers (and LLMs) love

Get started for freeTalk to us