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.
There are several logical parts inside Convoworks framework.
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\Workflownamespace - defines workflow component types - elements, processors, filters\Convo\Core\Intentnamespace - defines Convoworks intent model\Convo\Core\Paramsnamespace - defines how the service runtime parameters are accessed or set\Convo\Core\Publishernamespace - defines how we propagate definition to platforms\Convo\Core\Factorynamespace - defines how the service is loaded and how the components are created\Convo\Core\ConvoServiceInstanceclass - the concrete service executor class
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.
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.
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
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.
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 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.
Convoworks requires a PSR compatible http client and uses it through the \Convo\Core\Util\IHttpFactory interface.
You can use our convoworks-guzzle implementation.
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 |
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.
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));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);- 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 -
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