Convoworks

Convoworks is a PHP framework for managing conversational services (Amazon Alexa skills, Google actions and chatbots over Dialogflow, Viber, FB Messenger ...) Here are few key features:

• It defines conversation as a stream of reusable components which are manageable through admin API
• It handles communication layer with connected platforms
• It highly relies on PSRs and own interface definitions, so it can be used with any PHP application.

Overview

There are several logical parts inside Convoworks framework.

Core interfaces and implementations

This part defines what is service, and what kind of components it can use. It also defines persistence and platform communication layer.

Here are few parts to notice

• \Convo\Core\Workflow namespace - defines workflow component types - elements, processors, filters
• \Convo\Core\Intent namespace - defines Convoworks intent model
• \Convo\Core\Params namespace - defines how the service runtime parameters are accessed or set
• \Convo\Core\Publisher namespace - defines how we propagate definition to platforms
• \Convo\Core\Factory namespace - defines how the service is loaded and how the components are created
• \Convo\Core\ConvoServiceInstance class - the concrete service executor class

Admin REST

Admin rest allows access and management of the conversation workflow and publishing process. All handlers are placed in \Convo\Core\Admin namespace.

You can use the Convoworks Editor which is tailored to cover all Convoworks admin api functionalities.

There is also a Postman definition you can find in the docs folder which describes full API.

Adapters

Each supported platform has its own folder in the \Convo\Core\Adapters which contains several specific implementations required by the Convoworks. Firstly it defines http request handler for accepting platform requests. Then it defines how to create Convoworks request/response objects which are used in service workflow. It also implements how the service definition is propagated to target platforms.

Default component packages

Convoworks is shipped with a couple of packages which you'll use most of the time.

• Core - This package is required in all services. Contains basic components that you will use most of the time. It also contains standard intent and entity definitions, common functions and service templates.
• Dialogflow - Google assistant specific components
• Gnlp - Google NLP based filtering - Can not be used with Alexa
• Text - Plain text based filtering - Can not be used with Alexa
• Visuals - Visual conversation elements

Integration

You can import and run Convoworks with in literally any PHP web application. If your app uses PSR compatible framework and Dependency Injection, than it is even easier.

Convoworks exposes its functionality through admin and public REST apis. Public API is used by conversational platforms (e.g. Amazon Alexa) and it does not need authentication. Each supported platform has its own handler. Admin API serves for managing the conversation flow, configurations and release handling. It requires authenticated user requests.

In order to mount Convoworks REST handlers, we have to bootstrap them somehow and we have to provide few implementations required by the system.

Admin users

Serves for accessing the logged user and enables saving some specific user data (e.g. platform access configuration), service ownership and sharing.

Convoworks is accessing user data through \Convo\Core\IAdminUserDataProvider interface which returns \Convo\Core\IAdminUser objects. You have to implement these two interfaces, because the user management is always system specific.

Service data storage

Service data layer defines loading/saving service data, managing versions and releases and stores service related, runtime parameters. It is defined with \Convo\Core\IServiceDataProvider, \Convo\Core\Params\IServiceParams and \Convo\Core\Params\IServiceParamsFactory interfaces.

We provided two service data implementations, one stores data on the filesystem - convoworks-data-filesystem and one is working with mysql - convoworks-mypdo.

Http factory

Convoworks requires a PSR compatible http client and uses it through the \Convo\Core\Util\IHttpFactory interface. You can use our convoworks-guzzle implementation.

Bootstrapping

Although you can manually create all required classes, we recommend using an PSR compatible DI container.

Here is the full ecosystem:

System utils

DI key	Type	Description
logger	\Psr\Log\LoggerInterface	Provides logger
httpFactory	\Convo\Core\Util\IHttpFactory	Provides http layer access to the system
currentTimeService	\Convo\Core\Util\ICurrentTimeService	Allows as to have mockable time provider
cache	\Psr\SimpleCache\CacheInterface	Provides access to cache infrastructure

Core functionality

