# 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"
    }
}
```


---

# 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.vntranslator.com/advanced/custom-mt/request-and-response.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.