> For the complete documentation index, see [llms.txt](https://docs-en.dydu.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-en.dydu.ai/developers/api-reference/search-field.md).

# Search field

The search field service suggests knowledge while the user is typing a question.

## Send a request

* **Address**: `https://<server>/servlet/chatHttp`, replacing `<server>` with the address of your platform.
* **Method**: `GET` or `POST`. The JSON request is sent in the `data` parameter, or in the request body.
* **Encoding**: parameter values must be base64 encoded, except `solutionUsed`. Response values are also base64 encoded.

The request is a JSON object that contains:

* `type`: the request type, "fieldboxproactive" to get suggestions while the user is typing;
* `parameters`: the search parameters (see below);
* `callback` (optional): the name of a JavaScript function, to receive the response in JSONP format.

## Parameters

| Parameter           | Required | Description                                                                                                                                                                                                                                                                                                |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `botId`             | Yes      | Bot identifier. It is displayed on the **Preferences > Api > API access** page.                                                                                                                                                                                                                            |
| `userInput`         | Yes      | Text typed by the user.                                                                                                                                                                                                                                                                                    |
| `language`          | Yes      | Search language, in English: "French", "English"…                                                                                                                                                                                                                                                          |
| `space`             | No       | Consultation space. To use no particular space, enter "Defaut" (default value).                                                                                                                                                                                                                            |
| `contextId`         | No       | Search identifier. The first response of the service contains it: send it back to group all the requests of the same search. When it is not used for 10 minutes, the search is archived and the identifier is no longer valid. If you send an invalid or expired identifier, the server creates a new one. |
| `maxAnswerNumber`   | No       | Maximum number of suggestions (5 by default).                                                                                                                                                                                                                                                              |
| `tags`              | No       | Topics to search in. See [Restrict the search to topics](#restrict-the-search-to-topics).                                                                                                                                                                                                                  |
| `alreadyCame`       | No       | `true` if the user has already come, `false` (default) otherwise.                                                                                                                                                                                                                                          |
| `clientId`          | No       | User identifier. Without this parameter, the search is anonymous. In the BMS, it is only displayed to administrators.                                                                                                                                                                                      |
| `userUrl`           | No       | URL of the page the search is made from.                                                                                                                                                                                                                                                                   |
| `browser`           | No       | User's browser.                                                                                                                                                                                                                                                                                            |
| `os`                | No       | User's operating system.                                                                                                                                                                                                                                                                                   |
| `qualificationMode` | No       | `true`: qualification (testing) mode. Published and validated knowledge can be used and searches are not counted in the analytics. `false` (default): only published knowledge can be used and searches are counted.                                                                                       |
| `solutionUsed`      | No       | Solution used: "FIELDBOX" for the search field. This value can be sent without encoding.                                                                                                                                                                                                                   |

### Restrict the search to topics

The `tags` parameter is a list. For each topic, enter:

* `path`: the path of the topic, base64 encoded;
* `useChildren`: `true` to include sub-topics, `false` otherwise.

```
"tags": [
  { "path": "cm9vdC90YWcxCg==", "useChildren": true }
]
```

## Example

Request, with base64 encoded values ("f0de8c15-af21-467f-8cec-1494ee85ec87", "English", "how", "Common"):

```
{
  "type": "fieldboxproactive",
  "parameters": {
    "solutionUsed": "FIELDBOX",
    "botId": "ZjBkZThjMTUtYWYyMS00NjdmLThjZWMtMTQ5NGVlODVlYzg3",
    "language": "RW5nbGlzaA==",
    "userInput": "aG93",
    "space": "Q29tbW9u"
  }
}
```

Response:

```
{
  "type": "fieldboxproactive",
  "values": {
    "botId": "ZjBkZThjMTUtYWYyMS00NjdmLThjZWMtMTQ5NGVlODVlYzg3",
    "sourceInput": "aG93",
    "contextId": "ZWQ1OTM3NWItN2MyYy00NDRmLTkzZDQtMzBhNjFiNGUyOGE5",
    "suggestions": []
  }
}
```

`suggestions` contains the list of suggested knowledge, base64 encoded.

{% hint style="info" %}
The "fieldboxtalk" request type directly returns the answers of the knowledge found. It accepts the same parameters, plus `maxAnswerThresHold` (10 by default) instead of `maxAnswerNumber`.
{% endhint %}