DI key	Type	Description
adminUserDataProvider	\Convo\Core\IAdminUserDataProvider	Allows integration with your own admin users
convoServiceParamsFactory	\Convo\Core\Params\IServiceParamsFactory	For handling runtime parameters
convoServiceDataProvider	\Convo\Core\IServiceDataProvider	Service data persistance layer
serviceMediaManager	\Convo\Core\Media\IServiceMediaManager	Service media storage
convoServiceFactory	\Convo\Core\Factory\ConvoServiceFactory	Loads runnable service instance
platformRequestFactory	\Convo\Core\Factory\PlatformRequestFactory	Updates text based requests to intent based, through delegate platform
packageProviderFactory	\Convo\Core\Factory\PackageProviderFactory	Provides access to concrete package definitions
serviceReleaseManager	\Convo\Core\Publish\ServiceReleaseManager	Updates release and version information
platformPublisherFactory	\Convo\Core\Publish\PlatformPublisherFactory	Provides concrete platform publishers - \Convo\Core\Publish\IPlatformPublisher

Platform specifics

DI key	Type	Description
amazonAuthService	\Convo\Core\Adapters\Alexa\AmazonAuthService	Enables authentication for Amazon Alexa SMAPI
alexaRequestValidator	\Convo\Core\Adapters\Alexa\Validators\AlexaRequestValidator	Validates Amazon Alexa requests
amazonPublishingService	\Convo\Core\Adapters\Alexa\AmazonPublishingService	Our SMAPI implementation
dialogflowApiFactory	\Convo\Core\Adapters\Dialogflow\DialogflowApiFactory	Provides access to Dialogflow API
facebookMessengerApiFactory	\Convo\Core\Adapters\Fbm\FacebookMessengerApiFactory	Provides access to FB Messenger API
viberApi	\Convo\Core\Adapters\Viber\ViberApi	Our Viber API implementation

Admin API specifics

DI key	Type	Description
\Convo\Core\Admin\ServicesRestHandler	\Convo\Core\Admin\ServicesRestHandler	Service management
\Convo\Core\Admin\ServiceVersionsRestHandler	\Convo\Core\Admin\ServiceVersionsRestHandler	Service versions and releases management
\Convo\Core\Admin\ServicePlatformConfigRestHandler	\Convo\Core\Admin\ServicePlatformConfigRestHandler	Service platform configurations
\Convo\Core\Admin\UserPlatformConfigRestHandler	\Convo\Core\Admin\UserPlatformConfigRestHandler	Updates user configurations
\Convo\Core\Admin\UserPackgesRestHandler	\Convo\Core\Admin\UserPackgesRestHandler	Access to user packages
\Convo\Core\Admin\ServicePackagesRestHandler	\Convo\Core\Admin\ServicePackagesRestHandler	Service packages management
\Convo\Core\Admin\TemplatesRestHandler	\Convo\Core\Admin\TemplatesRestHandler	Access to available templates
\Convo\Core\Admin\TestServiceRestHandler	\Convo\Core\Admin\TestServiceRestHandler	Service simulator
\Convo\Core\Admin\ServiceImpExpRestHandler	\Convo\Core\Admin\ServiceImpExpRestHandler	Import/export service data
\Convo\Core\Admin\ComponentHelpRestHandler	\Convo\Core\Admin\ComponentHelpRestHandler	Loads component help if available
\Convo\Core\Admin\ConfigurationRestHandler	\Convo\Core\Admin\ConfigurationRestHandler	Loads configuration options
\Convo\Core\Admin\MediaRestHandler	\Convo\Core\Admin\MediaRestHandler	Service media management
propagationErrorReport	\Convo\Core\Admin\PropagationErrorReport	Error reporting utility

Public API specifics

