> For the complete documentation index, see [llms.txt](https://docs.vntranslator.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vntranslator.com/advanced/custom-mt/request-and-response.md).

# Request & Response

This is a configuration section of [Custom MT](/advanced/custom-mt.md). This section contains the core configuration for Machine Translation requests.

## Variables

* `$ID`
* `$SOURCE_TEXT` or `$ORIGINAL_TEXT`
* `$TRANSLATED_TEXT`
* `$SOURCE_LANG`
* `$TARGET_LANG`

Schema variables can be used in the configuration with the syntax `$SCHEMA_NAME`.

For example:

```json
{
    "schema": [
        { "type": "string", "name": "api_key", "title": "API Key", "default": "", "required": true, "message": "Required an API Key" },
    ],
    "request": {
        "method": "http_post",
        "url": "http://127.0.01/?key=$API_KEY"
        "options": {
            "headers": {
              "Authorization": "Bearer $API_KEY",
              "Content-Type": "application/json"
            }
        }        
    }
}
```

***

## Parameters

#### **method**: `string`

* "web\_scraping"
* "http\_get"
* "http\_post"
* "web\_llm"

#### **initialUrl**: `string` <mark style="color:$warning;">(optional)</mark>

The initial URL to visit before making the actual request (for web scraping).

#### **ur**l: `string`

The endpoint URL for the Machine Translation service.&#x20;

#### **encodeURI**: `boolean` <mark style="color:$warning;">(optional)</mark>

Escapes characters using UTF-8 code units, with each octet encoded in the format `%XX`, left-padded with 0 if necessary. Lone surrogates in UTF-16 do not encode any valid Unicode character.\
Reference: [encodeURI](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)

#### **encodeURIComponent:** `boolean` <mark style="color:$warning;">(optional)</mark>

Uses the same encoding algorithm as `encodeURI`.\
Escapes all characters except: `A–Z a–z 0–9 - _ . ! ~ * ' ( )`\
Reference: [encodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)

#### **encodeURIExtra:** `string` <mark style="color:$warning;">(optional)</mark>

Additional function to replace URI using a regular expression. For example: `["%2F", "g", "\\%2F"]`

#### userAgent: `string` <mark style="color:$warning;">(optional)</mark>

Custom User-Agent string for the HTTP request.

#### **querySelector:** `string`

Returns the first element within the HTML document that matches the specified selector or group of selectors.\
Reference: [querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)

#### **querySelectorAll:** `string` <mark style="color:$warning;">(optional)</mark>

Returns a static NodeList representing a list of HTML elements that match the specified group of selectors.\
Reference: [querySelectorAll](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll)

#### **queryProperty:** `string`

Specifies which property to extract from the selected HTML element:

* "value" - property of the HTMLDataElement [\[Reference\]](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDataElement/value)
* "innerText" - property of the HTMLElement [\[Reference\]](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)
* "textContent" **-** property of the Node [\[Reference\]](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
* "innerHTML" - property of the HTMLElement [\[Reference\]](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML)

#### **body:** `object`

The request body for POST requests. Can contain variables like `$SOURCE_TEXT`, `$SOURCE_LANG`, and `$TARGET_LANG`.

#### **options:** `object` <mark style="color:$warning;">(optional)</mark>

Additional request options.

* **headers** - Set custom request headers:
  * X-Custom-Header: `string`
  * Authorization: `string`
  * Content-Type: `string`

#### responseType: `string`

* "string" - set response type as string
* "json" - set response type as json

#### **responseQuery:** `string`

***

### Parsing JSON Responses from HTTP Requests

JSON responses can be parsed using the `responseQuery` parameter.

The `responseQuery` parameter is only used for `http_get` and `http_post` methods when the response type is set to `json`.

To navigate through nested JSON objects, use dot notation (`.`) to separate field names. Array elements can be accessed using bracket notation with an index (e.g., `[0]`).

**Example JSON Response:**

```json
{
  "text": "Hello 1",
  "words": [
    { "text": "Hello 2" },
    { "text": "Hello 3" }
  ]
  "lines": {
    "text": "Hello 4",
    "sub": {
      "text": "Hello 5"
    }        
  }
}
```

| responseQuery  | Result  |
| -------------- | ------- |
| text           | Hello 1 |
| words\[0].text | Hello 2 |
| lines.sub.text | Hello 5 |

***

***

## Examples

### 1. Web Scraping Method

<div align="left"><figure><img src="/files/e4AD2suCWLblRybyoQCU" alt=""><figcaption></figcaption></figure></div>

#### Required Parameters

* **method**: `string` ("web\_scraping")
* **url**: `string`
* **querySelector**: `string`
* **queryProperty**: `string`

```json
{
    "request": {
        "method": "web_scraping",
        "encodeURI": false,
        "encodeURIComponent": true, 
        "initialUrl": "https://localhost:8080",
        "url": "https://localhost:8080/?sl=$SOURCE_LANG&tl=$TARGET_LANG&text=$SOURCE_TEXT",    
        "querySelector": "span[lang=$TARGET_LANG]",
        "queryProperty": "innerText"
    }
}
```

***

### 2. HTTP GET Method

<div align="left"><figure><img src="/files/8yuvb0oD5m0dzzIrsJ0W" alt=""><figcaption></figcaption></figure></div>

#### Required Parameters

* **method**: `string` ("http\_get")
* **url**: `string`
* **responseType**: `string`
* **responseQuery**: `string`

```json
{
    "request": {
        "method": "http_get",
        "encodeURI": false,
        "encodeURIComponent": false, 
        "url": "https://localhost:8080/translate?sl=$SOURCE_LANG&tl=$TARGET_LANG&text=$SOURCE_TEXT",
        "options": {},
        "responseType": "json",
        "responseQuery": "translate.result"
    }
}
```

***

### 3. HTTP POST Method

<div align="left"><figure><img src="/files/8yuvb0oD5m0dzzIrsJ0W" alt=""><figcaption></figcaption></figure></div>

#### Required Parameters

* **method**: `string` ("http\_post")
* **url**: `string`
* **body**: `object`
* **options**: `object`
  * **headers**: `object`
    * X-Custom-Header: string
    * Authorization: string
    * Content-Type: string
* **responseType**: `string`
* **responseQuery**: `string`

```json
{
    "request": {
        "method": "http_post",
        "encodeURI": false,
        "encodeURIComponent": false, 
        "url": "https://localhost:8080/translate",
        "body": {
            "text": "$SOURCE_TEXT",
            "source_lang": "$SOURCE_LANG",
            "target_lang": "$TARGET_LANG"
        }
        "options": {
            "headers": {
                "Authorization": "Bearer $API_KEY",
                "Content-Type": "application/json"
            }
        },
        "responseType": "json",
        "responseQuery": "translate.result"
    }
}
```