# Start Session Bot

```sh
[POST] https://tap.gateway:port/StartRobot
```

## Request headers

Content-Type: multipart/form-data'

## Request body

All parameters for this request are passed via multipart form-data. The following keys are expected:

* **username -** the Windows username that will be used to create the session
* **password -** the Windows user password that will be used to create the session
* **token -** this is the token that is configured in the TGA (within appsettings.json); if this does not match with provided token, the response will feature a 403 Forbidden code.
* **botPath** - the absolute path to the target automation. This needs to be a solution file (.tap) 
* **ip** - the ip address of the session creation host. This is usually set to **127.0.0.1** or whatever the terminal services listener is configured to.
* **port -** the default value is **3389**, which is the default RDP protocol port. If terminal services are listening on a diferent port, this needs to be changed.
* **domain** - the domain name, if the server is part of one. Otherwise, this value can be left empty.
* **colorDepth -** default value is **32**, representing the color depth for the Windows session.
* **desktopHeight -** the height in pixels for the resolution of the Windows session.
* **desktopWidth -** the width in pixels for the resolution of the Windows session.<br>

Besides the mandatory parameters required above, you can specify an unlimited number of additional parameters which will be passed to the bot runtime once triggered.

* data1=some\_value
* data2=some\_other\_value
* file1='@C:\file1.pdf'
* file2='@C:\file2.txt'
* ...

## Returns

The TGA should reply with a code **200** and aditional runtime information as JSON:

```json
{
	"response": {
		"message": "Robot C:\\Tailent\\Test\\Test.tap started",
		"messageType": 6,
		"metadata": ["7876"]
	},
	"guid": "2777f2d5-dbf1-41a0-ad1a-b2c9b9388baf",
	"accessTokenSet": true,
	"accessToken": "AiUAOWUjyvZSRkabP9208JguJ4NUYXktMAteQVZZDoHfRJ4FTk46CrYuBZmiK1fWkVCn39BGYItxtHoYBTKlfO8bLE8avBENhOaQ9kIk6MuEgpA3HnlT5PKRhAwCQM4U"
}
```

This response features important information that can be used in other REST requests.&#x20;

The first section **"response"** offers information about what automation was started:

* **message** is the response from the TGA component
* **messageType** signals the outcome of the requested operation (6 is the code for successful remote start)
* **metadata** is an array with additional information regarding to the request; by default this contains the **PID** of the TAP.Runtime process (automation)

**guid** - is the unique identifier assigned at runtime to the bot instance and can be used to uniquely identify this bot.

**accessTokenSet** - can be true/false depending on wether the OTP (or access token generated was set correctly).

**accessToken** - is a OTP (one time password) generated only once for this particular bot instance. This can used (along with the **guid**) to interogate on the status or updates of this particular bot instance. Please note that this access token is not saved and cannot be regenerated if lost.

## Example curl request

```sh
curl --request POST \
  --url https://tap.gateway:port/StartRobot \
  --header 'Content-Type: multipart/form-data' \
  --form username=TestUser \
  --form 'password=Password' \
  --form token=12345678 \
  --form 'botPath=C:\Tailent\Test\Test.tap' \
  --form ip=127.0.0.1 \
  --form port=3389 \
  --form domain= \
  --form colorDepth=32 \
  --form desktopHeight=768 \
  --form desktopWidth=1024 \
  --form data1=some_value \
  --form data2=some_other_value \
  --form 'file1=@C:\file1.pdf'
  --form 'file2=@C:\file2.txt'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tailent.com/getting-started/tailent-gateway-agent/tap-gateway-agent-api-references/start-session-bot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.