Habitica

The Habitca integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] enables you to monitor your adventurer’s progress and stats in Home Assistant and seamlessly integrates your to-do’s and daily tasks.

Prerequisites for Habitica integration

• To set up the Habitica integration, you must first have an active Habitica account. You can register for an account at Habitica.com.
• During the setup process in Home Assistant, you can choose between two login options:
  • “Login to Habitica”, which allows you to log in with your username or email and password.
  • “Login to other instances”, which requires your User ID and API Token. The User ID and API Token can be retrieved by logging into your Habitica account, navigating to the Settings menu, and selecting Site Data.
  • Additionally, you will need to provide the URL for the Habitica instance you wish to connect to; the default URL is https://habitica.com, but you can specify a different URL if you are using an alternative Habitica instance or a self-hosted instance.

Configuration

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

Sensors

• Class: Indicates the class of your character (Warrior, Rogue, Healer, or Mage).
• Display name: Shows the character’s display name.
• Experience: Displays the current experience points of the character (for example, “144 XP”).
• Gold: Shows the amount of gold owned by your character (for example, “22.29 GP”).
• Health: Shows the current health points of the character (for example, “42 HP”).
• Level: Displays the current level of the character.
• Mana: Displays the current mana points of your character (for example, “61 MP”).
• Max. mana: Indicates the maximum mana points your character can have at the current level (for example, “70 MP”).
• Next level: Indicates the remaining experience points needed to reach the next level (for example, “440 XP”).
• Habits: Shows the number of habits being tracked (for example, “4 tasks”).
• Rewards: Displays the rewards that can be redeemed (for example, “1 task”)

To-do lists

The following Habitica tasks are available as to-do lists in Home Assistant. You can add, delete, edit and check-off completed tasks

• To-Do’s: Displays a comprehensive list of active and completed to-dos. Each to-do includes its due date if applicable, allowing you to check them off, edit them, delete them, and create new to-dos seamlessly.
• Dailies: Shows the daily tasks that need to be completed today or in the future. Tasks completed yesterday can still be marked off as “yesterdailies” until a new day starts.

Button controls

• Start my day: Initiates daily routine actions in Habitica, including resetting your dailies, deal damage from unfinished dailies and quest bosses, habits adjustment, buff expiration, and mana regeneration based on completed dailies.
• Revive from death: Allows your character to revive from death in Habitica. Upon revival, HP is fully restored, but your character will lose all gold, 1 level, all experience points, one stat point, and one piece of equipment.
• Buy a health potion: Allows your character to purchase a health potion in Habitica. Instantly applies the potion upon purchase, healing 15 HP at a cost of 25 GP.
• Allocate all stat points: Assigns all unallocated stat points based on the previously set automatic allocation method. If no method is set, all points are assigned to strength (STR).

Switch controls

• Rest in the Inn: When enabled, allows your character to rest in the inn in Habitica, pausing damage dealt from dailies and quest bosses.

API Service

At runtime, you will be able to use the 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 an action called habitica.api_call. To call it, you should specify these keys in the data:

A successful run of this action will fire an event habitica_api_call_success.

Let’s consider some examples on how to use the action

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

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