home-assistant.io/source/_components/habitica.markdown

layout, title, description, date, sidebar, comments, sharing, footer, logo, ha_category, ha_version, ha_iot_class

layout	title	description	date	sidebar	comments	sharing	footer	logo	ha_category	ha_version	ha_iot_class
page	Habitica	Instructions on enabling Habitica support for your Home Assistant	2018-08-09 00:00	true	false	true	true	habitica.png	Hub	0.78	Cloud Polling

This component allows you to monitor and manage your Habitica profile. This component 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. This component enables usage of sensor.habitica platform. To use the component you should use this example configuration:

# Minimum viable configuration.yaml entry
habitica:
  - api_user: YOUR_USER_ID
    api_key: YOUR_API_KEY

You can specify several users, providing api_user and api_key for each. 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.

{% configuration %} api_user: description: "Habitica's API user ID. This value can be grabbed from account setting" required: true type: string api_key: description: "Habitica's API password (token). This value can be grabbed from account setting by pressing 'Show API token'" required: true type: string name: description: "Override for Habitica's username. Will be used for service calls" required: false type: string default: Deduced at startup url: description: "URL to your Habitica instance, if you are hosting your own" required: false type: string default: http://habitica.com sensors: description: List of sensors to generate for this user. If you don't specify this entry then the default (all sensors) will be generated. If you specify this entry empty then no sensors will be generated. required: false type: list default: all (name, hp, maxHealth, mp, maxMP, exp, toNextLevel, lvl, gp, class) {% endconfiguration %}

{% linkable_title 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:

Service data attribute	Required	Type	Description
name	yes	string	Habitica's username as per configuration.yaml entry.
path	yes	[string]	Items from API URL in form of an array with method attached at the end. See the example below.
args	no	map	Any additional json or url parameter arguments. See the example below and apidoc.

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

Event data attribute	Type	Description
name	string	Copied from service data attribute.
path	[string]	Copied from service data attribute.
data	map	Deserialized data field of JSON object Habitica's server returned in response to api call. For more info see docs.

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 docs.

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"}
}