Setting up Shelly buttons with HA Docker

Had a few issues getting Shelly buttons working in a docker HA via the Shelly integration and native API for automatons. So thought I’d put up some notes as reference and for any other newbies that get stuck.

To get the buttons working in automatons etc I had to do the following:

  1. Add the button to Shelly App and update the firmware.
  2. Plug the button into a charger and connect to the local web-server (http://buttons_ip_address).
  3. Enable CoIoT under Internet & Security > Advanced - Developer Settings > Enable CoIoT (see Fig 1):
  4. Set CoIoT peer to:
    • my_HA_ip_address:5683
  5. Save the configuration and reboot the button: Settings > Device Reboot > Device Reboot.
  6. On the HA host open the port 5683
    • For me that was: sudo ufw allow 5683/udp
    • Possibly if your docker is locked down you may need to add permissions to the Docker configure to access that port as well.
  7. Added the button to HA (auto detected).
  8. Under developer tools go to Events and enter into the ‘Start Listening’ field and click ‘Start Listening’
  9. Press the button and you should get some JSON data similar to this:
        "event_type": "",
        "data": {
            "device_id": "6xxxxxxxxxxxxxxxxxxxxxxxx",
            "device": "shellybutton1-9xxxxxxxxxx",
            "channel": 1,
            "click_type": "single",
            "generation": 1
        "origin": "LOCAL",
        "time_fired": "2022-01-01T08:59:11.764987+00:00",
        "context": {
            "id": "axxxxxxxxxxxxxxxxxxxxxxxxx",
            "parent_id": null,
            "user_id": null
    • Copy the device_id
    • And note the click_type which should correspond to what you did, single, double, triple or long.
  10. Create a new automation:
  11. In Triggers
    • Set Trigger type to: Event
    • Set Event type to:
    • Add the following to Event data:
    device_id: 6xxxxxxxxxxxxxxxxxxxxxxxx
    click_type: single
  12. Then set up your conditions and actions and you should have a functioning automation linked to the shelly button event. You can then add different automatons for each type of click (single, double, triple, long).

Hopefully that helps.

Fig 1)


Thank you for the very nice explanation.
I was missing the open port 5683 but unfourtunately still not getting any events after that. :sleepy:
The different thing here is the fact that I’m trying this on a shelly 2.5 gen 1.
do you have any other suggestion?

Are you trying to use a shelly button? This is not related to the Shelly relays you are using, it’s only about the Shelly Wifi Buttons you can purchase.

I don’t understand your comment about Shelly 2.5, that should in no way be relevant. I have a number of Shelly 2.5, 1PM and 2L’s set up along with two Shelly Wifi buttons but the Relays have nothing to do with the Buttons function.

You can connect your relays to your house pushbuttons and then control different appliances other then controlling only the relays :stuck_out_tongue_winking_eye: so no, I’m not talking about Shelly button. I’m talking about the relays.

Yeah but that uses a completely different mechanism/api to the click approach described above for the buttons, so apart from the port above nothing will be useful.

Maybe look at the two binary_sensor.shellyswitch2.5_xxxxxx_channel_x entities that the Shelly integration provides, they maybe linked to the physical light switch but I don’t use them so not certain.