> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/digital-agent/tools-reference/conversation-and-state.md).

# Conversation & state

The conversation itself: IDs, messages, intents, counters and history.

The conversation itself: IDs, messages, intents, counters and history. How to add a tool and use its result is described in [Tools & smart functions](https://docs.borndigital.ai/digital-agent/tools-reference.md).

| Tool                     | Technical name               | What it does                                                                                            | Languages |
| ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------- | --------- |
| Conversation in HTML     | `get_conversation_as_html`   | Returns structured summary of customers conversation so far as html string.                             | any       |
| Conversation Recording   | `get_conversation_recording` | Returns recording data of current conversation in WAV format.                                           | any       |
| Counter extractor        | `counter`                    | Extract the number of times a particular node has been visited in the conversation.                     | any       |
| Current conversation id  | `current_conversation_id`    | Extract the current conversation ID from the conversation context.                                      | any       |
| Last utterance extractor | `utterance`                  | Extract the raw text of the user’s last utterance from the conversation history                         | any       |
| Preprocessed utterance   | `preprocessed_utterance`     | Joins preprocessed tokens into a full user utterance.                                                   | any       |
| Previous conversations   | `previous_conversations`     | Return the count or list of previous conversations for a user based on filters and verbosity.           | any       |
| Selected intent          | `selected_intent`            | Extract details of the most recent ACTIONS-selected intent from conversation history                    | any       |
| Utterance score          | `get_utterance_score`        | Returns output of intent recognition in conversation history (candidates for intents with their score). | any       |
| Widget announcement      | `widget_announcement`        | Returns data for the `announcement` widget                                                              | any       |
| Winning intent           | `winning_intent`             | Check if a specified intent wins with a score above a threshold. Works only with training set intents   | any       |

## Conversation in HTML

Technical name: `get_conversation_as_html`

Returns structured summary of customers conversation so far as html string.

| Parameter              | Name                     | Required | Default | Description                                            |
| ---------------------- | ------------------------ | -------- | ------- | ------------------------------------------------------ |
| Deduplicate user input | `deduplicate_user_input` | no       | `True`  | If set to True, extractor will deduplicate user input. |

**Example input:** previous Goodbot - user interactions.

**Example output:**

```
<time datetime="2022-01-24T12:17:29.304750+01:00">22-01-24, 12:17:29</time>] <b>BOT</b>: Dobrý den. Jak vám mohu pomoci?<br>[<time datetime="2022-01-24T12:17:33.965884+01:00">22-01-24, 12:17:33</time>] <b>USER</b>: neco vymyslime<br>
```

## Conversation Recording

Technical name: `get_conversation_recording`

Returns recording data of current conversation in WAV format.

* Can also be used in expressions as `get_conversation_recording()`.

**Example input:** current conversation

**Example output:**

```
recording data of current conversation in WAV format
```

## Counter extractor

Technical name: `counter`

Extract the number of times a particular node has been visited in the conversation.

* Not shown in the tool list until you type its name – start typing `counter`.
* Advanced – usually set up together with Born Digital.

| Parameter            | Name      | Required | Default             | Description                                                                                    |
| -------------------- | --------- | -------- | ------------------- | ---------------------------------------------------------------------------------------------- |
| Storage              | `storage` | no       | `fallback_counters` | Name of the variable to store visit counts.                                                    |
| Local incrementation | `local`   | no       | `True`              | When on, count separately for this node; when off, use one counter for the whole conversation. |

**Example input:** CThis function does not use the user input utterance.

**Example output:**

```
1
```

## Current conversation id

Technical name: `current_conversation_id`

Extract the current conversation ID from the conversation context.

**Example input:** This function does not use the user input utterance.

**Example output:**

```
text_12345
```

## Last utterance extractor

Technical name: `utterance`

Extract the raw text of the user’s last utterance from the conversation history

* Not shown in the tool list until you type its name – start typing `utterance`.
* Can also be used in expressions as `last_utterance()`.
* Advanced – usually set up together with Born Digital.

**Example input:** I would like to check my balance

**Example output:**

```
I would like to check my balance
```

## Preprocessed utterance

Technical name: `preprocessed_utterance`

Joins preprocessed tokens into a full user utterance.

**Example input:** This function does not use the user input utterance.

**Example output:**

```
hello world this is a test
```

## Previous conversations

Technical name: `previous_conversations`

Return the count or list of previous conversations for a user based on filters and verbosity.

| Parameter      | Name             | Required | Default       | Description                                                         |
| -------------- | ---------------- | -------- | ------------- | ------------------------------------------------------------------- |
| Filter key     | `filter_key`     | no       | `PhoneNumber` | Key to filter previous conversations by (e.g., 'customer\_id').     |
| Filter value   | `filter_value`   | no       |               | Value to match for the filter key in previous conversations.        |
| Weeks          | `weeks`          | no       | `0`           | Number of weeks to look back for past conversations.                |
| Days           | `days`           | no       | `0`           | Number of days to look back for past conversations.                 |
| Hours          | `hours`          | no       | `0`           | Number of hours to look back for past conversations.                |
| Minutes        | `minutes`        | no       | `0`           | Number of minutes to look back for past conversations.              |
| Seconds        | `seconds`        | no       | `0`           | Number of seconds to look back for past conversations.              |
| Ignore user id | `ignore_user_id` | no       | `False`       | When on, previous conversations are not filtered by `user_id`.      |
| Verbose        | `verbose`        | no       | `False`       | When on, return a list of the conversations instead of their count. |
| Variables      | `variables`      | no       | `[]`          | List of variable names to include in verbose output.                |
| Db tables      | `db_tables`      | no       |               | List of database table names to search for previous conversations.  |

**Example input:** This function does not use the user input utterance.

**Example output:**

```
2
```

## Selected intent

Technical name: `selected_intent`

Extract details of the most recent ACTIONS-selected intent from conversation history

**Example input:** This function does not use the user input utterance.

**Example output:**

```
{'Source': 'START', 'SelectedIntent': 'INTENT_TO_LOOP', 'Confidence': '1.000'}
```

## Send call to analytics

Technical name: `send_call_to_analytics`

Sends the finished voice call – its recording or its transcript, with call details and the flow variables you pick – to an Insights project, the same way realtime agents do. Call it from the node that the hang-up signals (`call_end_customer_hangup`, `call_finished`) lead to. The tool returns at once; the call reaches Insights when its recording is ready (up to 5 minutes). A call is sent only once.

| Parameter            | Name                 | Required | Default | Description                                                                            |
| -------------------- | -------------------- | -------- | ------- | -------------------------------------------------------------------------------------- |
| `project_id`         | Analytics project ID | yes      | –       | The Insights project the call is sent to (its ID, or a `{variable}` holding it).       |
| `analyse`            | Analyse              | yes      | `audio` | `audio` – the recording (the transcript when there is no recording), or `transcript`.  |
| `metadata_variables` | Metadata variables   | no       | –       | Flow variables sent as call metadata. Pick them from the list of the flow's variables. |
| `send_all_metadata`  | Send all variables   | no       | `false` | Send every simple flow variable as metadata.                                           |

Call and conversation IDs, both phone numbers, call direction, start, end, duration and end reason are always sent. Secret and not-logged variables are never sent.

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2FurwwYvmdTtkhgPmrER44%2Ftools-send-call-to-analytics-metadata.png?alt=media" alt="The Send call to analytics tool in a flow node with Analyse set to transcript, two flow variables picked in Metadata variables and the hint listing what is always sent"><figcaption><p>Flow variables picked as call metadata</p></figcaption></figure>

Set up by Born Digital on request: the connection to Insights must be configured for your environment.

**Example output:**

```
{'status': 'queued', 'reason': None}
```

<figure><img src="https://4261467870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6iQTvxgRZRwPS1NgIGEb%2Fuploads%2F65mMYQSMRMeCRRuACYMV%2Ftools-send-call-to-analytics-insights-result.png?alt=media" alt="The Detailed View of a call result in Insights with the meta_input fields sent by the flow, such as analyse mode, call result, channel, end reason and the transcript"><figcaption><p>The call in Insights with the metadata from the flow</p></figcaption></figure>

## Utterance score

Technical name: `get_utterance_score`

Returns output of intent recognition in conversation history (candidates for intents with their score).

| Parameter  | Name         | Required | Default | Description                                             |
| ---------- | ------------ | -------- | ------- | ------------------------------------------------------- |
| Return all | `return_all` | no       | `False` | If set to True, extractor will return all last intents. |

**Example input:** utterance

**Example output:**

```
[LIST_OF_INTENTS, SCORE]
```

## Widget announcement

Technical name: `widget_announcement`

Returns data for the `announcement` widget

* Can also be used in expressions as `widget_announcement()`.

| Parameter | Name        | Required | Default | Description                       |
| --------- | ----------- | -------- | ------- | --------------------------------- |
| Widget ID | `widget_id` | no       |         | ID of the announcement to return. |

## Winning intent

Technical name: `winning_intent`

Check if a specified intent wins with a score above a threshold. Works only with training set intents

| Parameter     | Name        | Required | Default | Description                                                 |
| ------------- | ----------- | -------- | ------- | ----------------------------------------------------------- |
| Threshold     | `threshold` | yes      |         | Score threshold to compare against the winning intent score |
| Target intent | `target`    | yes      |         | Intent name or pattern to check for dominance               |

**Example input:** Please change my day limit

**Example output:**

```
True
```
