164 lines
6.4 KiB
Markdown
164 lines
6.4 KiB
Markdown
---
|
|
title: Habitica
|
|
description: Instructions on enabling Habitica support for your Home Assistant
|
|
ha_category:
|
|
- Hub
|
|
- Sensor
|
|
ha_release: 0.78
|
|
ha_iot_class: Cloud Polling
|
|
ha_domain: habitica
|
|
ha_platforms:
|
|
- sensor
|
|
ha_codeowners:
|
|
- '@ASMfreaK'
|
|
- '@leikoilja'
|
|
ha_config_flow: true
|
|
ha_integration_type: integration
|
|
---
|
|
|
|
This integration allows you to monitor and manage your Habitica profile. This integration exposes the [Habitica's API](https://habitica.com/apidoc/) 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](https://habitica.com/) 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](https://habitica.com/) in Home Assistant. The following sensors will be available:
|
|
|
|
- Habits
|
|
- Daily tasks
|
|
- Todo tasks
|
|
- Rewards
|
|
|
|
{% include integrations/config_flow.md %}
|
|
|
|
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](https://habitica.com/user/settings/api)"
|
|
required: true
|
|
type: string
|
|
api_key:
|
|
description: "Habitica's API password (token). This value can be grabbed from [account setting](https://habitica.com/user/settings/api) 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: https://habitica.com
|
|
{% endconfiguration %}
|
|
|
|
### 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](https://habitica.com/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 the [API documentation](https://habitica.com/apidoc/). |
|
|
|
|
#### 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](https://habitica.com/apidoc/#api-Task-CreateUserTasks) 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](https://github.com/ASMfreaK/habitipy/blob/master/README.md).
|
|
* The `args` key is more or less described in the [API documentation](https://habitica.com/apidoc/).
|
|
|
|
Combining all together:
|
|
call `habitica.api_call` with data
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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](/dashboards/markdown/) to a dashboard with the following code:
|
|
|
|
{% raw %}
|
|
|
|
```jinja
|
|
{% for key, value in states.sensor.habitica_USER_dailys.attributes.items() %}
|
|
{% if 'text' in value | string %}
|
|
{{ loop.index }}. {{ value.text }}
|
|
{% endif %}
|
|
{% endfor %}
|
|
```
|
|
|
|
{% endraw %}
|