# CVG 1.10.0 (27-Apr-2021)

This release is focused around a number of _quality-of-life_ features that make CVG's APIs more convenient for
developers.

![simplifying developers' lives](simplify-life.jpg)


## Custom SIP Headers

CVG now supports custom SIP headers (headers that start with `X-`). 

### Inbound Calls

For inbound calls, custom SIP headers can be used to send specific data from your SIP application (e.g. Contact Center, IVR, PBX) to your bot via CVG. Custom SIP headers are read by CVG from the SIP requests and transferred to your bot.

- In the [Bot API](/specs/?urls.primaryName=Bot%20API%20(Client)),
  the [`session`](/specs/?urls.primaryName=Bot%20API%20(Client)#/bot/session) event now includes
  a `customSipHeaders` property. Note that header names are always lowercased.
- Just like with the session event, the `Start` entry in
  the [Dialog API](/specs/?urls.primaryName=Dialog%20API) includes the `customSipHeaders` as well.

If your SIP application send headers without `X-` prefix, CVG will not pass these headers to your bot and will not store these headers in the dialog data.

<div class="admonition note">
<p class="admonition-title">Custom SIP Headers vs Provisioning</p>
<p>If you are currently using the <a href="/specs/?urls.primaryName=Provisioning%20API"><code>Provisioning API</code></a> to indirectly deliver custom data to the bot via the Dialog API, custom SIP headers might be a more straightforward alternative. Simply include some custom SIP headers when forwarding the call from your contact center to CVG, and the bot will receive them as part of the session parameters.</p>
</div>

### Outbound Calls

In the [Call API](/specs/?urls.primaryName=Call%20API), endpoints that initiate outgoing
calls ([`dial`](/specs/#/call/dial), [`forward`](/specs/#/call/forward)
and [`bridge`](/specs/#/call/bridge)) can specify `customSipHeaders`. These custom headers are sent when initiating the call.

The called SIP application (e.g. Contact Center, IVR, PBX) can read these SIP headers. One possible use case is to route the call to the right agent based on the content of the custom header fields.

The `Start` entry in the [Dialog API](/specs/?urls.primaryName=Dialog%20API) includes the `customSipHeaders` also for outgoing calls.

## Health

There are a number of improvements to our Health API and its visualization:

### Health Status in Project Overview

The health status of projects is now shown as an icon in the project overview as well. This allows you to see which of your projects are healthy (or which ones had any activity within the last 10 minutes at all) at a glance:

![project overview health](project-overview-health.png)

### Health API Time Ranges

Our [Health API](/specs/?urls.primaryName=Health%20API) previously always returned project health events for
the last 10 minutes. This is still a reasonable default, but some use cases benefit from larger time ranges, 
which is now possible thanks to some new query parameters.

For instance, if you want to retrieve the health events for the **last 1 hour**, you can do so with
a `relative` time range and the amount of milliseconds:

```
/health/{resellerToken}/project/{projectToken}?timeRange=relative&delta=3600000
```

Or you could use an `absolute` time range to retrieve health events for **the entire month of April**:

```
/health/{resellerToken}/project/{projectToken}?timeRange=absolute&?start=1617228000000&end=1619819999999
```

Timestamps are in milliseconds since the epoch (1970-01-01).

### Webhook Health Status Change Events

Our [Webhook API](/specs/?urls.primaryName=Webhook%20API) now features a new `HealthStatusChanged` event, which fires whenever there are changes to the health status of a project. This means that there's now a much cleaner alternative for use cases that would have required polling our Health API previously.

The webhook event uses the default time range of 10 minutes to determine the health status.

## Improved Inactivity Timeouts

CVG's _inactivity timeouts_ have been around for a while. If enabled in a project's advanced settings, bots
will receive [`inactivity`](?urls.primaryName=Bot%20API%20(Client)#/bot/inactivity) events when the user
hasn't said anything for the specified time period.

![inactivity timeout](inactivity-timeout.png)

Starting with this release, inactivity events are no longer always sent immediately, but are instead delayed
if the timeout triggers in the middle of an utterance:

- If the utterance results in a successful transcription
  / [`message`](/specs/?urls.primaryName=Bot%20API%20(Client)#/bot/message) event, no `inactivity` event is
  sent anymore to avoid false positives.
- If there's no transcription result, the utterance was most likely just background noise and does still
  qualify as "inactivity". Note that in this case, the `duration` of an inactivity event will be longer than
  what's configured in the project settings because of the added wait.

## Improved Barge-In

Our "barge-in" functionality also benefits from the reworked timeouts: barge-in now triggers at the start of utterances
rather than at the end, which should result in a smoother dialog flow. However, barge-in is still sensitive to
background noise, so we recommend you do some testing in a realistic environment before you enable this
feature. We are working on further improvements in this area.

## Explicit SSML/Text Mode for Text-to-Speech

So far, CVG has automatically detected whether text to be synthesized contains SSML or not based on a simple
heuristic. Now, APIs that do synthesis ([`say`](/specs/#/call/say) and [`prompt`](/specs/#/call/prompt)) also
have an explicit `interpretAs` option to force either `SSML` or `TEXT`. A [`/call/say`](/specs/#/call/say)
request could look like this:

```json
{
  "dialogId": "2648a570-baf4-4940-9a7b-643a38292d38",
  "text": "<speak><prosody rate=\"125%\">Hello!</prosody></speak>",
  "interpretAs": "SSML"
}
```

You can also omit `interpretAs`, in which case the heuristic will be applied as usual. However, we recommend
that you provide the option anyway, as this enables some level of SSML validation. If you supply `text` that
is _meant_ to be `SSML`, but doesn't look like SSML to CVG, the request will return an error that looks
something like this:

```json
{
  "error": "Bad Request",
  "message": "Validation failed for text",
  "errors": [
    "Interpretation as SSML requested, but no valid SSML provided"
  ],
  "timestamp": 1618933934.398824218,
  "status": 400
}
```

<div class="admonition note">
<p class="admonition-title">Microsoft SSML Support</p>
<p>We currently do not support SSML in combination with Microsoft Text-to-Speech, but we are planning to include this functionality in a future update.</p>
</div>

## Set voice for an output message using Cognigy

Previously, when using Cognigy as conversational AI, it was only possible to change the language of an output. Now, the voice to be used can also be specified in the payload of a Say Node by providing a list of synthesizers ordered by priority. 

Here is an example for setting the voice to de-CH-LeniNeural provided by Microsoft:

```json
{
  "language": "de-CH",
  "synthesizers": ["MICROSOFT-de-CH-LeniNeural"]
}
```