HTTP Request¶
The http_request
component lets you make HTTP/HTTPS requests. To do so, you need to add it to your device’s configuration:
# Example configuration entry
http_request:
Configuration variables:¶
id (Optional, ID): Manually specify the ID used for code generation.
follow_redirects (Optional, boolean): Enable following HTTP redirects. Defaults to
true
.redirect_limit (Optional, integer): Maximum amount of redirects to follow when enabled. Defaults to
3
.timeout (Optional, Time): Timeout for request. Defaults to
4.5s
.useragent (Optional, string): User-Agent header for requests. Defaults to
ESPHome/<version> (https://esphome.io)
where<version>
is the version of ESPHome the device is running. For example:ESPHome/2024.6.0 (https://esphome.io)
verify_ssl (Optional, boolean): When set to
true
(default), SSL/TLS certificates will be validated upon connection; if invalid, the connection will be aborted. To accomplish this, ESP-IDF’s default ESP x509 certificate bundle is included in the build. This certificate bundle includes the complete list of root certificates from Mozilla’s NSS root certificate store. May only be set to true when using the ESP-IDF framework; must be explicitly set to false when using the Arduino framework.watchdog_timeout (Optional, Time): Change the watchdog timeout during connection/data transfer. May be useful on slow connections or connections with high latency. Do not change this value unless you are experiencing device reboots due to watchdog timeouts; doing so may prevent the device from rebooting due to a legitimate problem. Only available on ESP32 and RP2040.
For the ESP32 when using ESP-IDF:
buffer_size_rx (Optional, integer): Change HTTP receive buffer size. Defaults to
512
.buffer_size_tx (Optional, integer): Change HTTP transmit buffer size. Defaults to
512
.
For the ESP8266:
esp8266_disable_ssl_support (Optional, boolean): Determines whether to include HTTPS/SSL support in the firmware binary. Excluding the SSL libraries from your build will result in a smaller binary, which may be necessary for memory-constrained devices (512 kB or 1 MB). If you see
Error: ESP does not have enough space to store OTA file
in your device’s logs, you may need to enable this option. Defaults tofalse
. By setting this option totrue
:HTTPS connections will not be possible
verify_ssl: false
is implied
Warning
Setting verify_ssl
to false
reduces security when using HTTPS connections!
Without the root certificate bundle, certificates used by the remote HTTPS server cannot be verified, opening the HTTPS connection up to person-in-the-middle attacks.
To maximize security, do not set verify_ssl
to false
unless:
a custom CA/self-signed certificate is used,
the Arduino framework is used, or
the device does not have sufficient memory to store the certificate bundle
We strongly recommend using hardware which properly supports TLS/SSL.
HTTP Request Actions¶
The http_request
component supports a number of actions that can be used to send requests.
http_request.get
Action¶
This action sends a GET request.
on_...:
- http_request.get:
url: https://esphome.io
headers:
Content-Type: application/json
on_response:
then:
- logger.log:
format: 'Response status: %d, Duration: %u ms'
args:
- response->status_code
- response->duration_ms
# Short form
- http_request.get: https://esphome.io
Configuration variables:
url (Required, string, templatable): URL to which to send the request.
headers (Optional, mapping): Map of HTTP headers. Values are templatable.
capture_response (Optional, boolean): when set to
true
, the response data will be captured and placed into thebody
variable as astd::string
for use in lambdas. Defaults tofalse
.max_response_buffer_size (Optional, integer): The maximum buffer size to be used to store the response. Defaults to
1 kB
.on_response (Optional, Automation): An automation to perform after the request is received.
http_request.post
Action¶
This action sends a POST request.
on_...:
- http_request.post:
url: https://esphome.io
headers:
Content-Type: application/json
json:
key: value
# Short form
- http_request.post: https://esphome.io
Configuration variables:
body (Optional, string, templatable): A HTTP body string to send with request.
json (Optional, mapping): A HTTP body in JSON format. Values are templatable. See Examples.
All other options from http_request.get Action.
http_request.send
Action¶
This action sends a request.
on_...:
- http_request.send:
method: PUT
url: https://esphome.io
headers:
Content-Type: application/json
body: "Some data"
Configuration variables:
method (Required, string): HTTP method to use (
GET
,POST
,PUT
,DELETE
,PATCH
).All other options from http_request.post Action and http_request.get Action.
on_response
Trigger¶
This automation will be triggered when the HTTP request is complete. The following variables are available for use in lambdas:
response
as a pointer toHttpContainer
object which containscontent_length
,status_code
andduration_ms
.body
asstd::string
which contains the response body whencapture_response
(see http_request.get Action) is set totrue
.
on_...
then:
- http_request.get:
url: https://esphome.io
on_response:
then:
- logger.log:
format: "Response status: %d, Duration: %u ms"
args:
- response->status_code
- response->duration_ms
- lambda: |-
ESP_LOGD(TAG, "Response status: %d, Duration: %u ms", response->status_code, response->duration_ms);
Examples¶
Templatable values¶
on_...:
- http_request.post:
url: !lambda |-
return ((std::string) "https://esphome.io?state=" + id(my_sensor).state).c_str();
headers:
X-Custom-Header: !lambda |-
return ((std::string) "Value-" + id(my_sensor).state).c_str();
body: !lambda |-
return id(my_sensor).state;
POST Body in JSON format (syntax 1)¶
Note: all values of the map must be strings. It is not possible to send JSON boolean
or numbers
with this
syntax.
on_...:
- http_request.post:
url: https://esphome.io
json:
key: !lambda |-
return id(my_sensor).state;
greeting: "Hello World"
# Will send:
# {"key": "42.0", "greeting": "Hello World"}
POST Body in JSON format (syntax 2)¶
Note: use this syntax to send boolean
or numbers
in JSON.
The JSON message will be constructed using the ArduinoJson library.
In the json
option you have access to a root
object which represents the base object of the JSON message. You
can assign values to keys by using the root["KEY_NAME"] = VALUE;
syntax as shown below.
on_...:
- http_request.post:
url: https://esphome.io
json: |-
root["key"] = id(my_sensor).state;
root["greeting"] = "Hello World";
# Will send:
# {"key": 42.0, "greeting": "Hello World"}
GET values from a JSON body response¶
If you want to retrieve the value for the vol key and assign it to a template sensor or number component whose id is set to player_volume you can do this, but note that checking for the presence of the key will prevent difficult-to-read error messages:
This example assumes that the server returns a response as a JSON object similar to this:
{"status":"play","vol":"42","mute":"0"}
If you want to retrieve the value for the vol
key and assign it to a template sensor
or number
component
whose id
is set to player_volume
:
on_...:
- http_request.get:
url: https://esphome.io
capture_response: true
on_response:
then:
- lambda: |-
json::parse_json(body, [](JsonObject root) -> bool {
if (root["vol"]) {
id(player_volume).publish_state(root["vol"]);
return true;
}
else {
ESP_LOGD(TAG,"No 'vol' key in this json!");
return false;
}
});