{"id":13588698,"url":"https://github.com/wiseindy/timer-for-google-assistant","last_synced_at":"2025-04-08T06:32:35.435Z","repository":{"id":39799399,"uuid":"282738542","full_name":"wiseindy/timer-for-google-assistant","owner":"wiseindy","description":"Allows you to send commands to Google Assistant that will execute after a certain time interval. Built using NodeJS.","archived":false,"fork":false,"pushed_at":"2023-03-08T01:23:52.000Z","size":4269,"stargazers_count":91,"open_issues_count":17,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-06T08:43:03.698Z","etag":null,"topics":["google-assistant","home-automation","ifttt","ifttt-webhooks","timer"],"latest_commit_sha":null,"homepage":"https://wiseindy.com/automation/timer-for-google-assistant/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wiseindy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-26T21:46:01.000Z","updated_at":"2024-09-17T02:48:05.000Z","dependencies_parsed_at":"2024-11-06T08:33:46.395Z","dependency_job_id":"2cee79e8-ed2e-4731-ba1c-a330bfcf983d","html_url":"https://github.com/wiseindy/timer-for-google-assistant","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseindy%2Ftimer-for-google-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseindy%2Ftimer-for-google-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseindy%2Ftimer-for-google-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseindy%2Ftimer-for-google-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wiseindy","download_url":"https://codeload.github.com/wiseindy/timer-for-google-assistant/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247792150,"owners_count":20996878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-assistant","home-automation","ifttt","ifttt-webhooks","timer"],"created_at":"2024-08-01T15:06:52.394Z","updated_at":"2025-04-08T06:32:30.425Z","avatar_url":"https://github.com/wiseindy.png","language":"TypeScript","funding_links":["https://www.buymeacoffee.com/wiseindy"],"categories":["TypeScript"],"sub_categories":[],"readme":"![Timer for Google Assistant](/app/assets/timer-for-google-assistant.png?raw=true \"Timer for Google Assistant\")\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hub.docker.com/r/wiseindy/timer-for-google-assistant\"\u003e\n    \u003cimg src=\"https://img.shields.io/docker/cloud/automated/wiseindy/timer-for-google-assistant\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/r/wiseindy/timer-for-google-assistant\"\u003e\n    \u003cimg src=\"https://img.shields.io/docker/cloud/build/wiseindy/timer-for-google-assistant\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/wiseindy/timer-for-google-assistant\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/wiseindy/timer-for-google-assistant/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/wiseindy/timer-for-google-assistant?style=social\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Description\n\nWouldn't it be cool if you could say stuff like:\n\n* *\"Hey Google, turn off the lights after 10 minutes\"*\n* *\"Hey Google, turn on the fan for 25 minutes\"*\n* *\"Hey Google, turn off \u0026lt;device\u0026gt; after \u0026lt;x\u0026gt; minutes\"*\n\nWell, this project makes it possible. **Timer for Google Assistant** allows you to send commands to Google Assistant that will execute after a certain time.\n\n## How does it work?\n\n**Timer for Google Assistant** provides a simple API with which you can schedule commands. See [API Reference](#api-reference) below.\n\nThis application is built using [NestJS - A progressive Node.js framework](https://nestjs.com/).\nIt uses [IFTTT](https://ifttt.com/) to communicate with Google Assistant and your smart device.\n\nThere are 2 ways to set it up:\n\n1. [Install using Docker](#install-using-docker) (recommended)\n2. [Manual installation without Docker](#manual-installation-without-docker)\n\n## API Reference\n\n### Usage\n\n `POST /trigger`\n\n### Request body\n\nContent type: `application/json`\n| Name                    | Type      | Required | Default value | Description                                                                                            |\n|:------------------------|:----------|:---------|:--------------|:-------------------------------------------------------------------------------------------------------|\n| *key*                   | `string`  | **Yes**  | -             | This key can be any value, however, it should the match the key specified while setting up the server. |\n| *durationInMinutes*     | `number`  | **Yes**  | -             | Number of minutes after which the action should be triggered.                                          | \n| *deviceName*            | `string`  | **Yes**  | -             | Name of the target device.                                                                             |\n| *targetState*           | `boolean` | No       | `false`       | What should the state of the device be *after* firing the event? `true` = ON; `false` = OFF            | \n\n#### Example\n\nMaking a `POST` request with the parameters below will set the `lights` to `OFF` after `20` minutes.\n\n``` json\n{\n  \"key\":\"ChangeThisToSomethingSecure\",\n  \"durationInMinutes\":20,\n  \"deviceName\":\"lights\",\n  \"targetState\":false\n}\n```\n\n#### A note on the `targetState` parameter\n\nIf `targetState` is set to `false` (i.e., OFF), the device will be first turned `ON` upon receiving this command. After the specified time has elapsed, the device will be turned `OFF`. This is an optional parameter and by default, `targetState` is `false`.\n\nIf `targetState` is set to `true` (i.e., ON), it will do the opposite. The device will be first turned `OFF` upon receiving this command. After the specified time has elapsed, the device will be turned `ON`. \n\n\n## Install using Docker\n\n**Timer for Google Assistant** is available as a [Docker image](https://hub.docker.com/r/wiseindy/timer-for-google-assistant).\n\n### Prerequisites\n\n* An internet facing server (so that IFTTT can make requests to your server)\n* [Docker](https://www.docker.com/) installed on this server.\n\n#### Running with `docker`\n\nRun the following command on your server to get this application up and running. The application runs on port `3000` internally. The command below makes the API available externally on port `3020`.\n\n[For information on what the environment variables mean, see this section below.](#create-a-env-file-in-the-root-directory-sample-values-can-be-seen-in-envexample)\n\n```bash\ndocker run \\\n  -e SECURITY_KEY=\"ChangeThisToSomethingSecure\" \\\n  -e IFTTT_EVENT_OFF_SUFFIX=\"_off\" \\\n  -e IFTTT_EVENT_ON_SUFFIX=\"_on\" \\\n  -e IFTTT_EVENT_KEY=\"xxxxxxxxxxxxxxxxxxxxxx\" \\\n-p 3020:3000 wiseindy/timer-for-google-assistant\n```\n\nYou can also specify the environment variables in a separate file, for example, `my_env_data`.\n\n```\nSECURITY_KEY=ChangeThisToSomethingSecure\nIFTTT_EVENT_OFF_SUFFIX=_off\nIFTTT_EVENT_ON_SUFFIX=_on\nIFTTT_EVENT_KEY=xxxxxxxxxxxxxxxxxxxxxx\n```\n\nNow you can use a simpler command:\n\n```bash\ndocker run --env-file ./my_env_data -p 3020:3000 wiseindy/timer-for-google-assistant\n```\n\n#### Running with `docker-compose`\n\nIf using docker compose, download the [sample `docker-compose.yml` in this project](docker-compose.yml).\n\n* **Add your keys to `docker-compose.yml`**\n\\\nCreate two files `ifttt_event_key.secret` and `security_key.secret` which contain your IFTTT event key and security key respectively.\n\\\nWhen deploying with docker, any environment variable can be prefixed with `FILE__` (two underscores) to be used with docker secrets (recommended for `SECURITY_KEY` and `IFTTT_EVENT_KEY`).\n\n```yaml\n    ...\n    environment:\n        FILE__SECURITY_KEY: /run/secrets/timer_security_key\n        FILE__IFTTT_EVENT_KEY: /run/secrets/timer_ifttt_event_key\n        IFTTT_EVENT_OFF_SUFFIX: _off\n        IFTTT_EVENT_ON_SUFFIX: _on\n        \n  secrets:\n    timer_security_key:\n      file: ./security_key.secret\n    timer_ifttt_event_key:\n      file: ./ifttt_event_key.secret\n  ...\n```\n\n* **[NOT RECOMMENDED] Another way to add your keys to `docker-compose.yml`**\n\\\nAn alternative to using Docker secrets is to directly include the keys in your `docker-compose.yml` file. The above technique of using secrets is more secure and recommended over this method.\n\\\nInstead of using secrets in separate files, you can directly set the environment variables under the `environment` section to appropriate values.\n\n```yaml\n    ...\n    environment:\n        SECURITY_KEY: ChangeThisToSomethingSecure\n        IFTTT_EVENT_KEY: xxxxxxxxxxxxxxxxxxxxxx\n        IFTTT_EVENT_OFF_SUFFIX: _off\n        IFTTT_EVENT_ON_SUFFIX: _on\n    ...\n```\n\n[For information on what the environment variables mean, see this section below.](#create-a-env-file-in-the-root-directory-sample-values-can-be-seen-in-envexample)\n\nTo start the server, run:\n\n```bash\ndocker-compose up -d\n```\n\nTo stop, run:\n\n```bash\ndocker-compose down\n```\n\nNext, you'll need to set up triggers and actions in IFTTT. [Jump to section](#integrate-with-ifttt).\n\n## Manual installation without Docker\n\n### Prerequisites\n\n* An internet facing web server (so that IFTTT can make requests to your server)\n* [NodeJS](https://nodejs.org/en/) 12.18.3 or higher (lower versions may also work, but I haven't tested it)\n* An [IFTTT](https://ifttt.com/) account\n\n## Installation\n\n### Clone this repository\n\n``` bash\ngit clone https://github.com/wiseindy/timer-for-google-assistant.git\n```\n\n### Enter the directory and run `npm install`\n\n``` bash\ncd timer-for-google-assistant/app\nnpm install\n```\n\n### Create a `.env` file in the `/app` directory. Sample values can be seen in `/app/.env.example`\n\n``` bash\nPORT=3020\nSECURITY_KEY=ChangeThisToSomethingSecure\nIFTTT_EVENT_OFF_SUFFIX=_off\nIFTTT_EVENT_ON_SUFFIX=_on\nIFTTT_EVENT_KEY=xxxxxxxxxxxxxxxxxxxxxx\n```\n\n* `PORT` : (DEFAULT: `3000`, if not specified) This is the port number the application will use. You'll need to add this exception to your firewall rule. You can also use a reverse proxy. If you're using the docker image, this is the port used by the app, not the one exposed by the container; remember to change your port value accordingly in the docker command or your docker-compose.\n* `SECURITY_KEY` : (REQUIRED) Set this to a **unique** string and **do not share it with anyone**.\n``` diff\n- IMPORTANT! Make sure you change your SECURITY KEY to something secure and DO NOT use the default value.\n```\n* `IFTTT_EVENT_OFF_SUFFIX` : (REQUIRED) The suffix for the \"off\" action in IFTTT. For more details, please view [Integrate with IFTTT](#integrate-with-ifttt) section below.\n* `IFTTT_EVENT_ON_SUFFIX` : (REQUIRED) The suffix for the \"on\" action in IFTTT. For more details, please view [Integrate with IFTTT](#integrate-with-ifttt) section below.\n* `IFTTT_EVENT_KEY` : (REQUIRED) You can get your IFTTT key from [https://ifttt.com/maker_webhooks](https://ifttt.com/maker_webhooks). Click the **Documentation** button at the top to get your key.\\\n\\\n![IFTTT Webhooks page screenshot](/app/assets/ifttt_maker_webhooks.png?raw=true \"IFTTT Webhooks\")\n\\\n![IFTTT Webhooks key page screenshot](/app/assets/ifttt_maker_webhooks_key.png?raw=true \"IFTTT Webhooks key\")\n\n### Build the application\n\n```bash\nnpm run build\n```\n\n### Start the application\n\n``` bash\nnpm run start:prod\n```\n\nFor more options, view [Running the app](#running-the-app) section.\n\n---\n\n### Integrate with IFTTT\n\nYou will be creating two actions in IFTTT; one to turn off the device and another to turn it on. \n\nBoth these actions/applets will work by receiving a web request and triggering the device ON or OFF (using IFTTT's Webhooks feature).\n\n#### Set up webhooks\n\n1. Login to your [IFTTT](https://ifttt.com/) and create a new applet. For the `this` trigger, choose `Webhooks`.\\\n\\\n![IFTTT create a new applet](/app/assets/ifttt_webhooks_create.gif?raw=true \"IFTTT create a new applet\")\n\n2. Follow a consistent naming scheme for all events. Use the correct suffixes for your device events as specified in the `IFTTT_EVENT_OFF_SUFFIX` and `IFTTT_EVENT_ON_SUFFIX` parameters in the `.env` file above.\\\n\\\nFor example, if the device is a smart light, use `lights_off` and `lights_on` as the event names to turn the light OFF and ON respectively. DO NOT use inconsistent names like `lights_off` and `LIGHT_ON`.\\\n\\\n**Make sure you follow the SAME naming scheme for ALL events (they're case sensitive)**. \\\n\\\n![IFTTT name your event](/app/assets/ifttt_webhooks_trigger_event_name.gif?raw=true \"IFTTT name your event\")\n\n3. Next, choose your smart device from the list and select the action you'd like to carry out.\\\n\\\n![IFTTT set event target](/app/assets/ifttt_webhooks_trigger_event_target.gif?raw=true \"IFTTT set event target\")\n\n4. Repeat the above steps to create the `ON` trigger for your device.\n\n#### Configure IFTTT to receive commands from Google Assistant and forward to your server\n\n1. Create a new applet/action in IFTTT. For the `this` trigger, choose `Google Assistant`.\\\n\\\n![IFTTT create a new Google Assistant applet](/app/assets/ifttt_webhooks_create_google_assistant.gif?raw=true \"IFTTT create a new Google Assistant applet\")\n\n2. Select **Say a phrase with a number**\\\n\\\n![IFTTT Google Assistant applet](/app/assets/ifttt_google_assistant.gif?raw=true \"IFTTT Google Assistant applet\")\n\n3. Set your trigger phrase and the response. In this example, I want Google Assistant to turn on the lights and then turn it off after X minutes. Use `#` to specify where you'll say the number of minutes.\\\n\\\n![IFTTT Google Assistant number trigger](/app/assets/ifttt_google_assistant_number_trigger.png?raw=true \"IFTTT Google Assistant number trigger\")\n\n4. For the `that` action in your applet, select `Webhooks`. This will be used to make a web request to your server.\\\n\\\n![IFTTT set target to webhooks web request](/app/assets/ifttt_google_assistant_trigger_event_target.gif?raw=true \"IFTTT set target to webhooks web request\")\n\n5. Fill the action fields with the following values. For more information, refer to the [API Reference](#api-reference) below.\\\n\\\nFor the `URL` field, type in the domain/IP of your webserver running this application.\\\nThe API endpoint that handles requests is `/trigger`.\\\nSet the web request method to `POST`.\\\nSelect `application/json` as Content Type.\\\nFor the Body parameter, specify the following values:\\\n\\\n![IFTTT web request action](/app/assets/ifttt_webhooks_make_http_request.png?raw=true \"IFTTT web request action\")\n\nSample request body:\n\n``` \n{\n  \"key\":\"ChangeThisToSomethingSecure\",\n  \"durationInMinutes\":{{NumberField}},\n  \"deviceName\":\"lights\"\n}\n```\n\n* Make sure to use the same `key` that you specified in the `.env` file.\n* The device name `lights` should match the name used to create OFF/ON events: `lights_off` and `lights_on`. These values are case-sensitive.\n\n---\n\n## Running the app\n\n``` bash\n# development\nnpm run start\n\n# watch mode\nnpm run start:dev\n\n# production mode\nnpm run start:prod\n```\n\nThat's it! Try saying *\"Hey Google, turn on the lights for 2 minutes.\"* and if everything is setup right, Google Assistant will turn ON your lights and after two minutes, it should turn them OFF.\n\n## Test\n\n``` bash\n# unit tests\nnpm run test\n\n# e2e tests\nnpm run test:e2e\n\n# test coverage\nnpm run test:cov\n```\n\n## Support\n\n\u003ca href=\"https://www.buymeacoffee.com/wiseindy\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" style=\"height: 51px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n\n## Author\n\n* Website - [https://wiseindy.com](https://wiseindy.com/)\n* Twitter - [@wiseindy](https://twitter.com/wiseindy)\n\n## License\n\n  **Timer for Google Assistant** is [MIT licensed](LICENSE).\n  \n  All trademarks are the property of their respective owners.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiseindy%2Ftimer-for-google-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiseindy%2Ftimer-for-google-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiseindy%2Ftimer-for-google-assistant/lists"}