README

Chatbase is a Chatbot analytics service by Google.

This is the unofficial Chatbase API for PHP. It focuses heavily on the Laravel Framework however it will work in any standalone project with usage of Composer.

Installation

This package can be installed through Composer.

composer require richdynamix/chatbase-api

Framework Agnostic Usage

// API KEY and default platform must be set
$apiKey = '12345-12345-12345';
$platform = 'messenger';

// Instantiate a new Chatbase client with the dependency of Guzzle
$client = new \Richdynamix\Chatbase\Service\ChatbaseClient(new \GuzzleHttp\Client());

// Instantiate a new FieldManager with the dependency of the API KEY and default platform
$fieldsManager = new \Richdynamix\Chatbase\Entities\FieldsManager($apiKey, $platform);

// Instantiate a new GenericMessage with the dependency of the Chatbase client and the FieldsManager
$chatbase = new \Richdynamix\Chatbase\Service\GenericMessage($client, $fieldsManager);

// send a user message to chatbase
$send = $chatbase->userMessage()->with(['user_id => '12345', 'message' => 'hello'])->send();

Laravel Usage

In Laravel >5.5 the package will auto register the service provider. In Laravel 5.4 you must install this service provider.

// config/app.php
'providers' => [
    ...
    Richdynamix\Chatbase\ChatbaseServiceProvider::class,
    ...
];

In Laravel >5.5 the package will auto register the facades. In Laravel 5.4 you must install the facade manually.

// config/app.php
'aliases' => [
    ...
    'Chatbase' => Richdynamix\Chatbase\Facades\Chatbase::class,
    ...
];

You can publish the config file of this package with this command:

php artisan vendor:publish --provider="Richdynamix\Chatbase\ChatbaseServiceProvider"

The following config file will be published in config/chatbase.php

return [
    /*
     * The Chatbase API key
     */
    'api_key' => env('CHATBASE_API_KEY'),
    'platform' => env('CHATBASE_DEFAULT_PLATFORM', 'messenger'),
];

Only the Generic Messaging API is setup at present

IoC container

The IoC container will automatically resolve the GenericMessage dependencies for you. You can grab an instance of GenericMessage from the IoC container in a number of ways.

// Directly from the IoC
$chatbase = app(Richdynamix\Chatbase\Contracts\GenericMessage::class);

// From a constructor
class FooClass {
    public function __construct(Richdynamix\Chatbase\Contracts\GenericMessage $chatbase) {
       // . . .
    }
}

// From a method
class BarClass {
    public function barMethod(Richdynamix\Chatbase\Contracts\GenericMessage $chatbase) {
       // . . .
    }
}

Alternatively you may use the Chatbase facade directly

    Chatbase::userMessage()->with($data)->send();

    Chatbase::notHandledUserMessage()->with($data)->send();

    Chatbase::botMessage()->with($data)->send();

Fields (keys) that can be set using the with() method. (Passed as an array)

Usage

All methods take the same parameters in the following order -

$userId, $message, $intent, $version, $customSessionID

Send a user message to Chatbase

    $send = $chatbase->userMessage()->with(['user_id => '12345', 'message' => 'hello'])->send();
    
    // With Facade
    $send = Chatbase::userMessage()->with(['user_id => '12345', 'message' => 'hello'])->send();
    
    // With helper setters
    $send = Chatbase::userMessage()->withUserId('12345')->withMessage('hello')->send();
    
    dd($send);

Example Response -

    {#618 ▼
      +"message_id": "2981752682"
      +"status": 200
    }

Send a user message to Chatbase for a different platform

    $send = $chatbase->userMessage()->with([
        'user_id => '12345',
        'message' => 'hello',
        'platform' => 'slack'
    ])->send();
    
    // With Facade
    $send = Chatbase::userMessage()->with([
        'user_id => '12345',
        'message' => 'hello',
        'platform' => 'slack'
    ])->send();
    
    // With helper setters
    $send = Chatbase::userMessage()
        ->setPlatform('slack')
        ->withUserId('12345')
        ->withMessage('hello')
        ->send();
    
    dd($send);

Example Response -

    {#618 ▼
      +"message_id": "2981752682"
      +"status": 200
    }

Send a user message to Chatbase while logging a version

    $send = $chatbase->userMessage()->with([
            'user_id => '12345',
            'message' => 'hello',
            'version' => '1.2.1'
        ])->send();
        
        
    // With Facade
    $send = Chatbase::userMessage()->with([
        'user_id => '12345',
        'message' => 'hello',
        'version' => '1.2.1'
    ])->send();
    
    
    // With helper setters
    $send = Chatbase::userMessage()
        ->withUserId('12345')
        ->withMessage('hello')
        ->withVersion('1.2.1')
        ->send();
    
    dd($send);

Example Response -

    {#618 ▼
      +"message_id": "2981752682"
      +"status": 200
    }

Send a user message to Chatbase with intent

    $send = $chatbase->userMessage()->with([
        'user_id => '12345',
        'message' => 'hello',
        'intent' => 'hotel-booking'
    ])->send();
        
        
    // With Facade
    $send = Chatbase::userMessage()->with([
        'user_id => '12345',
        'message' => 'hello',
        'intent' => 'hotel-booking'
    ])->send();
    
    
    // With helper setters
    $send = Chatbase::userMessage()
        ->withUserId('12345')
        ->withMessage('hello')
        ->withIntent('hotel-booking')
        ->send();
    
    dd($send);

Example Response -

    {#618 ▼
      +"message_id": "2981752682"
      +"status": 200
    }

Send failed user message not handled by the bot

    $send = $chatbase->notHandledUserMessage()
        ->with([
            'user_id => '12345',
            'message' => 'hello',
        ])
        ->send();
    
    // With Facade
    $send = Chatbase::notHandledUserMessage()
        ->with([
          'user_id => '12345',
          'message' => 'hello',
        ])
        ->send();
    
    // With helper setters
    $send = Chatbase::userMessage()
        ->withUserId('12345')
        ->withMessage('hello')
        ->withIntent('hotel-booking')
        ->send();
        
    dd($send);

Example Response -

    {#618 ▼
      +"message_id": "29817235682"
      +"status": 200
    }

Send a bot message sent back to the user

    $send = $chatbase->botMessage()->with(['user_id => '12345','message' => 'hello'])->send();
    
    // With facade
    $send = Chatbase::botMessage()->with(['user_id => '12345','message' => 'hello'])->send();
    
    // With helper setters
    $send = Chatbase::botMessage()->withUserId('12345')->withMessage('hello')->send();
    
    dd($send);

Response -

    {#618 ▼
      +"message_id": "29347235682"
      +"status": 200
    }

Working with multiple bots

Sometime you may wish to push your bot activity to different chatbase accounts. Perhaps you have multiple bots running in the one application. You can easily set the API KEY for each bot on each method call.

    $send = $chatbase->userMessage()->with([
        'api_key' => 'my-chatbase-api-key',
        'user_id => '12345',
        'message' => 'hello'
    ])->send();


    // With facade
    $send = Chatbase::userMessage()->with([
        'api_key' => 'my-chatbase-api-key',
        'user_id => '12345',
        'message' => 'hello'
    ])->send();
    
    
    // With helper setters
    $send = Chatbase::botMessage()->setApiKey('my-chatbase-api-key')->withUserId('12345')->withMessage('hello')->send();
    
    dd($send);

Example Response -

    {#618 ▼
      +"message_id": "2981752682"
      +"status": 200
    }

*Please Note: Invalid fields sent to Chatbase may result in a successful entry however, you will receive a 400 error and a WrongDataSet exception will be thrown. This is common when you set fields like intent for bot messages.

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email steven@richdynamix.com instead of using the issue tracker.

Credits

• Steven Richardson
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

About the author

Built and maintained by Steven Richardson — CTO at Digitonic and Laravel engineer.

• Site & articles: richdynamix.com
• Laravel deep-dives: richdynamix.com/articles
• More open source: github.com/richdynamix