This repository has been archived by the owner on Apr 12, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
docs.candyhouse.co.html
915 lines (761 loc) · 41.5 KB
/
docs.candyhouse.co.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
<title>CANDY HOUSE Developer Reference</title>
<style>
.highlight table td { padding: 5px; }
.highlight table pre { margin: 0; }
.highlight .gh {
color: #999999;
}
.highlight .sr {
color: #f6aa11;
}
.highlight .go {
color: #888888;
}
.highlight .gp {
color: #555555;
}
.highlight .gs {
}
.highlight .gu {
color: #aaaaaa;
}
.highlight .nb {
color: #f6aa11;
}
.highlight .cm {
color: #75715e;
}
.highlight .cp {
color: #75715e;
}
.highlight .c1 {
color: #75715e;
}
.highlight .cs {
color: #75715e;
}
.highlight .c, .highlight .cd {
color: #75715e;
}
.highlight .err {
color: #960050;
}
.highlight .gr {
color: #960050;
}
.highlight .gt {
color: #960050;
}
.highlight .gd {
color: #49483e;
}
.highlight .gi {
color: #49483e;
}
.highlight .ge {
color: #49483e;
}
.highlight .kc {
color: #66d9ef;
}
.highlight .kd {
color: #66d9ef;
}
.highlight .kr {
color: #66d9ef;
}
.highlight .no {
color: #66d9ef;
}
.highlight .kt {
color: #66d9ef;
}
.highlight .mf {
color: #ae81ff;
}
.highlight .mh {
color: #ae81ff;
}
.highlight .il {
color: #ae81ff;
}
.highlight .mi {
color: #ae81ff;
}
.highlight .mo {
color: #ae81ff;
}
.highlight .m, .highlight .mb, .highlight .mx {
color: #ae81ff;
}
.highlight .sc {
color: #ae81ff;
}
.highlight .se {
color: #ae81ff;
}
.highlight .ss {
color: #ae81ff;
}
.highlight .sd {
color: #e6db74;
}
.highlight .s2 {
color: #e6db74;
}
.highlight .sb {
color: #e6db74;
}
.highlight .sh {
color: #e6db74;
}
.highlight .si {
color: #e6db74;
}
.highlight .sx {
color: #e6db74;
}
.highlight .s1 {
color: #e6db74;
}
.highlight .s {
color: #e6db74;
}
.highlight .na {
color: #a6e22e;
}
.highlight .nc {
color: #a6e22e;
}
.highlight .nd {
color: #a6e22e;
}
.highlight .ne {
color: #a6e22e;
}
.highlight .nf {
color: #a6e22e;
}
.highlight .vc {
color: #ffffff;
}
.highlight .nn {
color: #ffffff;
}
.highlight .nl {
color: #ffffff;
}
.highlight .ni {
color: #ffffff;
}
.highlight .bp {
color: #ffffff;
}
.highlight .vg {
color: #ffffff;
}
.highlight .vi {
color: #ffffff;
}
.highlight .nv {
color: #ffffff;
}
.highlight .w {
color: #ffffff;
}
.highlight {
color: #ffffff;
}
.highlight .n, .highlight .py, .highlight .nx {
color: #ffffff;
}
.highlight .ow {
color: #f92672;
}
.highlight .nt {
color: #f92672;
}
.highlight .k, .highlight .kv {
color: #f92672;
}
.highlight .kn {
color: #f92672;
}
.highlight .kp {
color: #f92672;
}
.highlight .o {
color: #f92672;
}
</style>
<link href="stylesheets/screen.css" rel="stylesheet" media="screen" />
<link href="stylesheets/print.css" rel="stylesheet" media="print" />
<script src="javascripts/all.js"></script>
<link rel="shortcut icon" href="https://s3.amazonaws.com/candyhouse.co/images/favicon.png" type="image/png">
</head>
<body class="index" data-languages="["shell"]">
<a href="#" id="nav-button">
<span>
NAV
<img src="images/navbar.png" alt="Navbar" />
</span>
</a>
<div class="tocify-wrapper">
<img src="images/logo.png" alt="Logo" />
<div class="lang-selector">
<a href="#" data-language-name="shell">shell</a>
</div>
<div class="search">
<input type="text" class="search" id="input-search" placeholder="Search">
</div>
<ul class="search-results"></ul>
<div id="toc">
</div>
<ul class="toc-footer">
<li><a href='mailto:[email protected]'>Email [email protected]</a></li>
</ul>
</div>
<div class="page-wrapper">
<div class="dark-box"></div>
<div class="content">
<h1 id="introduction">Introduction</h1>
<p><strong>This documentation is for Version 3 of CANDY HOUSE’s Sesame API. You can find documentation for Version 1/Version 2 <a href="v1.html">here</a>.</strong></p>
<p>Welcome to the CANDY HOUSE Developer Site! We use RESTful API to provide basic manipulation of the <a href="https://candyhouse.co/products/sesame">Sesame smart lock</a>, including:</p>
<ul>
<li>Get Sesame lock/unlock status</li>
<li>Get battery status</li>
<li>Lock and unlock Sesame</li>
<li>Sync Sesame status</li>
<li>Get results for lock, unlock, and sync commands</li>
</ul>
<p>Many new functions are still under development and will be coming soon, so stay tuned!</p>
<p>Please note that in order to enable API for your Sesame, you must be the owner of Sesame and have it paired with the <a href="https://candyhouse.co/products/wi-fi-access-point">Wi-Fi Access Point</a>.</p>
<p>To set up your Wi-Fi Access Point, <a href="https://candyhouse.co/blogs/sesame/how-to-setup-your-wi-fi-access-point">follow these instructions</a> to link your Wi-Fi Access Point to your home Wi-Fi network and pair it with your Sesame. </p>
<p><strong>IMPORTANT</strong>: Once you have linked your Sesame to the Wi-Fi Access Point, go to <strong>Sesame Status > Change Settings > Integration</strong> and toggle this setting to <strong>ON</strong> to enable the API.</p>
<p>If you would like to suggest changes to the documentation or if you find any bugs, please feel free to <a href="mailto:[email protected]">contact us</a>.</p>
<h2 id="endpoint">Endpoint</h2>
<p>All requests should be prefixed with:</p>
<p><code class="prettyprint">https://api.candyhouse.co/public</code></p>
<h2 id="parameters">Parameters</h2>
<blockquote>
<p>Pass parameter in json body</p>
</blockquote>
<pre class="highlight shell tab-shell"><code>curl -H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-X POST -d <span class="s1">'{"param1":"value1", "param2":"value2"}'</span>
</code></pre>
<blockquote>
<p>Pass parameter in query strings</p>
</blockquote>
<pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://api.candyhouse.co/public?param1=value1&param2=value2"</span>
</code></pre>
<p>Always pass parameters in json body for POST and query strings for GET.</p>
<h1 id="authentication">Authentication</h1>
<pre class="highlight shell tab-shell"><code>curl -H <span class="s2">"Authorization: YOUR_AUTH_TOKEN"</span>
</code></pre>
<p>Please create the your auth token by logging into the <a href="https://my.candyhouse.co">CANDY HOUSE Dashboard</a> with your CANDY HOUSE account. Click on “API Settings” in the sidebar, verify your identity, then add a new API key. This API key is your auth token. Every request must have the auth token set in the <code class="prettyprint">Authorization</code> header.</p>
<h1 id="sesame-api">Sesame API</h1>
<h2 id="get-sesame-list">Get Sesame list</h2>
<pre class="highlight shell tab-shell"><code>curl -H <span class="s2">"Authorization: YOUR_AUTH_TOKEN"</span> <span class="se">\</span>
https://api.candyhouse.co/public/sesames
</code></pre><pre class="highlight javascript tab-javascript"><code> <span class="p">[</span>
<span class="p">{</span>
<span class="s2">"device_id"</span><span class="p">:</span> <span class="s2">"00000000-0000-0000-0000-000000000000"</span><span class="p">,</span>
<span class="s2">"serial"</span><span class="p">:</span> <span class="s2">"ABC1234567"</span>
<span class="s2">"nickname"</span><span class="p">:</span> <span class="s2">"Front door"</span><span class="p">,</span>
<span class="p">},</span> <span class="p">{</span>
<span class="s2">"device_id"</span><span class="p">:</span> <span class="s2">"00000000-0000-0000-0000-000000000001"</span><span class="p">,</span>
<span class="s2">"serial"</span><span class="p">:</span> <span class="s2">"DEF7654321"</span>
<span class="s2">"nickname"</span><span class="p">:</span> <span class="s2">"Back door"</span><span class="p">,</span>
<span class="p">}</span>
<span class="p">]</span>
</code></pre>
<p><code class="prettyprint">GET /sesames</code></p>
<h3 id="response-fields">Response Fields</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td></td>
<td><b>array</b></td>
<td>Array of Sesames</td>
</tr>
<tr>
<td><code class="prettyprint">[i].device_id</code></td>
<td><b>UUID</b><br/></td>
<td>Sesame unique ID</td>
</tr>
<tr>
<td><code class="prettyprint">[i].serial</code></td>
<td><b>string</b><br/></td>
<td>Sesame serial</td>
</tr>
<tr>
<td><code class="prettyprint">[i].nickname</code></td>
<td><b>string</b><br/></td>
<td>Sesame nickname</td>
</tr>
</tbody></table>
<h2 id="get-sesame-status">Get Sesame status</h2>
<pre class="highlight shell tab-shell"><code>curl -H <span class="s2">"Authorization: YOUR_AUTH_TOKEN"</span> <span class="se">\</span>
https://api.candyhouse.co/public/sesame/00000000-0000-0000-0000-000000000001
</code></pre><pre class="highlight javascript tab-javascript"><code> <span class="p">{</span>
<span class="s2">"locked"</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="s2">"battery"</span><span class="p">:</span> <span class="mi">100</span><span class="p">,</span>
<span class="s2">"responsive"</span><span class="p">:</span> <span class="kc">true</span>
<span class="p">}</span>
</code></pre>
<p><code class="prettyprint">GET /sesame/{device_id}</code></p>
<h3 id="response-fields">Response Fields</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td><code class="prettyprint">locked</code></td>
<td><b>boolean</b><br/></td>
<td>Sesame is locked or not</td>
</tr>
<tr>
<td><code class="prettyprint">battery</code></td>
<td><b>integer</b></td>
<td>Sesame battery status</td>
</tr>
<tr>
<td><code class="prettyprint">responsive</code></td>
<td><b>boolean</b></td>
<td>Sesame is responsive now or not</td>
</tr>
</tbody></table>
<h2 id="control-sesame">Control Sesame</h2>
<pre class="highlight shell tab-shell"><code>curl -H <span class="s2">"Authorization: YOUR_AUTH_TOKEN"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-X POST -d <span class="s1">'{"command":"lock"}'</span> <span class="se">\</span>
https://api.candyhouse.co/public/sesame/00000000-0000-0000-0000-000000000001
</code></pre><pre class="highlight javascript tab-javascript"><code> <span class="p">{</span>
<span class="s2">"task_id"</span><span class="p">:</span> <span class="s2">"01234567-890a-bcde-f012-34567890abcd"</span>
<span class="p">}</span>
</code></pre>
<p><code class="prettyprint">POST /sesame/{device_id}</code></p>
<h3 id="post-body">Post Body</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td><code class="prettyprint">command</code></td>
<td><b>string</b><br/></td>
<td>(required) <code class="prettyprint">lock</code>, <code class="prettyprint">unlock</code> or <code class="prettyprint">sync</code>. <br/>Sync command will force the server to update Sesame status. <b>NOTE:</b> Frequent use of the sync command will reduce Sesame’s battery life.</td>
</tr>
</tbody></table>
<h3 id="response-fields">Response Fields</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td><code class="prettyprint">task_id</code></td>
<td><b>string</b><br/></td>
<td>Task ID which can be used to query execution result.</td>
</tr>
</tbody></table>
<h2 id="query-execution-result">Query Execution Result</h2>
<pre class="highlight shell tab-shell"><code>curl -H <span class="s2">"Authorization: YOUR_AUTH_TOKEN"</span> <span class="se">\</span>
https://api.candyhouse.co/public/action-result?task_id<span class="o">=</span>01234567-890a-bcde-f012-34567890abcd
</code></pre><pre class="highlight javascript tab-javascript"><code> <span class="p">{</span>
<span class="s2">"status"</span><span class="p">:</span> <span class="s2">"terminated"</span><span class="p">,</span>
<span class="s2">"successful"</span><span class="p">:</span> <span class="kc">true</span>
<span class="p">}</span>
</code></pre>
<p><code class="prettyprint">GET /action-result?task_id={task_id}</code></p>
<h3 id="query-parameters">Query Parameters</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td><code class="prettyprint">task_id</code></td>
<td><b>string</b><br/></td>
<td>(required) Task ID from command result.</td>
</tr>
</tbody></table>
<h3 id="response-fields">Response Fields</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td><code class="prettyprint">status</code></td>
<td><b>string</b><br/></td>
<td>Can be “processing” or “terminated”.</td>
</tr>
<tr>
<td><code class="prettyprint">successful</code></td>
<td><b>boolean</b><br/></td>
<td>This parameter only appears when the status is terminated. Indicates whether the execution was successful or not.</td>
</tr>
<tr>
<td><code class="prettyprint">error</code></td>
<td><b>string</b><br/></td>
<td>Indicates the reason execution failed.</td>
</tr>
</tbody></table>
<h1 id="errors">Errors</h1>
<p>All errors contain an error attribute indicating the error details.</p>
<h3 id="400-bad-request">400 Bad Request</h3>
<pre class="highlight javascript tab-javascript"><code><span class="p">{</span>
<span class="s2">"error"</span><span class="p">:</span> <span class="s2">"BAD_PARAMS"</span>
<span class="p">}</span>
</code></pre><pre class="highlight javascript tab-javascript"><code><span class="p">{</span>
<span class="s2">"error"</span><span class="p">:</span> <span class="s2">"DEVICE_IS_BUSY 35"</span>
<span class="p">}</span>
</code></pre>
<ul>
<li><code class="prettyprint">BAD_PARAMS</code> Your request paremeters are invalid</li>
<li><code class="prettyprint">CLOUD_INTEGRATION_NOT_ENABLED</code> Please enable cloud integration in Sesame app under Sesame > Change Settings.</li>
<li><code class="prettyprint">LOW_BATTERY</code> Your device cannot be operated because its batteries are low.</li>
<li><code class="prettyprint">DEVICE_IS_BUSY</code> Your device cannot be operated because it is occupied by other requests.</li>
<li><code class="prettyprint">DEVICE_IS_BUSY :seconds</code> Your device cannot be operated because the device is occupied by other requests. The <code class="prettyprint">:seconds</code> is an integer indicating the max duration you have to wait until you can send the next request.</li>
</ul>
<h3 id="401-unauthorized">401 Unauthorized</h3>
<ul>
<li><code class="prettyprint">UNAUTHORIZED</code> Your API key is missing or invalid.</li>
</ul>
<h3 id="403-forbidden">403 Forbidden</h3>
<ul>
<li><code class="prettyprint">Forbidden</code> OR <code class="prettyprint">ACCESS_DENY</code> You IP address has been blocked due to repeatedly exceeding our rate limits by a significant amount. The exact rate limit is subject to change as it is automatically determined by an algorithm, but request rates at 1 request per second (or lower) will not be restricted. If you receive this error, please cease requests for 30 minutes before trying again. If the error persists, please email us at [email protected] for assistance and provide your IP address.</li>
</ul>
<h3 id="429-throttled">429 Throttled</h3>
<ul>
<li><code class="prettyprint">THROTTLED</code> Your request rate has exceeded the limit. The request rate limit is based on both user account and IP address. Each API endpoint has an absolute rate limit. Please email us at [email protected] if you have any questions or requests for an exception.</li>
</ul>
<h3 id="500-internal-error">500 Internal Error</h3>
<ul>
<li><code class="prettyprint">INTERNAL_ERROR</code> Server cannot handle your request. These errors tend to be temporary; if it persists, please email [email protected] to let us know.</li>
</ul>
<h1 id="sesame-webhook">Sesame Webhook</h1>
<p>You can set up a webhook URL at the <a href="https://my.candyhouse.co">CANDY HOUSE Dashboard</a> by accessing your API Settings.</p>
<h2 id="method">Method</h2>
<ul>
<li>The webhook now supports GET and POST methods.</li>
</ul>
<h2 id="url">URL</h2>
<ul>
<li>The webhook URL is limited to 256 characters.</li>
<li>The webook URL supports variables; for example, when using <code class="prettyprint">http://example.com/device={device_id}</code>, <code class="prettyprint">{device_id}</code> will be replaced by the device UUID.</li>
<li>Variables Reference</li>
<li>* <code class="prettyprint">{device_id}</code>: Device UUID</li>
<li>* <code class="prettyprint">state</code>: <code class="prettyprint">locked</code> or <code class="prettyprint">unlocked</code></li>
</ul>
<h2 id="trigger">Trigger</h2>
<ul>
<li>The webhook will be triggered when Sesame’s lock status has changed.</li>
<li>The webhook will not retry if the HTTP request fails.</li>
</ul>
<h1 id="third-party-libraries-plugins">Third-Party Libraries & Plugins</h1>
<p>We love seeing what awesome things Sesame users are doing with our cloud API!</p>
<p>Have something to share? <a href="mailto:[email protected]">Email us</a> and we’ll be happy to add it to the list!</p>
<h2 id="libraries-using-v3-api">Libraries using V3 API</h2>
<h3 id="pysesame2"><a href="https://github.com/yagami-cerberus/pysesame2">Pysesame2</a></h3>
<p>by Anonymous</p>
<h3 id="sesame-net"><a href="https://github.com/veleek/sesame-net">Sesame.NET</a></h3>
<p>by <a href="http://www.veleek.com">Ben Randall</a></p>
<p>“A .NET client for the Sesame API.”</p>
<h3 id="homebridge-sesame"><a href="https://www.npmjs.com/package/homebridge-sesame">Homebridge-Sesame</a></h3>
<p>by <a href="https://www.npmjs.com/~aschaper">Andrew Schaper</a></p>
<p>“Homebridge plugin for the Sesame smart lock.”</p>
<h3 id="sesame-smartthings-integration"><a href="https://github.com/tobycth3/Sesame">Sesame/SmartThings Integration</a></h3>
<p>by <a href="https://github.com/tobycth3">tobycth3</a></p>
<p>“Integration between Sesame API and SmartThings.”</p>
<h3 id="gsuitescript-for-sesame-api"><a href="https://github.com/CANDY-HOUSE/GSuiteScript_SesameAPI">GSuiteScript for Sesame API</a></h3>
<p>by <a href="https://github.com/Jerming">Jerming Gu</a></p>
<p>“Integrate Google Apps with Sesame and lock/unlock Sesame from Google Sheets.”</p>
<h3 id="home-assistant-sesame"><a href="https://home-assistant.io/components/lock.sesame/">Home Assistant Sesame</a></h3>
<p>by <a href="https://home-assistant.io">Home Assistant</a></p>
<p>“The sesame platform allows you to control your Sesame smart locks made by CANDY HOUSE, Inc.”</p>
<h2 id="libraries-using-v1-v2-api">Libraries using V1 & V2 API</h2>
<h3 id="pysesame"><a href="https://github.com/trisk/pysesame">Pysesame</a></h3>
<p>by <a href="https://github.com/trisk">Albert Lee</a></p>
<p>“Python API for controlling Sesame smart locks made by CANDY HOUSE, Inc.”</p>
<h3 id="qsesame"><a href="http://quacktacular.net/crumbs/qsesame/">QSesame</a></h3>
<p>by <a href="http://quacktacular.net">Brendan</a></p>
<p>“QSesame is a <a href="https://github.com/nfarina/homebridge">Homebridge plugin</a> that allows you to control Sesame smart locks with Siri by integrating with HomeKit.”</p>
<h3 id="sesame-ruby"><a href="https://rubygems.org/gems/sesame-ruby">Sesame Ruby</a></h3>
<p>by <a href="https://github.com/mbklein">Michael B. Klein</a></p>
<p>“This gem provides a simple Ruby wrapper around the CANDY HOUSE Sesame API to control Sesame Bluetooth and Internet-connected locks.” <a href="https://github.com/mbklein/sesame-ruby">(source)</a></p>
<h1 id="tutorial-1-api-postman">Tutorial 1: API (Postman)</h1>
<h2 id="introduction">Introduction</h2>
<p>In this tutorial, you will learn how to get status updates for your Sesame, lock and unlock your Sesame, sync status, and check the results of your API commands. You will do so by making GET and POST requests to Sesame’s RESTful API using the free <a href="https://www.getpostman.com/">Postman app</a>.</p>
<p>To complete this tutorial, you must have the following:</p>
<ol>
<li><a href="https://candyhouse.co/products/sesame">Sesame smart lock</a></li>
<li><a href="https://candyhouse.co/products/wi-fi-access-point">Wi-Fi Access Point</a></li>
<li>Computer with internet access</li>
</ol>
<h2 id="before-you-start">Before You Start</h2>
<ol>
<li><p>You must be the owner of Sesame to enable the API.</p></li>
<li><p>You must have a Wi-Fi Access Point properly set up and paired with your Sesame (<a href="https://candyhouse.co/blogs/sesame/how-to-setup-your-wi-fi-access-point">instructions here</a>).</p></li>
<li><p>Make sure to enable cloud integration for your Sesame under Status > Change Settings > Integration.
<img src="images/CloudIntegration.png" alt="Cloud Integrations" /></p></li>
<li><p>Keep the Sesame app closed while using the API; if it’s open it will prevent the API from connecting to your Sesame. Only one device can connect to Sesame at a time.</p></li>
</ol>
<h2 id="obtain-your-api-key">Obtain Your API Key</h2>
<ol>
<li><p>Login to your CANDY HOUSE Account on the <a href="https://my.candyhouse.co">CANDY HOUSE Dashboard</a> with your email and password or Google account.
<img src="images/01_Login_to_Dashboard.png" alt="CANDY HOUSE Dashboard" /></p></li>
<li><p>Click on <strong>API Settings</strong> in the sidebar. To access your API Settings, you will need to enter a verification code. Click <strong>SEND CODE</strong> and your verification code will be sent to the email address you used to login. Enter the code and then click <strong>CONFIRM</strong>.
<img src="images/02_API_Settings.png" alt="API Settings" />
<img src="images/03_Verification.png" alt="API Verification" /></p></li>
<li><p>Once you’ve entered the verification code, you will be able to access your API settings. Click <strong>ADD</strong> to add a new API Key. Please note that the full key will no longer be visible once you refresh or logout, so be sure to save a copy somewhere. You can also delete existing keys and create additional keys as needed.
<img src="images/04_Add_API_Key.png" alt="Add API Key" />
<img src="images/05_API_Key.png" alt="API Key" /></p></li>
</ol>
<h2 id="get-postman">Get Postman</h2>
<ol>
<li><p>Download the free <a href="https://www.getpostman.com/">Postman app</a> and create an account. Make sure you’ve downloaded the latest version.
<img src="images/05_Get_Postman-01.png" alt="Get Postman" /></p></li>
<li><p>Create an account if you haven’t already, then login to the app. We recommend unchecking “Show this window on launch.” Close the launch screen to begin.
<img src="images/06_Launch_Postman-01.png" alt="Postman Launch Screen" /></p></li>
</ol>
<h2 id="save-your-api-key-as-a-preset">Save Your API Key as a Preset</h2>
<ol>
<li><p>Save your API key as a preset so you won’t need to keep copy/pasting it in the header over and over for each of the following steps. On your emply tab, do the following:</p>
<ol>
<li>Select the <strong>Headers</strong> tab</li>
<li>Click <strong>Presets</strong></li>
<li>Click <strong>Manage Presets</strong></li>
<li>Click <strong>Add</strong></li>
</ol>
<p><img src="images/07_Manage_Presets-01.png" alt="Manage Presets" />
<img src="images/08_Add_Preset-01.png" alt="Add Preset" /></p></li>
<li><p>Enter the following information:</p>
<ol>
<li>Give your Preset a name, such as: <strong>Sesame Token</strong></li>
<li>Enter the name of your key: <strong>Authorization</strong></li>
<li>Copy and paste the <strong>API key</strong> from the CANDY HOUSE Dashboard.</li>
<li>When you’re done, click <strong>Add</strong>.</li>
<li>Click the <strong>X</strong> in the upper right corner once you’re done.</li>
</ol>
<p><img src="images/09_Paste_Token-01.png" alt="Paste Token" />
<img src="images/11_Exit_Presets-01.png" alt="Exit Presets" /></p></li>
<li><p>The next time you want to use your authorization token, go to <strong>Header</strong>, click <strong>Preset</strong>, and select <strong>Sesame Token</strong> to automatically input the token. The token must be included for each of the following requests. Do so now as you will need it for the next step.
<img src="images/12_Select_Preset-01.png" alt="Add Sesame Token" /></p></li>
</ol>
<h2 id="request-sesame-list">Request Sesame List</h2>
<ol>
<li><p>Next, we will check if the token is correct by requesting a list of Sesames for which you are the owner. Please note that you will only be able to use the API for Sesames for which you are the owner. In your current tab, enter the following information:</p>
<ol>
<li>Leave <strong>GET</strong> as <strong>GET</strong></li>
<li>Enter the request URL: <code class="prettyprint">https://api.candyhouse.co/public/sesames</code></li>
</ol>
<p><img src="images/13_Get_Sesames-01.png" alt="Request Sesame List" /></p></li>
<li><p>Once you’ve confirmed all of the above is correct, click the blue <strong>Send</strong> button. If your request is successful, the API will return status 200 plus a list of Sesames owned by your CANDY HOUSE account, as well as the following information for each Sesame:</p>
<ol>
<li>Device ID</li>
<li>Serial</li>
<li>Nickname</li>
</ol>
<p><img src="images/14_Copy_Sesame_ID-01.png" alt="Sesame List" /></p></li>
<li><p>Copy the <strong>Device ID</strong> for the following steps, then click on the plus sign next to your current tab to open a new tab.</p></li>
</ol>
<h2 id="request-sesame-status">Request Sesame Status</h2>
<ol>
<li><p>Next, we will request the status for a Sesame in your list using its device ID. On your new tab, enter the following information:</p>
<ol>
<li>Leave <strong>GET</strong> as <strong>GET</strong></li>
<li>For the request URL, enter the following but change <code class="prettyprint">*DEVICE_ID*</code> to the actual ID of a Sesame you own: <code class="prettyprint">https://api.candyhouse.co/public/sesame/*DEVICE_ID*</code></li>
<li>Select the <strong>Headers</strong> tab</li>
<li>Add your <strong>Sesame Token</strong> preset</li>
</ol>
<p><img src="images/15_Get_Sesame_Status-01.png" alt="Request Sesame Status" /></p></li>
<li><p>Once you’ve confirmed everything is correct, click the blue <strong>Send</strong> button. If your request is successful, the API will return status 200 plus the following information for your Sesame:</p>
<ol>
<li>Locked (true = locked, false = unlocked)</li>
<li>Battery percentage</li>
<li>Responsive (true = responsive, false = unresponsive)</li>
</ol>
<p><img src="images/16_Sesame_Status_Results-01.png" alt="Sesame Status" /></p></li>
</ol>
<h2 id="lock-sesame">Lock Sesame</h2>
<ol>
<li><p>Next, we will pass a command to lock Sesame. Duplicate the “Get Sesame Status” tab by clicking the three circles next to the plus sign, then click <strong>Duplicate Current Tab</strong>.
<img src="images/28_Duplicate_Tab-01.png" alt="Duplicate Current Tab" /></p></li>
<li><p>On your duplicated tab, do the following:</p>
<ol>
<li>Change <strong>GET</strong> to <strong>POST</strong></li>
<li>Select the <strong>Body</strong> tab</li>
<li>Select <strong>raw</strong></li>
<li>Select <strong>JSON (application/json)</strong></li>
<li>In the text field, type the following: <code class="prettyprint">{"command":"lock"}</code></li>
</ol>
<p><img src="images/17_Lock_Sesame-01.png" alt="Lock Sesame" /></p></li>
<li><p>Make sure the information in both the Headers and Body sections are correct, then click the blue <strong>Send</strong> button. If your request is successful, the API will return status 200 plus the task ID. Copy the <strong>Task ID</strong> for the next step.
<img src="images/18_Get_Task_ID-01.png" alt="Lock Sesame Task ID" /></p></li>
</ol>
<h2 id="query-task-result">Query Task Result</h2>
<ol>
<li>Next, we will check whether the command was successfully carried out by Sesame. Receiving the task ID merely indicates that our servers successfully received the request, but it doesn’t necessarily mean that Sesame was actually locked. Querying the status will let you know if the commane was successfully executed, and if not, the reason for failure. To begin, open a new tab, then enter the following information:
<ol>
<li>Leave <strong>GET</strong> as <strong>GET</strong></li>
<li>For the request URL, enter the following but change <code class="prettyprint">*TASK_ID</code> to the actual task ID for your lock Sesame command: <code class="prettyprint">https://api.candyhouse.co/public/action-result?task_id=*TASK_ID*</code></li>
<li>Select the <strong>Headers</strong> tab</li>
<li>Add your <strong>Sesame Token</strong> preset</li>
</ol></li>
</ol>
<p><img src="images/19_Query_Task_Result-01.png" alt="Query Task Result" /></p>
<ol>
<li>Make sure the information in both the Headers and Body section is correct, then click the blue <strong>Send</strong> button. If your request is successful, the API will return the status of your task. If the status is terminated, the API will also return whether the command was successful, and if not, why it failed.
<img src="images/10_Task_Status-01.png" alt="Task Status" /></li>
</ol>
<h2 id="unlock-sesame">Unlock Sesame</h2>
<ol>
<li><p>Now it’s time to unlock Sesame. Find the tab you used to lock Sesame, then duplicate the tab by clicking the three cirlces and <strong>Duplicate Current Tab</strong>. Next, do the following:</p>
<ol>
<li>Select the <strong>Body</strong> tab</li>
<li>In the text field, change the content to the following: <code class="prettyprint">{"command":"unlock"}</code></li>
</ol>
<p><img src="images/20_Unlock_Sesame-01.png" alt="Change to Lock" /></p></li>
<li><p>Click the blue <strong>Send</strong> button. If the request is successful, the API will return status 200 and the task ID. You can copy this task ID and query its status if you’d like.</p></li>
</ol>
<h2 id="sync-sesame-status">Sync Sesame Status</h2>
<ol>
<li><p>In addition to the lock and unlock commands, you can also use the sync command to force the server to update Sesame status. To do so, duplicate your unlock Sesame tab by clicking the three cirlces and <strong>Duplicate Current Tab</strong>. Next, do the following:</p>
<ol>
<li>Select the <strong>Body</strong> tab</li>
<li>In the text field, change the content to the following: <code class="prettyprint">{"command":"sync"}</code></li>
</ol>
<p><img src="images/21_Sync_Sesame-01.png" alt="Sync" /></p></li>
<li><p>Click the blue <strong>Send</strong> button. If the request is successful, the API will return status 200 and the task ID. You can copy this task ID and query its status if you’d like.</p></li>
</ol>
<h2 id="saving-your-requests">Saving Your Requests</h2>
<ol>
<li><p>If you haven’t already, be sure to save each of your requests by clicking the <strong>Save</strong> button and giving the request a name that describes its function.
<img src="images/23_Save_Request-01.png" alt="Name Request" /></p></li>
<li><p>You will also need to create a collection in which to save all your requests. Click <strong>Create Collection</strong>, give your collection a name, then click the checkmark.
<img src="images/24_Name_Request_and_Collection-01.png" alt="Name Collection" /></p></li>
<li><p>Once you’ve done so, select your collection and click <strong>Save</strong>.
<img src="images/25_Select_Collection_and_Save-01.png" alt="Save Request" /></p></li>
<li><p>After you save your first request in a collection, the collection sidebar will open. Click the <strong>X</strong> on the upper right to close this sidebar. Once you’ve done so, you can continue saving your other requests.
<img src="images/26_Close_Collection-01.png" alt="Close Collection" /></p></li>
<li><p>The next time you’d like to send a request, you can either click on the existing tab or find your request in your Sesame collection. Click the <strong>Send</strong> button to make the request.
<img src="images/27_Access_Saved_Request-01.png" alt="Access Saved Requests" /></p></li>
</ol>
<h2 id="support">Support</h2>
<p>We hope you found our tutorial helpful! If you have any feedback or questions for us, please feel free to email <a href="mailto:[email protected]">[email protected]</a> and we’ll be happy to answer your questions! You can also check out <a href="https://community.candyhouse.co">the CANDY HOUSE forum</a> for API-related discussions - just sign in with your CANDY HOUSE account email and password. </p>
<h1 id="tutorial-2-api-webhook-ifttt">Tutorial 2: API & Webhook (IFTTT)</h1>
<h2 id="introduction">Introduction</h2>
<p>In this tutorial, you will learn how to turn Sesame being locked or unlocked into an IFTTT trigger (“If This”) as well as lock or unlock Sesame as an IFTTT action (“Then That”). You will use both the Sesame RESTful API as well as the Sesame Webhook as well as the <a href="https://ifttt.com">IFTTT</a> platform.</p>
<p>To complete this tutorial, you must have the following:</p>
<ol>
<li><a href="https://candyhouse.co/products/sesame">Sesame smart lock</a></li>
<li><a href="https://candyhouse.co/products/wi-fi-access-point">Wi-Fi Access Point</a></li>
<li>Computer or mobile device with internet access</li>
</ol>
<h2 id="before-you-start">Before You Start</h2>
<ol>
<li><p>You must be the owner of Sesame to enable the API.</p></li>
<li><p>You must have a Wi-Fi Access Point properly set up and paired with your Sesame (<a href="https://candyhouse.co/blogs/sesame/how-to-setup-your-wi-fi-access-point">instructions here</a>).</p></li>
<li><p>Make sure to enable cloud integration for your Sesame under Status > Change Settings > Integration.
<img src="images/CloudIntegration.png" alt="Cloud Integrations" /></p></li>
<li><p>Keep the Sesame app closed while using the API; if it’s open it will prevent the API from connecting to your Sesame. Only one device can connect to Sesame at a time.</p></li>
<li><p>You will need to create an account at <a href="https://ifttt.com">IFTTT</a> in order to create IFTTT applets.</p></li>
</ol>
<h2 id="obtain-your-api-key-and-device-id">Obtain Your API Key and Device ID</h2>
<ol>
<li><p>Login to your CANDY HOUSE Account on the <a href="https://my.candyhouse.co">CANDY HOUSE Dashboard</a> with your email and password or Google account.
<img src="images/01_Login_to_Dashboard.png" alt="CANDY HOUSE Dashboard" /></p></li>
<li><p>Click on <strong>API Settings</strong> in the sidebar. To access your API Settings, you will need to enter a verification code. Click <strong>SEND CODE</strong> and your verification code will be sent to the email address you used to login. Enter the code and then click <strong>CONFIRM</strong>.
<img src="images/02_API_Settings.png" alt="API Settings" />
<img src="images/03_Verification.png" alt="API Verification" /></p></li>
<li><p>Once you’ve entered the verification code, you will be able to access your API Settings. Click <strong>ADD</strong> to add a new API Key. Please note that the full key will no longer be visible once you refresh or logout, so be sure to save a copy somewhere. You can also delete existing keys and create additional keys as needed.
<img src="images/04_Add_API_Key.png" alt="Add API Key" />
<img src="images/05_API_Key.png" alt="API Key" /></p></li>
<li><p>To obtain your Device ID, click on <strong>Sesame List</strong> in the sidebar, then click on your Sesame. The device ID will be in the URL. Select the alphanumerical string after the last slash in the URL; you will use this as the device ID later, so keep the tab open or copy it to a safe place.
<img src="images/06_Sesame_List.png" alt="Sesame List" />
<img src="images/07_Device_ID.png" alt="Device ID in URL" /></p></li>
</ol>
<h2 id="lock-or-unlock-sesame-as-an-ifttt-action">Lock or Unlock Sesame as an IFTTT Action</h2>
<ol>
<li><p>First, make sure you go to the <a href="https://ifttt.com/maker_webhooks">Webhook</a> service and click <strong>CONNECT</strong> to add this service to your IFTTT account.</p></li>
<li><p>Next, go to your IFTTT account and click on the <a href="https://ifttt.com/create">New Applet</a> button.
<img src="images/08_Add_New_Applet.png" alt="New Applet" /></p></li>
<li><p>Click on <strong>+this</strong> and select the trigger you would like to use. For our example, we chose the Button Widget and selected “Button press” as our trigger.
<img src="images/09_Add_This.png" alt="Add This" />
<img src="images/10_Button.png" alt="Button" /></p></li>
<li><p>Click on <strong>+that</strong> and search for the <strong>Webhooks</strong> widget. Select “Make a web request”.
<img src="images/11_Add_That.png" alt="Add That" />
<img src="images/12_Webhooks.png" alt="Webhooks" />
<img src="images/13_Make_Request.png" alt="Make Request" /></p></li>
<li><p>Enter the following information to create your action:</p>
<ol>
<li>In the URL field, enter: <code class="prettyprint">https://api.candyhouse.co/public/partners/ifttt</code></li>
<li>For the Method field, select <strong>POST</strong>.</li>
<li>For Content Type, select <strong>application/json</strong>.</li>
<li>In the Body section, enter: <code class="prettyprint">{"command": "*COMMAND*", "apikey": "*API_KEY*", "device_id": "*DEVICE_ID*"}</code>. Be sure to replace <code class="prettyprint">*COMMAND*</code> with either <strong>lock</strong> or <strong>unlock</strong> depending on whether you want the applet to lock or unlock. Be sure to also replace <code class="prettyprint">*API_KEY*</code> with your actual API key, and replace <code class="prettyprint">*DEVICE_ID*</code> with your actual device ID.</li>
</ol>
<p><img src="images/14_URL_Method.png" alt="URL and Method" />
<img src="images/16_Body_Example.png" alt="Body Example" /></p></li>
<li><p>Once finished, click <strong>Create Action</strong>, edit the name of the applet if you’d like, then click <strong>Finish</strong> and your new Sesame applet is good to go!
<img src="images/17_Name_Applet.png" alt="Name Applet" /></p></li>
</ol>
<h2 id="trigger-actions-when-sesame-is-locked-or-unlocked">Trigger Actions when Sesame is Locked or Unlocked</h2>
<ol>
<li><p>First, go to the <a href="https://ifttt.com/maker_webhooks">Webhook</a> service on IFTTT and make sure it is connected to your account (if not, click on <strong>CONNECT</strong> to do so). Click on <strong>Documentation</strong> to obtain your IFTTT Maker Key.
<img src="images/18_Webhook_Documentation.png" alt="Webhook Documentation" />
<img src="images/19_Maker_Key.png" alt="Maker Key" /></p></li>
<li><p>In the Event field, type <code class="prettyprint">{device_id}_{state}</code>, then copy the URL at the bottom of the page.
<img src="images/20_Copy_Event_URL.png" alt="Copy_Event_URL" /></p></li>
<li><p>Next, go to the <a href="https://my.candyhouse.co">CANDY HOUSE Dashboard</a> and click on <strong>API Settings</strong>. Create a webhook by clicking on the <strong>EDIT</strong> button, then paste the copied URL in the URL field. It will be <code class="prettyprint">https://maker.ifttt.com/trigger/{device_id}_{state}/with/key/*MAKER_KEY*</code> with <code class="prettyprint">*MAKER_KEY*</code> replaced with your own actual key. Your webhook will then be Enabled.
<img src="images/21_Edit_Webhook.png" alt="Edit Webhook" />
<img src="images/22_Paste_URL.png" alt="Paste URL" />
<img src="images/23_Webhook_Enabled.png" alt="Webhook Enabled" /></p></li>
<li><p>Next, return to your IFTTT account and click on the <a href="https://ifttt.com/create">New Applet</a> button.
<img src="images/24a_Add_New_Applet.png" alt="New Applet" /></p></li>
<li><p>Click on <strong>+that</strong> and search for the <strong>Webhooks</strong> widget. Select “Receive a web request”.
<img src="images/24_New_Applet.png" alt="New Applet" />
<img src="images/25_Webhook.png" alt="Webhook" />
<img src="images/26_Receive_Request.png" alt="Receive_Request" /></p></li>
<li><p>In the Event Name field, enter <code class="prettyprint">*DEVICE_ID*_*STATE*</code>, but replace <code class="prettyprint">*DEVICE_ID*</code> with your actual device ID, and replace <code class="prettyprint">*STATE*</code> with either <strong>lock</strong> or <strong>unlock</strong> depending on which state you would like to trigger the applet. The end result will be something like “12345678-ABCD-1234-EFGHIJKLMNOP_lock” or “12345678-ABCD-1234-EFGHIJKLMNOP_unlock”. Click <strong>Create Trigger</strong> to proceed.
<img src="images/28_Event_Example.png" alt="Event" /></p></li>
<li><p>Next, click <strong>+that</strong> and select the action you would like to happen. In our example, we chose “Send an email.” You can also edit the content of the email or your own trigger using <code class="prettyprint">MakerEventName</code> or <code class="prettyprint">OccurredAt</code>. Values 1, 2, 3 are not used.
<img src="images/30_Email_Default.png" alt="Email Default" />
<img src="images/31_Email_Example.png" alt="Email Example" /></p></li>
<li><p>Click <strong>Create Applet</strong>, then rename your applet and click <strong>Finish</strong>. Now your action will trigger when Sesame is locked or unlocked, depending on which state you chose to enter in the Event Name field.
<img src="images/32_Name_and_Finish.png" alt="Name and Finish" /></p></li>
</ol>
<h2 id="support">Support</h2>
<p>We hope you found our tutorial helpful! If you have any feedback or questions for us, please feel free to email <a href="mailto:[email protected]">[email protected]</a> and we’ll be happy to answer your questions! You can also check out <a href="https://community.candyhouse.co">the CANDY HOUSE forum</a> for API-related discussions - just sign in with your CANDY HOUSE account email and password. </p>
</div>
<div class="dark-box">
<div class="lang-selector">
<a href="#" data-language-name="shell">shell</a>
</div>
</div>
</div>
</body>
</html>