Habitica

This integration allows you to monitor and manage your Habitica profile. This integration exposes the Habitica’s API as a Home Assistant service. It supports multiple users and allows you to automate checking out your habits and daily tasks or casting magics using Home Assistant.

There is currently support for the following device types within Home Assistant:

Player data: allows you to view and monitor your player data from Habitica in Home Assistant. The following sensors will be available:

• Player’s name
• Player’s health points
• Player’s max health
• Player’s mana points
• Player’s max mana points
• Player’s experience
• Player’s experience to the next level
• Player’s level
• Player’s gold pieces
• Player’s class

Tasks: allows you to view and monitor your tasks from Habitica in Home Assistant. The following sensors will be available:

• Habits
• Daily tasks
• Todo tasks
• Rewards

Configuration

To add the Habitica integration to your Home Assistant instance, use this My button:

At runtime you will be able to use API for each respective user by their Habitica’s username. You can override this by passing name key, this value will be used instead of the username. If you are hosting your own instance of Habitica, you can specify a URL to it in url key.

API Service Parameters

The API is exposed to Home Assistant as a service called habitica.api_call. To call it you should specify this keys in service data:

A successful call to this service will fire an event habitica_api_call_success.

Let’s consider some examples on how to call the service.

For example, let’s say that there is a configured habitica platform for user xxxNotAValidNickxxx with their respective api_user and api_key. Let’s create a new task (a todo) for this user via Home Assistant. There is an API call for this purpose. To create a new task one should hit https://habitica.com/api/v3/tasks/user endpoint with POST request with a JSON object with task properties. So let’s call the API on habitica.api_call.

• The name key becomes xxxNotAValidNickxxx.
• The path key is trickier.
  • Remove https://habitica.com/api/v3/ at the beginning of the endpoint URL.
  • Split the remaining on slashes (/) and append the lowercase method at the end.
  • You should get ["tasks", "user", "post"]. To get a better idea of the API you are recommended to try all of the API calls in IPython console using this package.
• The args key is more or less described in the API documentation.

Combining all together: call habitica.api_call with data

{
  "name": "xxxNotAValidNickxxx",
  "path": ["tasks", "user", "post"],
  "args": {"text": "Use API from Home Assistant", "type": "todo"}
}

This call will create a new todo on xxxNotAValidNickxxx’s account with text Use API from Home Assistant like this:

Also an event habitica_api_call_success will be fired with the following data:

{
  "name": "xxxNotAValidNickxxx",
  "path": ["tasks", "user", "post"],
  "data": {
    "challenge": {},
    "group": {"approval": {"required": false,
     "approved": false,
     "requested": false},
    "assignedUsers": [],
    "sharedCompletion": "recurringCompletion"},
    "completed": false,
    "collapseChecklist": false,
    "type": "todo",
    "notes": "",
    "tags": [],
    "value": 0,
    "priority": 1,
    "attribute": "str",
    "text": "Use API from Home Assistant",
    "checklist": [],
    "reminders": [],
    "_id": "NEW_TASK_UUID",
    "createdAt": "2018-08-09T18:03:27.759Z",
    "updatedAt": "2018-08-09T18:03:27.759Z",
    "userId": "xxxNotAValidNickxxx's ID",
    "id": "NEW_TASK_UUID"}
}

Templating

sensor.habitica_USER_dailys, sensor.habitica_USER_habits, sensor.habitica_USER_rewards, and sensor.habitica_USER_todos have state attributes listing the user’s respective tasks. For example, you can see this information in Developer Tools -> States -> sensor.habitica_USER_dailys -> Attributes, or by adding a Markdown card to a dashboard with the following code:

{% for key, value in states.sensor.habitica_USER_dailys.attributes.items() %}
  {% if 'text' in value | string %}
    {{ loop.index }}. {{ value.text }}
  {% endif %}
{% endfor %}