{urlsend}
Sample Usage
{note}Sends a message to acme.com/log_delivery with the widget count when this snippet is inserted{endnote}
{urlsend: https://example.com/log_delivery?widgets={=count}}
Settings
Setting Name Type Description General URL Settings _ url The URL to request. Fox example, https://example.com/page method GET/POST/... The HTTP method used to make the request. Defaults to GET. body text The body of the request. headers Key/Value List A list of headers. For example, Content-Type=text/json,Authorization=Basic 12345 completed function Function called when the request completes. The function takes the results of the request and returns a string. If the returned string is not blank (""), creates a browser notification with that message. retry keyed list Retry automatically if the request fails. General Command Settings trim yes/no/left/right If yes whitespace is removed before and after the command. If left, only whitespace to the left is removed. If right, only whitespace to the right is removed.
| Setting Name | Type | Description |
|---|---|---|
| General URL Settings | ||
| _ | url | The URL to request. Fox example, https://example.com/page |
| method | GET/POST/... | The HTTP method used to make the request. Defaults to GET. |
| body | text | The body of the request. |
| headers | Key/Value List | A list of headers. For example, Content-Type=text/json,Authorization=Basic 12345 |
| completed | function | Function called when the request completes. The function takes the results of the request and returns a string. If the returned string is not blank (""), creates a browser notification with that message. |
| retry | keyed list | Retry automatically if the request fails. |
| General Command Settings | ||
| trim | yes/no/left/right | If yes whitespace is removed before and after the command. If left, only whitespace to the left is removed. If right, only whitespace to the right is removed. |
The urlsend command allows you to send a message to a server when a snippet is inserted. This can be used for logging snippet usage, or even saving the variables that were used in a snippet.
The command's first positional setting is the URL you want to send data to.
You also have access to settings like method, body, and headers so you can specify the data you want to send.
Example usage
If you want to write data to Google Sheets, take a look at this example.
You can also develop your own server application to collect and store data from the urlsend command.
See also the {urlload} command for loading data from a server into your snippet.
Handling errors
If the request fails, a browser notification will be shown to the user. You can customize this message and when it is shown by using the completed setting. The completed setting takes a function with two parameters: the response text and response status code. When that function returns a non-blank string a message is shown with the string.
For instance, imagine we have an endpoint that returns JSON with a status property that is either "success" or "error". To show a message when the status is "error" we could use the following completed settings:
{urlsend: ...; completed=(res) -> "An error occurred, please try again" if fromJSON(res).status = "error" else ""}
Retrying requests
You can use the retry setting to automatically retry the request if it fails. It takes a keyed list with delays (a list of millisecond delays) and when (a list of conditions).
Supported condition types: connection (for network errors), status (for specific HTTP status codes), and text (if the response contains specific text).
For example, the following command will retry after 2 seconds, and then 4 seconds on a 500 status code, if the response contains the text "error", or if there is a connection error:
{urlsend: ...; retry=["delays": [2000, 4000], "when": [["type": "status", "code": 500], ["type": "text", "text": "error"], ["type": "connection"]]]}
Note: If the request is not idempotent, it is possible for duplicate actions to be caused due to retrying. For example, if the initial request was successfully received and acted on by the server, but the confirmation never made it back to Text Blaze.
Sharing connected snippets with others
When sharing snippets with others, snippets containing the urlsend command may only be shared with members of your Text Blaze Business organization.