The Amazon Echo API

 

I love my Amazon Echo! But what else can I do with it?

First of all, I’m not a web developer, so go easy on me, but also help me out by being constructive. I’m an Automation Engineer, that is, I design electrical and control systems for manufacturing machines and then program the PLCs, and I write C# interfaces to the machines. I also did some embedded work and some website programming a long time ago, but anything after 2000 is new to me. But I guess that just makes it more exciting!

echo app

When I use the web-based control app at echo.amazon.com I can use Google Chrome to watch the network activity. Here’s a list of URLs that my browser hits with responses, with identifying stuff filtered out with “xxx”. I have a cookie set with a session ID, which is probably being used to get my user-specific information.

https://pitangui.amazon.com/api/check-client-version?version=v1.2-174-gcadbe83

(no response)

https://pitangui.amazon.com/api/devices/device

{"devices":[{"accountName":"xxx's Echo","deviceAccountId":"xxx","deviceOwnerCustomerId":"xxx","deviceType":"AB72C64C86AW2","online":true,"postalCode":null,"registrationId":null,"serialNumber":"xxx","softwareVersion":"2100"}]}

https://pitangui.amazon.com/api/todos?type=TASK&size=1

{"values":[{"complete":false,"createdDate":1418360739053,"customerId":"xxx","deleted":false,"itemId":"A94B0T49AALEW#3de6b833-3f38-3290-b98d-8f6c6d582246","lastLocalUpdatedDate":null,"lastUpdatedDate":1418360739053,"nbestItems":["roast beef","beef","roast groceries","groceries","brush beef"],"originalAudioId":"AB72C64C86AW2:1.0/2014/12/12/05/B0F00712447601DB/05:34::TNIH_2V.f34eec6a-82b3-4841-b68d-f3336830b454ZXV/1","text":"roast beef","type":"TASK","version":1}]}

[I was trying to say “brush teeth” :)]

https://pitangui.amazon.com/api/cards?limit=3

{"cards":[{"cardType":"StandardCard","creationTimestamp":1418424998722,"deleteCardAction":{"actionType":"DeleteCardAction","cardId":"A94B0T49AALEW#1418424998722","mainText":"Remove card","subText":"Learn more","subTextRoute":"help/node/201602230"},"descriptiveText":null,"giveFeedbackAction":{"actionType":"NavigateAction","mainText":"Thank you! Your feedback helps Echo understand you better.","musicCustomerId":null,"route":"beta-feedback","serviceName":null,"subText":"Send more detailed feedback.","subTextRoute":null},"id":"A94B0T49AALEW#1418424998722","imageAction":{"actionType":"PlayItAgainAction","mainText":"Radio Disney","queueCustomerId":"A94B0T49AALEW","queueId":"1f1ce0db-a300-4d1c-abf4-9b019caf6882","subText":null,"subTextRoute":null},"imageCaption":null,"imageReference":{"deviceSerialNumber":"B0F00712447601DB","deviceType":"AB72C64C86AW2","fallbackIcon":"TUNE_IN","referenceId":"1f1ce0db-a300-4d1c-abf4-9b019caf6882:1","referenceType":"MusicReferenceIdImageReference"},"nBestOptions":[],"playbackAudioAction":{"actionType":"PlayAudioAction","mainText":"Echo heard: \"i heart radio\"","subText":null,"subTextRoute":null,"url":"/api/utterance/audio/data?id=AB72C64C86AW2:1.0/2014/12/12/22/B0F00712447601DB/56:35::TNIH_2V.44b8e078-8eda-4c7f-ac8a-cc94684347deZXV/1"},"primaryActions":[{"actionType":"NavigateAction","mainText":"Browse your TuneIn stations","musicCustomerId":null,"route":"music/TUNE_IN","serviceName":null,"subText":null,"subTextRoute":null}],"registeredCustomerId":"A94B0T49AALEW","secondaryActions":null,"sourceDevice":{"serialNumber":"B0F00712447601DB","type":"AB72C64C86AW2"},"subtitle":"Live station on TuneIn","thumbsUpDownActivityAction":{"actionType":"ThumbsUpDownActivityAction","activityId":"A94B0T49AALEW#1418424998722","mainText":"Did Echo hear you correctly?","subText":null,"subTextRoute":null},"title":"Radio Disney","wrapTitle":false}]}

https://pitangui.amazon.com/api/media/provider-capabilities

