Dialogflow APIs

This extension defines a few APIs that you might find useful.

Note: we're planning a fairly significant refactor of the internals of this extension as part of a new release. If you'd like to get involved, please get in contact so we can co-ordinate.

Credentials

The DialogflowCredentials API entity allows you to tell CiviCRM where is the key file needed to connect with a Dialogflow agent.

<?php // Example: Set your credentials file

civicrm_api3('DialogflowCredentials', 'set', [
    'credentials' => '/var/private/google-credentials.json',
]);

Intents

DialogflowIntent is a standard BAO API entity that facilitates to create, retrieve, update and delete (CRUD) operations for your intents.

When you create an intent, you'll be prompted by its type. The most basic type is "Newsletter Subscription". Once you've set the intent's type, you may be prompted other questions about it.

The available types are determined by the registered handlers in your system. (See below for more information about handlers.)

<?php // Example: Search intent's of a given type

civicrm_api3('DialogflowIntent', 'get', [
    'type' => 'subscribe',
]);

Remote creation

When you create a new intent, it will be registered remotely for your Dialogflow agent.

For instance, if you call the create intent API:

<?php // Example: Create a new intent

civicrm_api3('DialogflowIntent', 'create', [
    'type' => 'subscribe',
    'settings' => [
        'group_id' => 2,
        'phrases' => [
            'I want to be informed about your work',
            'What does your organization do?',
            'I want to subscribe to your newsletter',
            'What should I do to receive your digital magazine?',
        ],
        'email_prompts' => [
            'If you give me your email address, I can subscribe you to our newsletter',
            'What\'s your email address? Tell me and you\'ll receive our emails',
        ],
        'thank_you' => 'You\'ll receive an email to confirm your subscription',
    ],
]);

An intent will be registered for you behind the scenes. You can check it because you'll find that the name, which we didn't assign, now contains the remote intent identifier.

<?php
[
    "is_error" => 0,
    "version" => 3,
    "count" => 1,
    "id" => 3,
    "values" => [
        3 => [
            "id" => "3",
            "name" => "projects/newagent-nenppa/agent/intents/cb272d3f-a6d6-4326-b464-e54adc92d20f",
            "intent_type_id" => "1",
            "settings" => '{"group_id":"2","phrases":["I want to be informed about your work","What does your organization do?","I want to subscribe to your newsletter","What should I do to receive your digital magazine?"],"thank_you":"You\'ll receive an email to confirm your subscription"}',
        ],
    ],
]

Also note that the intent_type_id has been set for us taking the type we specified as the reference.

As this is a standard CiviCRM API, you only have to add a id parameter to your call in order to update an existing intent. If you do that, the intent will be deleted and recreated remotely, so the intent name property will change.

Remote Deletion

Intents can be removed as if they were a normal API entity. Its remote counterpart will be automatically removed.

<?php // Example: Remove an intent

civicrm_api3('DialogflowIntent', 'delete', [ 'id' => 1 ]);

But some things can cause an error during the remote deletion, like if the intent was deleted directly from the Dialogflow console. In that case, the previous call would fail. To remove an intent without trying to delete it remotely, you can also use the skip_remote_deletion parameter:

<?php // Example: Remove an intent only locally

civicrm_api3('DialogflowIntent', 'delete', [
    'id' => 1,
    'skip_remote_deletion' => 1,
]);

Intents Table

You'll find the intents managed by this API are in the civicrm_dialogflow_intents table. The table schema is available in xml/schema/CRM/Dialogflow/DialogflowIntent.xml.

Intent Types

DialogflowIntentType is also a standard BAO API entity that implements CRUD operations for your handlers.

Handlers are entities meant to be used by developers when they want to implement a new type of intent.