Difference between revisions of "Bot Playground/Built-in Functions/http.post"
(Updated with new requestOptions object.) |
|||
| Line 4: | Line 4: | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
const queryData = { f: "123" }; | const queryData = { f: "123" }; | ||
| + | const requestOptions = { headers: { "x-my-header": "example" } }; | ||
| − | http.post(url, queryData, "json") | + | http.post(url, queryData, "json", requestOptions) |
.then(function(response) { | .then(function(response) { | ||
... | ... | ||
| Line 11: | Line 12: | ||
// or with await: | // or with await: | ||
| − | const response = await http.post(url, queryData, "json"); | + | const response = await http.post(url, queryData, "json", requestOptions); |
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 26: | Line 27: | ||
{{API Variable Group|Input}} | {{API Variable Group|Input}} | ||
{{API Variable|url|yes}} the URL to retrieve | {{API Variable|url|yes}} the URL to retrieve | ||
| − | {{API Variable|queryData|no}} (object) the optional POST parameters | + | {{API Variable|queryData|no}} (object) the optional POST parameters |
{{API Variable|contentType|no}} (string) the optional content type (see below) | {{API Variable|contentType|no}} (string) the optional content type (see below) | ||
| − | + | {{API Variable|requestOptions|no}} (object) the optional request options (see below) | |
{{API Variable Group|Output}} | {{API Variable Group|Output}} | ||
| Line 62: | Line 63: | ||
http.post(url, queryData, "json") | http.post(url, queryData, "json") | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| + | |||
| + | === Available Request Options === | ||
| + | The requestOptions object allows you to specify additional http options. Available options are: | ||
| + | * '''headers''' - Key/value pairs to add to the request headers (Example: {"x-my-header": "example"}) | ||
=== Example === | === Example === | ||
Revision as of 21:17, 18 August 2025
Retrieves data from a HTTP source using the POST method.
const queryData = { f: "123" };
const requestOptions = { headers: { "x-my-header": "example" } };
http.post(url, queryData, "json", requestOptions)
.then(function(response) {
...
});
// or with await:
const response = await http.post(url, queryData, "json", requestOptions);
or with await:
var response = await http.post(url, query);
Reference
This command accepts the following parameters:
| Variable | Required | Description
| |
|---|---|---|---|
| Input: | |||
| url | yes | the URL to retrieve | |
| queryData | optional | (object) the optional POST parameters | |
| contentType | optional | (string) the optional content type (see below) | |
| requestOptions | optional | (object) the optional request options (see below) | |
| Output: | |||
| Function returns a Promise with the following data: | |||
| success | bool | true if command completed successfully | |
| error | string | error string if command has failed | |
| statusCode | (on success) The HTTP status code | ||
| headers | (on success) The array with HTTP headers | ||
| body | (on success) The string body of the reply | ||
Comments
This function makes an HTTP POST request to the specified URL. The query parameters may be added to the URL as a query object ({ param1: 1, param2: 2 }).
You can use https://ptsv2.com to test your POST requests.
Limitations
The length of the response body is limited to 4096 bytes.
Content type
By default the request is being sent as an old plain POST. This is the string composed of key=value pairs (also known as "application/x-www-form-urlencoded").
http.post(url, queryString);
// or, the same
http.post(url, queryString, "form");
You can change the request to send JSON by specifying "json" as contentType argument (this way is also known as "application/json"):
http.post(url, queryData, "json")
Available Request Options
The requestOptions object allows you to specify additional http options. Available options are:
- headers - Key/value pairs to add to the request headers (Example: {"x-my-header": "example"})
Example
A simple POST request using await:
console.log("Doing http request...");
var response = await http.post("https://ptsv2.com/t/h6rf5-1631886515/post", { param1: 1, param2: 2})
console.log("http result:", response.body);
// Gracefully stop the test script
exit();
A bit more complex example which provides the error handling (uses Promises but can be rewritten to use await):
console.log("Doing http request...");
http.post("https://ptsv2.com/t/h6rf5-1631886515/post", { param1: 1, param2: 2})
.then(function(result) {
if(!result.success) {
// On error display the error message and stop the processing
console.log("HTTP error:", result.error);
throw "";
}
console.log("http result:", result.body);
})
.catch(function(err) {
// This block allows cancelling the processing chain with throw ""
if(err != "") { throw err; }
})
.then(function() {
// Gracefully stop the test script
exit();
});