{"providerCapabilities":{"ADVERTISEMENT":{"canCreateStation":false,"canJump":false,"canNext":false,"canNextAtEndOfQueue":false,"canPlay":true,"canPrevious":false,"canRepeatAll":false,"canScanContent":false,"canShuffle":false,"canThumbsDown":false,"canThumbsUp":false,"queueModifiedInPlace":false}
...and so on

https://pitangui.amazon.com/api/bluetooth

{"bluetoothStates":[{"deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","online":true,"sconeBattery":85,"sconePaired":true,"softwareVersion":"2100","streamingState":null}]}

https://pitangui.amazon.com/api/customer-status/

{"eulaAcceptance":true,"hasActiveDopplers":true}

https://pitangui.amazon.com/api/authentication

{"authenticated":true,"canAccessPrimeMusicContent":false,"customerEmail":"xxx","customerId":"xxx","customerName":"Owen Piette"}

https://pitangui.amazon.com/api/album-art/1f1ce0db-a300-4d1c-abf4-9b019caf6882:1?deviceSerialNumber=xxx&deviceType=AB72C64C86AW2&screenWidth=1920

https://pitangui.amazon.com/api/music-account-details

That’s it. Later I’ll see if I can match these API queries against the JavaScript so I can make a more complete list of the API. I’m starting to get the idea…

https://pitangui.amazon.com/api/notifications

{"notifications":[{"alarmTime":1418513400000,"deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","id":"xxx-B0F00712447601DB-a1","notificationIndex":"a1","remainingTime":0,"status":"OFF","triggerTime":0,"type":"Alarm","version":"26"},{"alarmTime":0,"deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","id":"xxx-B0F00712447601DB-t1","notificationIndex":"t1","remainingTime":0,"status":"OFF","triggerTime":0,"type":"Timer","version":"28"}]}

https://pitangui.amazon.com/api/third-party

{"services":[{"associationState":"UNASSOCIATED","serviceName":"I_HEART_RADIO","username":null},{"associationState":"UNASSOCIATED","serviceName":"TUNE_IN","username":null}]}

https://pitangui.amazon.com/api/device-preferences

{"devicePreferences":[{"autocastToThisClient":false,"deviceAccountId":"xxx","deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","postalCode":"52201","responseStyle":"CONCISE","searchCustomerId":"xxx","temperatureScale":"FAHRENHEIT","voiceCastEnabled":true}]}

And so on!

Here’s one that I guessed:¬†https://pitangui.amazon.com/api/wake-word

{"wakeWords":[{"deviceSerialNumber":"xxx","deviceType":"AB72C64C86AW2","wakeWord":"ALEXA"}]}

I want to modify that value! I guess tomorrow.

-Owen

8 thoughts on “The Amazon Echo API

  1. Hi Owen,

    Today I started Wireshark to try and sniff some interesting Amazon Echo traffic. Surprisingly it was not until today that I found your blog! I have been searching around for others trying to “hack” the Echo. A couple hours later I did some “integration” with my Hue lights and also with my phone. Thanks! Check the video here https://www.youtube.com/watch?v=r58ERvxT0qM

  2. Pingback: Home Automation With The Amazon Echo | Hackaday

  3. Pingback: Home Automation With The Amazon Echo | Ad Pub

  4. This is pretty exciting. I have an UBI too, which is worse than worthless. Although, it does connect to SmartThings and IFTTT.
    Echo is amazing, if it connects to anything it will be the steal of the century.

  5. Have you tried modifying the wake word? Any luck? Also, how did you/how are you going modify the value?

  6. @Chris Until Amazon opens up the wake word to other options we’ll have to stick with what we have. I tried changing the value in the PUT req but unfortunately their API rejects it.

  7. Looks like forum registration is currently disabled.. Dug through the JS a bit and wanted to share a few findings:

    – The microphone array can apparently determine where the Echo is located based on acoustics… very cool: KEY_DISTANCE_BETWEEN_DEVICE_AND_WALL, KEY_IS_DEVICE_IN_CORNER
    – Internal phrasing is interesting: doppler = wifi setup mode, scone = remote (turns out it is bluetooth), earcon = before / after request audio cues
    – References for collections of devices within the household.. purely speculation but Amazon may have Sonos in the crosshairs.

  8. Pingback: Amazon Artwork Api | Smiling Experts

Comments are closed.