Using The Web API

ThinkAutomation provides a public Web API that acts as a secure tunnel between web resources and your on-premises or self-hosted ThinkAutomation instance. When your ThinkAutomation Server starts, it makes a secure outbound connection to the ThinkAutomation Web API Gateway server. This allows your ThinkAutomation Server to receive public HTTP requests without being publicly accessible itself. Since your ThinkAutomation server makes an outbound connection to the Gateway server you do not need to open any incoming firewall ports and you do not need a static IP address.

The Web API is used for the following:

Type	Details
Web Form Message Sources	For creating publicly accessible web forms that connect to your Automations.
API Message Sources	For executing Automations via public HTTP GET or POST endpoints.
Teams Message Sources	For receiving messages from Microsoft Teams users.
Web Forms - Custom	For posting your own web forms directly to ThinkAutomation for processing.
Web Get Requests	For triggering Automations from simple HTTP Get requests and optionally returning the Automation Return value.
Twilio Actions	For making calls or sending/receiving SMS messages via Twilio.
Wait For User Response Action	For requesting additional information from users during Automation execution.
Web Message Store Viewer	For viewing the Message Store using a web browser via the public URL (the local URL will still work).
Web For Webhook Action	For integrating with 3rd party web API's that offer webhook callbacks.
Other web based integrations	For example posting messages to your ThinkAutomation instance via HTTP POSTS or GETS for your own or 3rd party webhooks.

The Web API Gateway server does not hold any of your settings, or keep copies of messages it has forwarded to your ThinkAutomation Server - it simply acts as a secure tunnel between your unique public URL's and your ThinkAutomation Server.

You can disable the Web API in your ThinkAutomation Server Settings. Your ThinkAutomation Server will then not make any connection to the Web API Server - however the operations above cannot then be used.

Posting Messages Via The Web API

Web Form Message Source

The Web Form Message Source Type enables you to create a publicly accessible web form with multiple input fields. The web form has a unique secure public URL hosted on the ThinkAutomation Web API. You can embed the web form inside your own website or send a link to the form in outgoing emails. When a web user completes the form, the results are sent to your ThinkAutomation Server for immediate processing. The Web Form can optionally display the Automation return value after the form is submitted. See: Message Source Types - Web Form

Your Existing Website Forms

The Web API can accept HTTP POST requests from your own web forms. Simply set the form action to the Web API URL shown on the Message Source properties.

Custom Webhooks

Messages can be also posted to ThinkAutomation via the Web API using HTTP GET or POST requests. Each of your configured Message Sources has a unique public endpoint URL. The URL contains a secure hash of your ThinkAutomation instance and Message Source Id. Any message posted to this endpoint will be passed to your ThinkAutomation server for immediate processing. Messages will be processed by the default Automation configured for the Message Source. If your ThinkAutomation server is not active when a message is posted then the message will be queued for up 48 hours.

The Web API enables you to send messages to ThinkAutomation from any location.

You send messages to ThinkAutomation using HTTP POST or GET requests to the public Message Source URL. HTTP POST & GET requests are sent in the same way as the local API - but with the public URL instead of the local URL.

The Web API accepts x-www-form-urlencoded, form-data, and raw post data formats as the local API.

Response

The Web API will respond with a HTTP 202 Accepted response status along with a Json response:

{
    "Success": true,
    "Cached": false,
    "ErrorMessage": "",
    "MessageResultDetail": null
}

Success will be true if the message was accepted, otherwise false and ErrorMessage will contain the reason.

Cached will be true if your ThinkAutomation Server was not active when the message was added. The Message will be cached for up to 48 hours and sent to your ThinkAutomation Server when it becomes active.

If you are not waiting for Automation results and your calling API requires a 200 response status instead of 202 you can add &responsestatus=200 or &responsestatus=201 querystring parameter to your GET or POST request.

Waiting For Automation Results

