Toggl Slash Command for Slack
- Show a list of projects and their corresponding IDs in a given workspace
- Show a list of tasks associated with a given project
- Add time entries to Toggl straight from Slack's message input box
Setup & Installation
- You must have PHP 5.3.2+ installed locally and on an accessible server.
- You need Composer installed locally to install the third-party dependencies.
Two third-party libraries are dependencies included via Composer:
- Clone or download this repository onto your local machine
- Install Composer in this repository if you don't already have it
- Open a command line terminal and navigate to this directory.
php composer.phar installvia the command line to install the third-party dependencies
Configure the variables file.
- Copy the variables-dist.php file to
- Fill out the Slack token you got while setting up the slash command.
- Fill out users' Slack usernames with their corresponding Toggl API keys in the array. They can get those keys at the bottom of https://toggl.com/app/profile.
- Enter a workspace ID for your team. to find yours, log in to Toggl, then go to https://www.toggl.com/api/v8/workspaces. Pick the ID of the workspace you want to use. Don't wrap it in quotes; it needs to be an integer.
- Set your team's default timezone. Right now it is set to
- Save the file as
variables.phpin the same directory and you are good to go!
Upload to a server with a valid SSL certificate
- Once the dependencies are installed, upload the whole directory to a server running PHP 5.3.2+
- Ensure you have a valid SSL certificate. Slash command URLs must support HTTPS and serve a valid SSL certificate. Self-signed certificates are not allowed. Check out CloudFlare for an easy way to obtain a valid certificate.
Configure a custom slash command on Slack
- Log in to your Slack account and navigate to Custom Integration to set up a custom slash command.
- Click Add Configuration.
- Choose the command you want (I use
- Fill out the path to the
slash_parsing.phpfile on your server from above.
- Set the method to be POST.
- Copy the token and save it for
- Set a fun name and icon. I use Toggl's logo from their media kit.
/toggl help- Shows the syntax below
/toggl about- Shows info about this slash command and directs people to this repository
/toggl show projects- Shows the list of projects associated with API key of the user the workspace ID set in
/toggl show tasks [project ID]- Shows a list of tasks associates with a given project ID.
/toggl show tasks 10692310
/toggl add -p [project ID] -d "description" -t [duration in hh:mm:ss]- Adds a time entry to Toggl. Don't include the [ ].
add -d "Weekly check-in" -p 10692310 -t 00:15:00
- Additional options:
--date [mm/dd/yy]- Adds the time entry to a specific date. If none is passed, it defaults to today's date.
--task [task id]- Adds the time entry to a task ID. See above to find your task ID for a project.
- I added basic logging to CSV for usage stats and debugging. This happens individually per project, stored in
log.csv. Nothing is transmitted back to me.
- If you'd prefer to not log usage, simply comment out lines 14-19 in
- Since the log includes a Slack token, you'll want to deny access to
log.csvon your webserver. I achieved that via my
- First commit
- Basic logging for usage stats and debugging
- Ordering projects by client in
- Allow users to access projects in any of their workspaces, not just the one currently set in
- Checking and error handling for the
addcommand (currently returns nothing when it fails)
- Figure out how to get better error messages back from Toggl when a project or task doesn't exist (currently returns nothing when it fails)
- Figure out how to pass error messages from GetOptionKit back to Slack about improper formatting
addcommand with tagging
- Make a command for creating projects and tasks via the guzzle-toggl API client
- Add basic reporting functionality from the Toggl Reports API
- If you find a bug, open an issue and I'll check it out.
- If you've fixed a bug on your own or added a new feature, open a pull request and I'll review it. Thanks!