DI key	Type	Description
\Convo\Core\Adapters\ConvoChat\ConvoChatRestHandler	\Convo\Core\Adapters\ConvoChat\ConvoChatRestHandler	Handles web chat requests
\Convo\Core\Adapters\Google\Dialogflow\DialogflowAgentRestHandler	\Convo\Core\Adapters\Google\Dialogflow\DialogflowAgentRestHandler	Handles Dialogflow requests
\Convo\Core\Adapters\Google\Gactions\ActionsRestHandler	\Convo\Core\Adapters\Google\Gactions\ActionsRestHandler	Handles direct Google Actions requests
\Convo\Core\Adapters\Fbm\FacebookMessengerRestHandler	\Convo\Core\Adapters\Fbm\FacebookMessengerRestHandler	Handles Messenger requests
\Convo\Core\Adapters\Viber\ViberRestHandler	\Convo\Core\Adapters\Viber\ViberRestHandler	Handles Viber requests
\Convo\Core\Adapters\Alexa\AlexaSkillRestHandler	\Convo\Core\Adapters\Alexa\AlexaSkillRestHandler	Handles Alexa requests
\Convo\Core\Adapters\Alexa\AmazonAuthRestHandler	\Convo\Core\Adapters\Alexa\AmazonAuthRestHandler	Oauth for enabling Amazon SMAPI access
\Convo\Core\Adapters\Alexa\CatalogRestHandler	\Convo\Core\Adapters\Alexa\CatalogRestHandler	Exposes entity catalogues to Alexa
\Convo\Core\Media\MediaRestHandler	\Convo\Core\Media\MediaRestHandler	Allows public access to service media
facebookAuthService	\Convo\Core\Adapters\Fbm\FacebookAuthService	Oauth for enabling Facebook API access

REST routing

Our handlers are always expecting convo/v1 as a base for all Convoworks requests, so you can use wildcard to route all such requests to the Convoworks request handlers. Please note that we have two separate REST APIs, public and admin so they are treated and mounted separately.

Instead of mapping each request handler we have, you can use our "grouped" handlers, just one per API. \Convo\Core\Adapters\PublicRestApi for public and \Convo\Core\Admin\AdminRestApi for admin API. Only difference is that in such a case you have to use a DI container.

Registering packages

Your application will also define which Convoworks custom packages will be available for use. Packages are registered by passing \Convo\Core\Factory\IPackageDescriptor objects to the \Convo\Core\Factory\PackageProviderFactory.

<?php

// example with function based factory
/** @var \Psr\Log\LoggerInterface $logger */
/** @var \Convo\Core\Factory\PackageProviderFactory $packageProviderFactory */
$packageProviderFactory->registerPackage( new FunctionPackageDescriptor('\Convo\Pckg\Trivia\TriviaPackageDefinition', function() use ( $logger, $packageProviderFactory) {
    return new \Convo\Pckg\Trivia\TriviaPackageDefinition(
        $logger, $packageProviderFactory
    );
}));

// example with class based factory - requires DI container!
/** @var \Psr\Container\ContainerInterface $container */
$packageProviderFactory->registerPackage( new ClassPackageDescriptor('\Convo\Pckg\Trivia\TriviaPackageDefinition', $container));

Admin API Authentication

Once you have that implemented, you have to make logged user available for REST handlers. Somewhere in the app bootstrap process, set the request attribute Convo\Core\IAdminUser to your user (which implements \Convo\Core\IAdminUser).

<?php

$user       =   $this->_adminUserDataProvider->findUser( 'myusernameiremail');
$request    =   $request->withAttribute( \Convo\Core\IAdminUser::class, $user);

Roadmap

• APL support - Alexa Presentation Language allows creation of much more delightful user interfaces for Alexa devices.
• Prefix our intent model on target platforms - It will enable users to manually create additional intents and entities directly on platform and not to be overwritten when model is propagated
• Propagate platform system events - Ability to reference some platform intent or entity in a manner that it will be automatically turned on when we propagate Convoworks intent model
• Component migration interface to packages - Ability to migrate component definitions to the new version. Right now it is on the core level, but should be on the package.
• Package files - ability to deploy files inside component packages to be used in services (mp3 audio prompts, images ...)
• Increase unit test coverage -

Convoworks Prototype

You can check our example integration called Convoworks Prototype. You can download it and find more information here

---

For more information, please check out convoworks.com