By default Web API POST and GET requests will respond with a 202 Accepted status as soon as the message has been queued (unless a &redirect parameter is specified). You can optionally wait for the Automation results by adding a &wait=true query string parameter to the URL. If the &wait=true parameter is used then the HTTP response will be sent back when the Automation has completed for the message (with a 200 OK status). The response will include the Automation Return Value in the MessageResultDetail.

Example response if &wait=true parameter is used:

{
    "Success": true,
    "Cached": false,
    "ErrorMessage": "",
    "MessageResultDetail": {
        "MessageStoreId": "5f9befaf6e1f4065a89a5d9e",
        "MessageSourceId": "5f9ab14c6e1f405c7cbf955c",
        "IncomingUid": "dff8ad81-7ec2-4cc6-a288-975f7134ff85",
        "AutomationId": "5f86c3076e1f402260ea4bec",
        "AutomationSuccess": true,
        "AutomationError": "",
        "AutomationReturnValue": "Hello World",
        "AutomationLog": null,
        "ExecutionTime": 23
    }
}

Returning The Automation Return Value Only

You can choose to return the Automation Return value only by adding &results=true query string parameter to the URL. If the &results=true parameter is used then only the Automation Return Value content (or an error message) will be returned instead of the full Json response (shown above), along with a 200 OK status. Depending on the content of the Automation Return value, the result will be served as plain text (text/plain), HTML (text/html) or Json (application/json). If the Return Value contains Markdown text it will be converted to HTML first. If the Return Value is already HTML it will be returned as HTML. If the Return Value is Json it will be returned as Json.

Depending on what your Automation is doing - the Web API POST or GET request may timeout before the Automation completes. The maximum wait time is 60 seconds. So for long running Automations (for example: if your Automation is uploading FTP files etc), then the &wait and &results parameters may not be applicable.

Returning Files

If the &results=true parameter is used and the Automation Return value is a single local file path (or a variable containing a file path) then the file content will be read and returned. You can return whole html pages, images, PDF files etc. The response Content-Type will be set according to the file extension.

Returning Files From The Embedded Files Store

If you are using the Embedded Files Store action to save files to the Embedded Files Store database, you can return file content directly from the Embedded File Store. Use the Embedded Files Store action with the Get Info operation. Assign the results of the Get Info operation to your Automation Return value. The ThinkAutomation Server will then read the file content directly from the database and return the content.

The Web API has a limit of 5mb for the content returned from an Automation.

Providing A Link To The Automation Results

If your Automation is long running, or you want to provide a static link to the Automation results that a user can access later, you can use the %Msg_ResultsUrl% variable. Your Automation could include this variable in an outgoing email. A user can click the link to view the Automation results at a later date. The %Msg_ResultsUrl% URL is unique for each processed message and contains a secure hash. The link will work for as long as the Message is stored in the Message Store.

Allowed Origins

By default the Web API accepts HTTP POST and GET requests from anywhere. To ensure requests can only be made from your own websites you can add one or more 'Allowed Origins'. For each Message Source you can specify a comma separated list of allowed URL's that can post to the Web API endpoint. If this entry is blank then the endpoint can be posted to from anywhere. Full URL's should be specified, eg: https://www.mysite.com - without any path or page name. Allowed Origins can be edited via the Properties tab of the Message Source.

Web API Usage Limitations

Each instance of ThinkAutomation includes free access to the Web API Gateway with daily limits of:

ThinkAutomation Edition	Web API Calls Per Day
Basic	500
Standard	1000
Professional	5000 *

* can be increased at additional cost if required or you can host your own instance (see below).

The daily usage count resets at midnight UTC.

Each message posted via the Web API is limited to 10mb in size.

Self Hosted Web API Gateway

The Professional Edition of ThinkAutomation allows you host you own instance of the API Gateway Server (for example: api.mycompany.com). This is a self-hosted instance of the ThinkAutomation Web API Gateway Server with no message limits. The Gateway Server can run on any Windows machine or cloud VM. Please contact us for more information. See: Configuring Self Hosted API Gateway Server.

---