2019-11-09 18:39:13 +01:00
HTTP Request
============
.. seo ::
:description: Instructions for setting up HTTP Requests in ESPHome
2021-11-16 03:19:33 +01:00
:image: connection.svg
2019-11-09 18:39:13 +01:00
:keywords: http, request
2024-06-10 02:36:21 +02:00
The `` http_request `` component lets you make HTTP/HTTPS requests. To do so, you need to add it to your device's configuration:
2019-11-09 18:39:13 +01:00
.. code-block :: yaml
# Example configuration entry
http_request:
2024-06-10 02:36:21 +02:00
.. _http_request-configuration_variables:
2019-11-09 18:39:13 +01:00
Configuration variables:
------------------------
- **id** (*Optional* , :ref: `config-id` ): Manually specify the ID used for code generation.
2022-01-25 09:53:56 +01:00
- **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 `` .
2024-07-23 03:51:37 +02:00
- **timeout** (*Optional* , :ref: `config-time` ): Timeout for request. Defaults to `` 4.5s `` .
2024-06-10 02:36:21 +02:00
- **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* , :ref: `config-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** .
2024-07-24 05:51:01 +02:00
**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 `` .
2024-06-10 02:36:21 +02:00
**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 to `` false `` . By setting this option to `` true `` :
- 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.
2024-06-13 06:06:06 +02:00
2024-06-10 02:36:21 +02:00
To maximize security, do not set `` verify_ssl `` to `` false `` *unless:*
2024-06-13 06:06:06 +02:00
2024-06-10 02:36:21 +02:00
- 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.**
2021-09-19 19:44:54 +02:00
2019-11-09 18:39:13 +01:00
HTTP Request Actions
--------------------
2024-06-10 02:36:21 +02:00
The `` http_request `` component supports a number of :ref: `actions <config-action>` that can be used to send requests.
2019-11-09 18:39:13 +01:00
.. _http_request-get_action:
`` http_request.get `` Action
***** ***** ***** ***** ***** **
This :ref: `action <config-action>` sends a GET request.
.. code-block :: yaml
on_...:
- http_request.get:
url: https://esphome.io
headers:
Content-Type: application/json
2021-03-22 04:26:19 +01:00
on_response:
then:
- logger.log:
2023-01-10 05:40:48 +01:00
format: 'Response status: %d, Duration: %u ms'
2021-03-22 04:26:19 +01:00
args:
2024-07-14 22:52:49 +02:00
- response->status_code
- response->duration_ms
2019-11-09 18:39:13 +01:00
# Short form
- http_request.get: https://esphome.io
2024-06-10 02:36:21 +02:00
**Configuration variables:**
2019-11-09 18:39:13 +01:00
2024-06-10 02:36:21 +02:00
- **url** (**Required** , string, :ref: `templatable <config-templatable>` ): URL to which to send the request.
2019-11-09 18:39:13 +01:00
- **headers** (*Optional* , mapping): Map of HTTP headers. Values are :ref: `templatable <config-templatable>` .
2024-06-10 02:36:21 +02:00
- **capture_response** (*Optional* , boolean): when set to `` true `` , the response data will be captured and placed into
the `` body `` variable as a `` std::string `` for use in :ref: `lambdas <config-lambda>` . Defaults to `` false `` .
- **max_response_buffer_size** (*Optional* , integer): The maximum buffer size to be used to store the response.
Defaults to `` 1 kB `` .
- **on_response** (*Optional* , :ref: `Automation <automation>` ): An automation to perform after the request is received.
2024-10-30 02:11:01 +01:00
- **on_error** (*Optional* , :ref: `Automation <automation>` ): An automation to perform if the request cannot be completed.
2019-11-09 18:39:13 +01:00
.. _http_request-post_action:
`` http_request.post `` Action
***** ***** ***** ***** ***** ***
This :ref: `action <config-action>` sends a POST request.
.. code-block :: yaml
on_...:
- http_request.post:
url: https://esphome.io
headers:
Content-Type: application/json
json:
key: value
# Short form
- http_request.post: https://esphome.io
2024-06-10 02:36:21 +02:00
**Configuration variables:**
2019-11-09 18:39:13 +01:00
- **body** (*Optional* , string, :ref: `templatable <config-templatable>` ): A HTTP body string to send with request.
2024-06-10 02:36:21 +02:00
- **json** (*Optional* , mapping): A HTTP body in JSON format. Values are :ref: `templatable <config-templatable>` .
See :ref: `http_request-examples` .
2019-11-09 18:39:13 +01:00
- All other options from :ref: `http_request-get_action` .
.. _http_request-send_action:
`` http_request.send `` Action
***** ***** ***** ***** ***** ***
This :ref: `action <config-action>` sends a request.
.. code-block :: yaml
on_...:
- http_request.send:
method: PUT
url: https://esphome.io
headers:
Content-Type: application/json
body: "Some data"
2024-06-10 02:36:21 +02:00
**Configuration variables:**
2019-11-09 18:39:13 +01:00
- **method** (**Required** , string): HTTP method to use (`` GET `` , `` POST `` , `` PUT `` , `` DELETE `` , `` PATCH `` ).
2024-06-10 02:36:21 +02:00
- All other options from :ref: `http_request-post_action` and :ref: `http_request-get_action` .
2019-11-09 18:39:13 +01:00
2021-03-22 04:26:19 +01:00
.. _http_request-on_response:
`` on_response `` Trigger
-----------------------
2024-06-10 02:36:21 +02:00
This automation will be triggered when the HTTP request is complete.
The following variables are available for use in :ref: `lambdas <config-lambda>` :
2023-01-10 05:40:48 +01:00
2024-07-14 22:52:49 +02:00
- `` response `` as a pointer to `` HttpContainer `` object which contains `` content_length `` , `` status_code `` and `` duration_ms `` .
2024-06-10 02:36:21 +02:00
- `` body `` as `` std::string `` which contains the response body when `` capture_response ``
(see :ref: `http_request-get_action` ) is set to `` true `` .
2021-03-22 04:26:19 +01:00
2024-10-29 01:23:38 +01:00
.. note ::
The `` status_code `` should be checked before using the `` body `` variable. A successful response will usually have
a status code of `` 200 `` . Server errors such as "not found" (404) or "internal server error" (500) will have an appropriate status code, and may contain an error message in the `` body `` variable.
2021-03-22 04:26:19 +01:00
.. code-block :: yaml
on_...
then:
- http_request.get:
url: https://esphome.io
on_response:
then:
- logger.log:
2023-01-10 05:40:48 +01:00
format: "Response status: %d, Duration: %u ms"
2021-03-22 04:26:19 +01:00
args:
2024-07-14 22:52:49 +02:00
- response->status_code
- response->duration_ms
2024-07-17 12:35:29 +02:00
- lambda: |-
ESP_LOGD(TAG, "Response status: %d, Duration: %u ms", response->status_code, response->duration_ms);
2024-10-30 02:11:01 +01:00
on_error:
then:
- logger.log: "Request failed!"
.. _http_request-on_error:
`` on_error `` Trigger
-----------------------
This automation will be triggered when the HTTP request fails to complete. This may be e.g. when the network is not available,
or the server is not reachable. This will *not* be triggered if the request
completes, even if the response code is not 200. No information on the type of error is available and no variables
are available for use in :ref: `lambdas <config-lambda>` . See example usage above.
2021-03-22 04:26:19 +01:00
2019-11-09 18:39:13 +01:00
.. _http_request-examples:
Examples
--------
Templatable values
***** ***** ***** ***
.. code-block :: yaml
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;
2022-03-12 19:27:48 +01:00
POST Body in JSON format (syntax 1)
***** ***** ***** ***** ***** ***** *****
2019-11-09 18:39:13 +01:00
2024-06-10 02:36:21 +02:00
**Note:** all values of the map must be strings. It is not possible to send JSON `` boolean `` or `` numbers `` with this
syntax.
2019-11-09 18:39:13 +01:00
.. code-block :: yaml
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"}
2022-03-12 19:27:48 +01:00
POST Body in JSON format (syntax 2)
***** ***** ***** ***** ***** ***** *****
2019-11-09 18:39:13 +01:00
**Note:** use this syntax to send `` boolean `` or `` numbers `` in JSON.
The JSON message will be constructed using the `ArduinoJson <https://github.com/bblanchon/ArduinoJson> `__ library.
2024-06-10 02:36:21 +02:00
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.
2019-11-09 18:39:13 +01:00
.. code-block :: yaml
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"}
2022-03-12 19:27:48 +01:00
GET values from a JSON body response
***** ***** ***** ***** ***** ***** ***** *
2024-11-08 05:02:07 +01:00
If you want to retrieve the value for the vol key and assign it to a template sensor or number component whose id is
2024-11-07 00:40:12 +01:00
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:
2022-03-12 19:27:48 +01:00
2024-06-10 02:36:21 +02:00
This example assumes that the server returns a response as a JSON object similar to this:
2022-03-12 19:27:48 +01:00
`` {"status":"play","vol":"42","mute":"0"} ``
2024-06-10 02:36:21 +02:00
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 `` :
2022-03-12 19:27:48 +01:00
.. code-block :: yaml
on_...:
- http_request.get:
url: https://esphome.io
2024-06-10 02:36:21 +02:00
capture_response: true
2022-03-12 19:27:48 +01:00
on_response:
then:
2024-10-29 01:23:38 +01:00
- if:
condition:
lambda: return response->status_code == 200;
then:
- lambda: |-
json::parse_json(body, [](JsonObject root) -> bool {
2024-12-28 23:08:13 +01:00
if (root["vol"]) {
id(player_volume).publish_state(root["vol"]);
return true;
}
else {
ESP_LOGI(TAG,"No 'vol' key in this json!");
return false;
}
2024-11-11 02:22:47 +01:00
});
2024-10-29 01:23:38 +01:00
else:
- logger.log:
format: "Error: Response status: %d, message %s"
2024-12-28 23:08:13 +01:00
args: [ 'response->status_code', 'body.c_str()' ]
2022-03-12 19:27:48 +01:00
2019-11-09 18:39:13 +01:00
See Also
--------
- :doc: `index`
- :apiref: `http_request/http_request.h`
2024-11-07 00:40:12 +01:00
- :doc: `/components/json`
2019-11-09 18:39:13 +01:00
- :ghedit: `Edit`