Difference between revisions of "Bot Playground/Built-in Functions/http.post"

From SmartBots Developers Docs
Jump to: navigation, search
m (typo)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
 
<onlyinclude>Retrieves data from a HTTP source using the POST method.</onlyinclude>
 
<onlyinclude>Retrieves data from a HTTP source using the POST method.</onlyinclude>
−
Not implemented yet, see [[Bot Playground/Built-in Functions/http.get|http.get]]
+
 
 +
<syntaxhighlight lang="javascript">
 +
await http.post(url, queryData, "json", requestOptions);
 +
</syntaxhighlight>
 +
 
 +
 
 +
{{API Command Table}}
 +
{{API Required Vars|login}}
 +
 
 +
{{API Variable Group|Input}}
 +
{{API Variable|url|yes}} the URL to retrieve
 +
{{API Variable|queryData|no}} (object) the optional POST parameters
 +
{{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 Return promise}}
 +
{{API Variable|statusCode}} (on success) The HTTP status code
 +
{{API Variable|headers}} (on success) The array with HTTP headers
 +
{{API Variable|body}} (on success) The string body of the reply
 +
{{API Variables Table End}}
 +
 
 +
== Comments ==
 +
 
 +
This function makes an HTTP POST request to the specified URL. The request body may be added to the URL as a '''queryData''' parameter:
 +
 
 +
<syntaxhighlight lang="javascript">
 +
var response = await http.post("https://ptsv2.com/t/h6rf5-1631886515/post", {
 +
  param1: 1,
 +
  param2: 2
 +
});
 +
</syntaxhighlight>
 +
 
 +
You can use https://ptsv2.com to test your POST requests.
 +
 
 +
=== Content type ===
 +
 
 +
By default the request is being sent as an old plain POST (also known as "application/x-www-form-urlencoded"). This is the string composed of key=value pairs.
 +
 
 +
<syntaxhighlight lang="javascript">
 +
http.post(url, queryString);
 +
// or, the same
 +
http.post(url, queryString, "form");
 +
</syntaxhighlight>
 +
 
 +
You can change the request to send JSON by specifying "json" as contentType argument (this way is also known as "application/json"):
 +
 
 +
<syntaxhighlight lang="javascript">
 +
http.post(url, queryData, "json")
 +
</syntaxhighlight>
 +
 
 +
=== Request HTTP headers ===
 +
 
 +
HTTP headers can be set using a ''requestOptions'' object. Headers are the only available option for now:
 +
 
 +
<syntaxhighlight lang="javascript">
 +
var response = await http.post("https://ptsv2.com/t/h6rf5-1631886515/post", { param1: 1, param2: 2}, "json", {
 +
  "headers": {
 +
    "x-my-header-1": "value-1",
 +
    ...
 +
  }
 +
});
 +
</syntaxhighlight>
 +
 
 +
=== Limitations ===
 +
 
 +
The length of the response body is limited to 4096 bytes.
 +
 
 +
 
 +
== Examples ==
 +
 
 +
A simple POST request using await:
 +
 
 +
<syntaxhighlight lang="javascript">
 +
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();
 +
</syntaxhighlight>
 +
 
 +
A bit more complex example which provides the error handling (uses Promises but can be rewritten to use [[Bot_Playground/Async_and_await|await]]):
 +
 
 +
<syntaxhighlight lang="javascript">
 +
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();
 +
});
 +
</syntaxhighlight>
 +
 
 +
{{NavMenu}}
 +
__NOTOC__

Latest revision as of 11:39, 29 September 2025

Retrieves data from a HTTP source using the POST method. 

await http.post(url, queryData, "json", requestOptions);


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 request body may be added to the URL as a queryData parameter: 

var response = await http.post("https://ptsv2.com/t/h6rf5-1631886515/post", {
  param1: 1,
  param2: 2
});

You can use https://ptsv2.com to test your POST requests.

Content type

By default the request is being sent as an old plain POST (also known as "application/x-www-form-urlencoded"). This is the string composed of key=value pairs. 

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")

Request HTTP headers

HTTP headers can be set using a requestOptions object. Headers are the only available option for now: 

var response = await http.post("https://ptsv2.com/t/h6rf5-1631886515/post", { param1: 1, param2: 2}, "json", {
  "headers": {
     "x-my-header-1": "value-1",
     ...
  }
});

Limitations

The length of the response body is limited to 4096 bytes.


Examples

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();
	});
Retrieved from "https://www.mysmartbots.com/dev/docs/index.php?title=Bot_Playground/Built-in_Functions/http.post&oldid=2482"