# Core Concepts of CVG ## 'Voice-ify' your Calls With our user-friendly REST-based APIs you can handle your incoming and outgoing calls just as easy as web requests. You only need to implement a few web hooks to get informed about new calls and to receive utterances as text. Use the programming language, NLU and NLP you love to build applications like voicebots and assistants. Send text back to us for a spoken answer. Use SSML too make the answer sound more natural. ## Cloud Platform CVG is a Cloud Platform, fully operated in a carrier-grade datacenter on our own hardware in Frankfurt, Germany. For our international customers we can make CVG available in our datacenters in Atlanta, Georgia, USA, and Singapore. ## Project A *CVG project* is the link between the caller and the text-based bot of the customer: * One CVG project is required per bot and per language. * A telephone number assigned to the project can be used to call the bot. * A project can be identified by a generated project token. * A project is assigned to one CVG account (of one CVG customer). ## Dialog and Bot Each call linked with a CVG project is considered as a *dialog*. A dialog starts with the beginning of the phone call and ends with the end of the call. It includes the complete conversation in this phone call between the caller and a bot. CVG generates permanent, unique dialog identifiers (dialogId) that remain valid for the duration of a call. It notifies the bot about each new call and passes the dialog identifier along. The following image shows a general sequence diagram of such a dialog. “Bot” (also known as “Virtual Agent”) in this picture summarizes * the integration service (provided by CVG ord 3rd party) plus * the 3rd party conversational AI (e.g. Boost.ai, Cognigy, Dialogflow, Jovo, Parlamind, Ubitec) plus * the specific bot implementation (such as intent recognition and answer generation). ```mermaid:: sequenceDiagram; Caller->>CVG: Phone Call CVG->>Bot: POST /session loop dialog between Caller and Bot Bot->>CVG: POST /call/say note left of Bot: text CVG->>Caller: audio announcement note right of Caller: speech alt something is said Caller->>CVG: some utterance note right of Caller: speech CVG->>Bot: POST /message note left of Bot: text else nothing is said note right of Bot: inactivityTimeout
defined in CVG project
CVG->>Bot: POST /inactivity end end Bot->>CVG: POST /call/say note right of Bot: final words of Bot
in this dialog Bot->>CVG: POST /call/drop CVG->>Caller: Phone Call on CVG dropped ``` ## Organizational Units CVG has four organizational units, with a 1:n relation from each unit to the next: 1. Resellers 2. Customers 3. Accounts 4. Projects ### Resellers Resellers are service providers. A reseller forms the root of the organizational structure. Everything else on the platform, except for certain globally shared resources (speech cloud profiles, platform numbers), is linked to a reseller. ### Customers & Accounts Each reseller can have an arbitrary number of customers, which would represent its own direct customers (customer = company = legal entity). Each customer can have an arbitrary number of accounts below it, representing a level of customer-specific organizational separation (account = business unit). ### Projects Accounts, and only accounts, can have an arbitrary number of projects. A project represents a single voice bot, with all the necessary configuration to make it work (languages, speech vendors, voice options, bot configuration, ...). ### Hierarchical Settings Some settings can be configured on each level of the hierarchy (reseller, customer, account, and project). These settings act as _constraints_ for the child units: - call recordings can only be allowed if all parents allow them - the maximum allowed recording retention time is limited to the parent's maximum retention time - phone number anonymization can't be disabled if it's enabled for the parent - the maximum allowed dialog data retention time is limited to the parent's maximum retention time Here's an example hierarchy where phone number anonymization is enabled for `Customer2`. This means that phone number anonymization will be used for all projects within `Customer2` (and can't be disabled on account or project level because it's required by the organization / customer): ```mermaid:: stateDiagram-v2 Reseller Reseller --> Customer1 Reseller --> Customer2 Customer1 --> Account1 Customer1 --> Account2 note left of Customer2 : Activated Phone number anonymization state Customer2 { [*] --> Account3 : Forces Anonymization [*] --> Account4 : Forces Anonymization state Account3 { [*] --> Project1 : Forces Anonymization [*] --> Project2 : Forces Anonymization } state Account4 { [*] --> Project3 : Forces Anonymization [*] --> Project4 : Forces Anonymization } } ``` ## Users and Owners ### Users Users are persons that are given credentials to access the CVG Console for management and configuration tasks. Each user may have one of four roles: 1. Reseller Admin 2. Customer Admin 3. Account Admin 4. Project Admin An admin of a certain organizational unit can see all other units below it. ### Owners CVG has, in certain places the concept of an owner. Ownership is modeled on an organizational unit level, not on users. If something is owned (e.g. a speech cloud profile or a platform number block), it is owned by a reseller, customer or a project, but not by a user. Users would be considered owners, if the user has the owning organizational unit *directly* assigned and only that unit.

Example

A speech cloud profile owned by a customer can not be edited by a user that only has a reseller assigned, even though that user can see the profile. Also, a user assigned directly to a project would not be able to edit the profile, even though he can use it. Only a Customer Admin with that specific customer ID would be able to edit it.

### Service Accounts Service Accounts are similar to users, but represent machines that want to automate tasks using CVG's various APIs. Access control works no different compared to users, however Service Accounts cannot log into the CVG Console. Upon creation of a service account, its credentials will be presented once to the user (or service account) that created it. The credentials cannot be changed and will never be presented again. If credentials need to be rotated, a new service account has to be created instead and the old one must be deleted. ## Authentication Mechanisms The CVG Console and all the available APIs require explicit authentication using one of three mechanisms: 1. OAuth 2 Authorization Grant: Users authenticating themselves using their email, password, and TOTP token (User-to-Machine authentication) 2. OAuth 2 Client Credentials Grant: Applications authenticating themselves as a service account with the corresponding client credential pair (Machine-to-Machine authentication) 3. Bot Auth Tokens: A bot authenticating as themselves using a token supplied to the bot (Machine-to-Machine authentication) ### OAuth 2 Client Credentials Grant This is a standardized authentication protocol which is similarly used by many cloud services, which is specified by [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4). A more high-level description can be found at [oauth.com](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/). A lot of modern HTTP client software already has native support for automatic authentication using this mechanism. CVG does not require any scopes. The resulting access token will be valid for 30 minutes, refresh tokens are not available. ### Bot Auth Tokens As a measure to simplify authentication from bots, a very common use-case, CVG provides an access token to the bot as part of every event sent to the bots. The access token is valid for the entire during of the dialog plus a small grace period to account for some degree of processing delay on the the bot's end. Each dialog will receive a dedicated access token. Conversational AI integrations provided by CVG will automatically use this token when performing any call actions, the token is still provided to the dialog engine to allow for out of band requests to CVG's API. ### Authorization Different authentication mechanisms will receive slightly different privileges. As mentioned before, only users will be able to log in on to the CVG Console through a browser. Service account credentials cannot be used for this purpose. Users can access any API except the [Call API](/specs/?urls.primaryName=Call+API); however, data access is restricted to the organizational units they have been given access to. Service accounts also have access to the same APIs as users, and their data access is also restricted to the organizational unit on which they have been created. Bots can access any API _including_ the [Call API](/specs/?urls.primaryName=Call+API) with the "Bot Auth Token" provided to them with every Bot API request CVG performs. ### Recording Downloads CVG's [Recording API](/specs/?urls.primaryName=Recording+API) is subject to the authentication and authorization mechanisms previously mentioned. The URLs provided by `GET` endpoint however don't require additional authentication. These URLs have authentication information encoded into them. Additionally, the URLs are very short-lived and should only be used for immediate downloads of the files.