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).
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<br/>defined in CVG project<br/>
CVG->>Bot: POST /inactivity
end
end
Bot->>CVG: POST /call/say
note right of Bot: final words of Bot<br/>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:
Resellers
Customers
Accounts
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):
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:
Reseller Admin
Customer Admin
Account Admin
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:
OAuth 2 Authorization Grant: Users authenticating themselves using their email, password, and TOTP token (User-to-Machine authentication)
OAuth 2 Client Credentials Grant: Applications authenticating themselves as a service account with the corresponding client credential pair (Machine-to-Machine authentication)
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 used by many applications and cloud services, specified by RFC 6749. A more high-level description can be found at oauth.com.
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.
Recording Downloads
CVG’s 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.