Dialogflow Fulfillment PHP Library

This Library is inspired by dialogflow/dialogflow-fulfillment-nodejs.

It supports Dialogflow's fulfillment webhook JSON requests and responses for v1 and v2 agents.

For full class reference please refer to the doc.

• Installation
• Usage
  • Initiate Agent
  • Get Request Info
  • Send Reply
  • Rich Message
    • Text
    • Image
    • Card
    • Suggestion
    • Custom payload
  • Actions on Google
    • Send Reply
    • Responses
      • Simple Response
      • Image
      • Basic Card
      • List
    • Surface Capabilities

Installation

Install via composer: composer require eristemena/dialogflow-fulfillment-webhook-php.

Usage

Initiate Agent

To initiate agent, use \Dialogflow\WebhookClient constructor with input parameter as array of request coming from Dialogflow.

In Vanilla PHP, this can be done as follow,

use Dialogflow\WebhookClient;

$agent = new WebhookClient(json_decode(file_get_contents('php://input'),true));

// or

$agent = WebhookClient::fromData($_POST);

or if you're using Laravel,

$agent = \Dialogflow\WebhookClient::fromData($request->json()->all());

Get Request Info

• Intent

$intent = $agent->getIntent();

• Action

$action = $agent->getAction();

• Query

$query = $agent->getQuery();

• Parameters

$parameters = $agent->getParameters();

• Session

$session = $agent->getSession();

• Contexts

$contexts = $agent->getContexts();

• Language

$language = $agent->getLocale();

• Request Source (ex: google, facebook, slack, etc)

$originalRequest = $agent->getRequestSource();

• Original Request, platform specific payload

$originalRequest = $agent->getOriginalRequest();

• Agent Version (1 or 2)

$agentVersion = $agent->getAgentVersion();

Send Reply

To send a reply, use reply() method.

$agent->reply('Hi, how can I help?');

Then use render() to get response in array. All you have to do is to print the array as JSON,

header('Content-type: application/json');
echo json_encode($agent->render());

or in Laravel,

return response()->json($agent->render());

The response payload will be automatically formatted according to Agent Version of the request.

Rich Message

Text

$text = \Dialogflow\RichMessage\Text::create()
    ->text('This is text')
    ->ssml('<speak>This is <say-as interpret-as="characters">ssml</say-as></speak>')
;
$agent->reply($text);

Image

$image = \Dialogflow\RichMessage\Image::create('https://www.example.com/image.png');
$agent->reply($image);

Card

$card = \Dialogflow\RichMessage\Card::create()
    ->title('This is title')
    ->text('this is text body')
    ->image('https://www.example.com/image.png')
    ->button('This is a button', 'https://docs.dialogflow.com/')
;
$agent->reply($card);

Suggestion

$suggestion = \Dialogflow\RichMessage\Suggestion::create(['Suggestion one', 'Suggestion two']);
$agent->reply($suggestion);

Custom payload

if ($agent->getRequestSource()=='google') {
    $agent->reply(\Dialogflow\RichMessage\Payload::create([
        'expectUserResponse' => false
    ]));
}

Actions on Google

This library also supports Actions on Google specific functionalities. It's still under development, so more features will be added in the future.

To use Actions on Google Dialogflow Conversation object, you must first need to ensure the requestSource is coming from Google Assistant,

if ($agent->getRequestSource()=='google') {
    $conv = $agent->getActionConversation();
    
    // here you can use the rest of Actions on Google responses and helpers
    
    $agent->reply($conv);
}

or you can just call getActionConversation() method, and it will return null if the request doesn't come from Google Assistant.

$conv = $agent->getActionConversation();

if ($conv) {
	// here you can use the rest of Actions on Google responses and helpers
} else {
	// the request does not come from Google Assistant
}

Send Reply

Using Dialogflow Conversation object, you can send a reply in two ways,

1. Send a reply and close the conversation

$conv->close('Have a nice day!');

2. Send a reply and wait for user's response

$conv->ask('Hi, how can I help?');

Responses

Simple Response

Please see the documentation here.

use Dialogflow\Action\Responses\SimpleResponse;

$conv->ask(SimpleResponse::create()
     ->displayText('Hello, how can i help?')
     ->ssml('<speak>Hello,<break time="0.5s"/> <prosody rate="slow">how can i help?</prosody></speak>')
);

Image

use Dialogflow\Action\Responses\Image;

$conv->close(Image::create('https://picsum.photos/400/300'));

Basic Card

Please see the documentation here.

use Dialogflow\Action\Responses\BasicCard;

$conv->close(BasicCard::create()
    ->title('This is a title')
    ->formattedText('This is a subtitle')
    ->image('https://picsum.photos/400/300')
    ->button('This is a button', 'https://docs.dialogflow.com/')
);

List

The single-select list presents the user with a vertical list of multiple items and allows the user to select a single one. Selecting an item from the list generates a user query (chat bubble) containing the title of the list item.

Please see the documentation here.

use Dialogflow\Action\Questions\ListCard;
use Dialogflow\Action\Questions\ListCard\Option;

$conv->ask('Please choose below');

$conv->ask(ListCard::create()
    ->title('This is a title')
    ->addOption(Option::create()
        ->key('OPTION_1')
        ->title('Option 1')
        ->synonyms(['option one','one'])
        ->description('Select option 1')
        ->image('https://picsum.photos/48/48')
    )
    ->addOption(Option::create()
        ->key('OPTION_2')
        ->title('Option 2')
        ->synonyms(['option two','two'])
        ->description('Select option 2')
        ->image('https://picsum.photos/48/48')
    )
);

To capture the option selected by user, create a Dialogflow intent with the actions_intent_OPTION event. Assuming you name the intent as Get Option, you can get the argument as follow,

if ('Get Option'==$agent->getIntent()) {
    $conv = $agent->getActionConversation();
    $option = $conv->getArguments()->get('OPTION');

    switch ($option) {
        case 'OPTION_1':
            $conv->close('You choose option 1');
            break;
        
        case 'OPTION_2':
            $conv->close('You choose option 2');
            break;
        
        default:
            $conv->close('Sorry, i do not understand');
            break;
    }
}

Surface Capabilities

Google Assistant can be used on a variety of surfaces such as mobile devices that support audio and display experiences or a Google Home device that supports audio-only experiences.

To design and build conversations that work well on all surfaces, use surface capabilities to control and scope your conversations properly.

$surface = $conv->getSurface();

if ($surface->hasScreen()) {
	// surface has screen
} elseif ($surface->hasAudio()) {
	// surface has audio
} elseif ($surface->hasMediaPlayback()) {
	// surface can play audio
} elseif ($surface->hasWebBrowser()) {
	// user can interact with the content in a web browser
}