Find My Kids - WhatsApp Face Recognition Bot

This application integrates DeepFace with the WhatsApp Green API to detect predetermined faces in images shared within a WhatsApp group and to notify designated contacts immediately.

Components

This solution leverages the following technologies:

• Green-API: Facilitates WhatsApp communication.
• DeepFace: Provides robust face recognition capabilities.
• FastAPI: Powers the web server interface.

Prerequisites

Before proceeding with the setup, ensure that you have the following:

• Docker and Docker Compose installed
• A registered Green API Account

Setup Instructions

1. Green API Configuration

Account Registration

1. Visit https://green-api.com/en and register for a new account.

2. Complete the registration form by entering your details and then click Register.

   

3. Once registered, select Create an instance.

   

4. Choose the Developer instance (Free Tier).

   

5. Copy the generated InstanceId and Token—these will be required for integration.

   

6. To link your WhatsApp account, navigate to the API section on the left under Account and select QR. Open the provided QR URL in your browser, then click on Scan QR code:

   

7. Scan the QR code to complete the linking process:

   

8. Once linked, the instance status will display a green light, indicating it is active:

   

Important: Do not configure a webhook URL for your instance, as this will interfere with the bot’s functionality.

2. Environment Configuration

1. Duplicate the sample environment file by running:

 cp .env.example .env

2. Edit the .env file with your credentials:

# WhatsApp API Credentials
GREEN_API_INSTANCE=your_whatsapp_instance_id
GREEN_API_TOKEN=your_whatsapp_api_token

3. Running the Application

1. Use the following docker-compose.yaml :

    services:
   find-my-kids:
     image: techblog/find-my-kids:latest
     container_name: find-my-kids
     ports:
       - "7020:7020"
     environment:
       - GREEN_API_INSTANCE=${GREEN_API_INSTANCE}
       - GREEN_API_TOKEN=${GREEN_API_TOKEN}
     volumes:
       - ./find-my-kids/images:/app/images
       - ./find-my-kids/config:/app/config
     restart: unless-stopped 

   Where:

   • /find-my-kids/images is the volume for the model training images and downloaded images.
   • ./find-my-kids/config is the path to the config file.

2. Start the application:

   docker-compose up -d

3. The application will be available at http://[Server_IP]:[Port]

Usage

Configuration file

Under the config folder you will find a file named config.yaml with the following content:

kids:
  Kid1: 
    collection_id: Kid1
    chat_ids:
      - 000000000000000000@g.us

target: 972000000000-1000000000@g.us

• Kid1: the name of the kid/person
• collection_id: The Id of the classifier used by DeepFace.
• chat_ids: list of whatsapp chats (Groups or Contacts) to monitor.
• target: The target group or contact to forward the pictures to.

In order to get the list of groups, enter the following URL: http://[server_ip]:[port]/contacts

The web page will contain a table with the list of contacts and group:

⚠️ IMPORTANT ⚠️: After updating the config file, restart the container to reload the configuration

Training

Manual Images Upload

In order to train the Recognition model open your browser and navigate to: http://[SERVER_IP]:[PORT]/trainer

ℹ️Noticeℹ️ An error may popup, it is because there are no images related for the collections, just click on OK.

Next, select the collecion you would like to train, Select a picture and click "Upload and Train" button:

In the Gallery tab, you will see all the pictured used to train the model:

You can click the "re-train" button to re-train the model with the pictures.

Bulk Images Upload

The bot also support bulk imags upload for training by adding Images to the trainer folder as follows:

images
    |──trainer/
          ├── Kid1/
          │   ├── image1.jpg
          │   ├── image2.jpg
          │   └── ...
          ├── Kid2/
          │   ├── image1.jpg
          │   └── ...
          └── Kid3/
              ├── image1.jpg
              └── ...

Next, in the Gallery tab (Web UI), you will see all the pictured used to train the model:

You can click the "re-train" button to re-train the model with the pictures.

Congrats, you can now use the bot.