Download the PHP package zef-dev/convoworks-core without Composer

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

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.

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).

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