jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions
home-assistant.github.io/developers/websocket_api/index.html
Travis CI a6fbc15960 Site updated at 2017-10-21 23:33:52 UTC
2017-10-21 23:33:53 +00:00

567 lines
41 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>WebSocket API - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Home Assistant WebSocket API documentation">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/websocket_api/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="WebSocket API">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/websocket_api/">
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant WebSocket API documentation">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="WebSocket API">
<meta name="twitter:description" content="Home Assistant WebSocket API documentation">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection, print" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header class='site-header'>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
<li><a href="/cookbook/">Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
<li><a href='#' class='show-search'><i class="icon-search"></i></a></li>
</ul>
</nav>
<div class='search-container' style='display: none'>
<div class='search'>
<i class="icon-search"></i>
<input id='search' placeholder='Search the docs…'>
<a href='#' class='close'><i class="icon-remove-sign"></i></a>
</div>
</div>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
WebSocket API
</h1>
</header>
<hr class="divider">
<p>Home Assistant contains a WebSocket API. This API can be used to stream information from a Home Assistant instance to any client that implements WebSocket. Implementations in different languages:</p>
<ul>
<li><a href="https://github.com/home-assistant/home-assistant-js-websocket">JavaScript</a> - powers the frontend</li>
<li><a href="https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py">Python</a> - CLI client using <a href="https://async-websockets.readthedocs.io/en/latest/"><code class="highlighter-rouge">asyncws</code></a></li>
<li><a href="https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html">JavaScript/HTML</a> - WebSocket connection in your browser</li>
</ul>
<p>Connect your websocket implementation to <code class="highlighter-rouge">ws://localhost:8123/api/websocket</code>.</p>
<h2><a class="title-link" name="server-states" href="#server-states"></a> Server states</h2>
<ol>
<li>Client connects</li>
<li>Authentication phase starts
<ul>
<li>If no further authentication necessary for the user: go to 3</li>
<li>Server sends <code class="highlighter-rouge">auth_required</code> message</li>
<li>Client sends <code class="highlighter-rouge">auth</code> message</li>
<li>If <code class="highlighter-rouge">auth</code> message correct: go to 3.</li>
<li>Server sends <code class="highlighter-rouge">auth_invalid</code>. Go to 6.</li>
</ul>
</li>
<li>Send <code class="highlighter-rouge">auth_ok</code> message</li>
<li>Authentication phase ends.</li>
<li>Command phase starts.
a. Client can send commands.
b. Server can send results of previous commands.</li>
<li>Client or server disconnects session.</li>
</ol>
<p>During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to it’s origin.</p>
<h2><a class="title-link" name="message-format" href="#message-format"></a> Message format</h2>
<p>Each API message is a JSON serialized object containing a <code class="highlighter-rouge">type</code> key. After the authentication phase messages also must contain an <code class="highlighter-rouge">id</code>, an integer that contains the number of interactions.</p>
<p>Example of an auth message:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth"</span><span class="p">,</span><span class="w">
</span><span class="nt">"api_password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"supersecret"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="w"> </span><span class="err">5,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="s2">"event"</span><span class="p">,</span><span class="w">
</span><span class="nt">"event"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"data"</span><span class="p">:{},</span><span class="w">
</span><span class="nt">"event_type"</span><span class="p">:</span><span class="s2">"test_event"</span><span class="p">,</span><span class="w">
</span><span class="nt">"time_fired"</span><span class="p">:</span><span class="s2">"2016-11-26T01:37:24.265429+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"origin"</span><span class="p">:</span><span class="s2">"LOCAL"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h2><a class="title-link" name="authentication-phase" href="#authentication-phase"></a> Authentication phase</h2>
<p>When a client connects to the server, the server will test if the client is authenticated. Authentication will not be necessary if no api_password is set or if the user fulfills one of the other criteria for authentication (trusted network, password in url/header).</p>
<p>If no authentication is needed, the authentication phase will complete and the server will send an <code class="highlighter-rouge">auth_ok</code> message.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth_ok"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>If authentication is necessary, the server sends out <code class="highlighter-rouge">auth_required</code>.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth_required"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>This means that the next message from the client should be an auth message:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth"</span><span class="p">,</span><span class="w">
</span><span class="nt">"api_password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"supersecret"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>If the client supplies valid authentication, the authentication phase will complete by the server sending the <code class="highlighter-rouge">auth_ok</code> message:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth_ok"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>If the data is incorrect, the server will reply with <code class="highlighter-rouge">auth_invalid</code> message and disconnect the session.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth_invalid"</span><span class="p">,</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Invalid password"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h2><a class="title-link" name="command-phase" href="#command-phase"></a> Command phase</h2>
<p>During this phase the client can give commands to the server. The server will respond to each command with a <code class="highlighter-rouge">result</code> message indicating when the command is done and if it was successful.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">6</span><span class="err">.</span><span class="w">
</span><span class="s2">"type"</span><span class="err">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="err">//</span><span class="w"> </span><span class="err">Can</span><span class="w"> </span><span class="err">contain</span><span class="w"> </span><span class="err">extra</span><span class="w"> </span><span class="err">result</span><span class="w"> </span><span class="err">info</span><span class="w">
</span><span class="nt">"result"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h2><a class="title-link" name="subscribe-to-events" href="#subscribe-to-events"></a> Subscribe to events</h2>
<p>The command <code class="highlighter-rouge">subscribe_events</code> will subscribe your client to the event bus. You can either listen to all events or to a specific event type. If you want to listen to multiple event types, you will have to send multiple <code class="highlighter-rouge">subscribe_events</code> commands.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"subscribe_events"</span><span class="p">,</span><span class="w">
</span><span class="err">//</span><span class="w"> </span><span class="err">Optional</span><span class="w">
</span><span class="nt">"event_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"state_changed"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message to indicate that the subscription is active.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="nt">"result"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>For each event that matches, the server will send a message of type <code class="highlighter-rouge">event</code>. The <code class="highlighter-rouge">id</code> in the message will point at the original <code class="highlighter-rouge">id</code> of the <code class="highlighter-rouge">listen_event</code> command.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="s2">"event"</span><span class="p">,</span><span class="w">
</span><span class="nt">"event"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"data"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="s2">"light.bed_light"</span><span class="p">,</span><span class="w">
</span><span class="nt">"new_state"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="s2">"light.bed_light"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="s2">"2016-11-26T01:37:24.265390+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="s2">"on"</span><span class="p">,</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"rgb_color"</span><span class="p">:[</span><span class="w">
</span><span class="mi">254</span><span class="p">,</span><span class="w">
</span><span class="mi">208</span><span class="p">,</span><span class="w">
</span><span class="mi">0</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="nt">"color_temp"</span><span class="p">:</span><span class="mi">380</span><span class="p">,</span><span class="w">
</span><span class="nt">"supported_features"</span><span class="p">:</span><span class="mi">147</span><span class="p">,</span><span class="w">
</span><span class="nt">"xy_color"</span><span class="p">:[</span><span class="w">
</span><span class="mf">0.5</span><span class="p">,</span><span class="w">
</span><span class="mf">0.5</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="nt">"brightness"</span><span class="p">:</span><span class="mi">180</span><span class="p">,</span><span class="w">
</span><span class="nt">"white_value"</span><span class="p">:</span><span class="mi">200</span><span class="p">,</span><span class="w">
</span><span class="nt">"friendly_name"</span><span class="p">:</span><span class="s2">"Bed Light"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nt">"last_updated"</span><span class="p">:</span><span class="s2">"2016-11-26T01:37:24.265390+00:00"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nt">"old_state"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="s2">"light.bed_light"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="s2">"2016-11-26T01:37:10.466994+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="s2">"off"</span><span class="p">,</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"supported_features"</span><span class="p">:</span><span class="mi">147</span><span class="p">,</span><span class="w">
</span><span class="nt">"friendly_name"</span><span class="p">:</span><span class="s2">"Bed Light"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nt">"last_updated"</span><span class="p">:</span><span class="s2">"2016-11-26T01:37:10.466994+00:00"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nt">"event_type"</span><span class="p">:</span><span class="s2">"state_changed"</span><span class="p">,</span><span class="w">
</span><span class="nt">"time_fired"</span><span class="p">:</span><span class="s2">"2016-11-26T01:37:24.265429+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"origin"</span><span class="p">:</span><span class="s2">"LOCAL"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="unsubscribing-from-events" href="#unsubscribing-from-events"></a> Unsubscribing from events</h3>
<p>You can unsubscribe from previously created subscription events. Pass the id of the original subscription command as value to the subscription field.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"unsubscribe_events"</span><span class="p">,</span><span class="w">
</span><span class="nt">"subscription"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message to indicate that unsubscribing was successful.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="nt">"result"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="calling-a-service" href="#calling-a-service"></a> Calling a service</h3>
<p>This will call a service in Home Assistant. Right now there is no return value. The client can listen to <code class="highlighter-rouge">state_changed</code> events if it is interested in changed entities as a result of a service call.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">24</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"call_service"</span><span class="p">,</span><span class="w">
</span><span class="nt">"domain"</span><span class="p">:</span><span class="w"> </span><span class="s2">"light"</span><span class="p">,</span><span class="w">
</span><span class="nt">"service"</span><span class="p">:</span><span class="w"> </span><span class="s2">"turn_on"</span><span class="p">,</span><span class="w">
</span><span class="err">//</span><span class="w"> </span><span class="err">Optional</span><span class="w">
</span><span class="nt">"service_data"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"light.kitchen"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will indicate with a message indicating that the service is done executing.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">24</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="nt">"result"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="fetching-states" href="#fetching-states"></a> Fetching states</h3>
<p>This will get a dump of all the current states in Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"get_states"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message containing the states.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="nt">"result"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="fetching-config" href="#fetching-config"></a> Fetching config</h3>
<p>This will get a dump of the current config in Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"get_config"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message containing the config.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="nt">"result"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="fetching-services" href="#fetching-services"></a> Fetching services</h3>
<p>This will get a dump of the current services in Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"get_services"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message containing the services.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="nt">"result"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="fetching-panels" href="#fetching-panels"></a> Fetching panels</h3>
<p>This will get a dump of the current registered panels in Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"get_panels"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message containing the current registered panels.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="nt">"result"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h2><a class="title-link" name="error-handling" href="#error-handling"></a> Error handling</h2>
<p>If an error occurs, the <code class="highlighter-rouge">success</code> key in the <code class="highlighter-rouge">result</code> message will be set to <code class="highlighter-rouge">false</code>. It will contain an <code class="highlighter-rouge">error</code> key containing an object with two keys: <code class="highlighter-rouge">code</code> and <code class="highlighter-rouge">message</code>.</p>
<table>
<thead>
<tr>
<th>Code</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>A non-increasing identifier has been supplied.</td>
</tr>
<tr>
<td>2</td>
<td>Received message is not in expected format (voluptuous validation error).</td>
</tr>
<tr>
<td>3</td>
<td>Requested item cannot be found</td>
</tr>
</tbody>
</table>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">12</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="s2">"result"</span><span class="p">,</span><span class="w">
</span><span class="nt">"success"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w">
</span><span class="nt">"error"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"code"</span><span class="p">:</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Message incorrectly formatted: expected str for dictionary value @ data['event_type']. Got 100"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/websocket_api.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
<h1 class="title delta">Development Guide</h1>
<ul class='divided sidebar-menu'>
<li>
<a href='/developers/'>Introduction </a>
<ul>
<li><a href='/developers/architecture/'>Architecture </a></li>
<li><a href='/developers/architecture_components/'>Components </a></li>
</ul>
</li>
<li>
<a href='/developers/development/'>Starting with Development </a>
<ul>
<li><a href='/developers/development_environment/'>Setting up Environment </a></li>
<li><a href='/developers/development_submitting/'>Submit your Work </a></li>
<li><a href='/developers/development_checklist/'>Checklist </a></li>
<li><a href='/developers/development_guidelines/'>Style guidelines </a></li>
<li><a href='/developers/development_testing/'>Testing </a></li>
<li><a href='/developers/development_catching_up/'>Catching up with Reality </a></li>
<li><a href='/developers/development_validation/'>Validation </a></li>
</ul>
</li>
<li>
<a href='/developers/development_101/'>Development 101 </a>
<ul>
<li><a href='/developers/development_hass_object/'>Hass object </a></li>
<li><a href='/developers/development_events/'>Events </a></li>
<li><a href='/developers/development_states/'>States </a></li>
<li><a href='/developers/development_services/'>Services </a></li>
<li><a href='/developers/development_config/'>Config </a></li>
</ul>
</li>
<li>
<a href='/developers/add_new_platform/'>Creating a new platform (to support a new device) </a>
<ul>
<li><a href='/developers/code_review_platform/'>Checklist creating a platform </a></li>
<li><a href='/developers/platform_example_sensor/'>Example sensor platform </a></li>
<li><a href='/developers/platform_example_light/'>Example light platform </a></li>
</ul>
</li>
<li>
<a href='/developers/creating_components/'>Adding a new component </a>
<ul>
<li><a href='/developers/code_review_component/'>Checklist creating a component </a></li>
<li><a href='/developers/component_loading/'>Loading components </a></li>
<li><a href='/developers/component_deps_and_reqs/'>Requirements & Dependencies </a></li>
<li><a href='/developers/component_events/'>Handling events </a></li>
<li><a href='/developers/component_states/'>States </a></li>
<li><a href='/developers/component_visibility/'>Visibility </a></li>
<li><a href='/developers/component_generic_discovery/'>Loading Platforms </a></li>
<li><a href='/developers/component_discovery/'>Component Discovery </a></li>
</ul>
</li>
<li>
<a href='/developers/intent/'>Intents (handling voice responses) </a>
<ul>
<li><a href='/developers/intent/firing/'>Firing intents </a></li>
<li><a href='/developers/intent/handling/'>Handling intents </a></li>
<li><a href='/developers/intent/conversation/'>Registering sentences </a></li>
</ul>
</li>
<li>
<a href='/developers/asyncio/'>Asynchronous Programming </a>
<ul>
<li><a href='/developers/asyncio_101/'>Introduction to asyncio </a></li>
<li><a href='/developers/asyncio_categorizing_functions/'>Categorizing Functions </a></li>
<li><a href='/developers/asyncio_working_with_async/'>Working with Async </a></li>
<li><a href='/developers/asyncio_misc/'>Miscellaneous </a></li>
</ul>
</li>
<li>
<a href='/developers/frontend/'>Frontend Development </a>
<ul>
<li><a href='/developers/frontend_add_card/'>Add State Card </a></li>
<li><a href='/developers/frontend_add_more_info/'>Add More Info Dialog </a></li>
<li><a href='/developers/frontend_creating_custom_panels/'>Add Custom Panels </a></li>
<li><a href='/developers/frontend_creating_custom_ui/'>Add Custom UI </a></li>
</ul>
</li>
<li>
<a href='/developers/hassio/architecture/'>Hass.io architecture </a>
<ul>
<li><a href='/developers/hassio/debugging/'>Debugging Hass.io </a></li>
</ul>
</li>
<li>
<a href='/developers/hassio/addon_development/'>Hass.io Add-on Development </a>
<ul>
<li><a href='/developers/hassio/addon_tutorial/'>Tutorial: Making your first add-on </a></li>
<li><a href='/developers/hassio/addon_config/'>Configuration </a></li>
<li><a href='/developers/hassio/addon_communication/'>Communication </a></li>
<li><a href='/developers/hassio/addon_testing/'>Local Testing </a></li>
<li><a href='/developers/hassio/addon_publishing/'>Publishing </a></li>
<li><a href='/developers/hassio/addon_repository/'>Repositories </a></li>
</ul>
</li>
<li>
<a href='/developers/api/'>API </a>
<ul>
<li><a href='https://dev-docs.home-assistant.io/en/dev/'>Python API </a></li>
<li><a class='active' href='/developers/websocket_api/'>Websocket API </a></li>
<li><a href='/developers/rest_api/'>REST API </a></li>
<li><a href='/developers/python_api/'>Python REST API </a></li>
<li><a href='/developers/server_sent_events/'>Server-sent events </a></li>
</ul>
</li>
<li>
<a href='/developers/documentation/'>Website/Documentation </a>
<ul>
<li><a href='/developers/documentation/standards/'>Standards </a></li>
<li><a href='/developers/documentation/create_page/'>Create a new page </a></li>
</ul>
</li>
<li><a href='/developers/helpers/'>Online helpers </a></li>
<li><a href='/developers/releasing/'>Releasing </a></li>
<li><a href='/developers/maintenance/'>Maintenance </a></li>
<li>
Governance
<ul>
<li><a href='/developers/cla/'>Contributor License Agreement </a></li>
<li><a href='/privacy/'>Privacy Policy </a></li>
<li><a href='/tos/'>Terms of Service </a></li>
<li><a href='/code_of_conduct/'>Code of Conduct </a></li>
<li><a href='/developers/credits/'>Credits </a></li>
<li><a href='/developers/license/'>License </a></li>
</ul>
</li>
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a> (no support!).<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">home-assistant.io</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
</div>
</div>
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css" />
<script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script>
<script type="text/javascript">
docsearch({
apiKey: 'ae96d94b201c5444c8a443093edf3efb',
indexName: 'home-assistant',
inputSelector: '#search',
debug: false // Set debug to true if you want to inspect the dropdown
});
document.querySelector('.search .close').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'none';
});
document.querySelector('.show-search').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'block';
document.getElementById('toggle').checked = false;
document.querySelector('.search-container input').focus();
});
</script>
</body>
</html>
Reference in a new issue View git blame Copy permalink