Mautic API: How to integrate with WordPress plugin

[shulard]

Hello,

As we already discussed on Slack, I create this thread to discuss and define how to implement Mautic API features inside the WordPress plugin.

This issue will be used as a request for comment around the features to be introduces.

To be tracked :

• Adding a settings section/page to store API credentials
  • Allow to generate a token and to refresh token
  • Add documentation to help users generating public key / secret inside Mautic
• Create a wrapper around WP HTTP API to interact with Mautic / Maybe embed mautic/api-library...
• Create a wpmautic_api_init hook to easily plug custom code which rely on API

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[robwent]

I'm not totally familiar with how other WP plugins do this, but I have seen a few which have add-on plugins and work together with the main plugin and can hook into events that the main plugin defines.

So my thoughts were that the main Mautic plugin has either an extra 'API settings' page, or API settings are just integrated into the existing settings page (Since the base url is already added there).

If a public key/secret pair is added to the settings, on save, it checks to see if an authentication token is already saved as an option.
If not, it tries to authenticate and then saves the token in the db.
If a token already exists then there is a 'reauthenticate' button which attempts to refresh the token (If api settings are changed or updated but a token already exists for the old key) or maybe a delete connection option which removes the key/secret/token.

Once authenticated, the API is opened up to other plugins through actions/hooks (Not sure how it works).

I would imagine a hook for each endpoint of the API. For example, the segments: https://developer.mautic.org/#segments has the actions

• get
• list
• create
• edit
• delete
• add contact to segment
• remove contact from segment

So another plugin could then hook into the segments endpoint and pass a method and some parameters like 'add', '6', ['email' => 'user@domain.com', 'wp-id' => 34]

I'm no WP master but could help with the connection part.

[shulard]

Hello,

So what's the goal of this integration ? Adding new contacts directly using API ? Retrieve the list of existing contacts ? Displaying some graphs in WP admin ?

I've added a to do list in the description to track each point to be adressed.

[robwent]

It could be anything that is allowed through the api.

For example, I just started a plugin which works with memberpress.
The plugin gets the list of segments from mautic and lets the admin map a membership level to one or more segments.
When someone is added to a membership level there are some actions like 'mepr-txn-status-complete' which happens when a transaction is completed and passes the user object, so I use that to check the level they have subscribed to, which segments that level is mapped to, and then push the user into those segments in Mautic.
When the membership ends, another hook runs and I remove the user from those segments.

Another plugin might want to add a user directly to a campaign
Another, sync new WP users to Mautic
Display Mautic stats in the WP dashboard etc

It could be anything, but having one main connection in the main plugin would make it easier/faster to develop new integrations as the dev wouldn't need to go through the authentication process, just hook into the methods provided by the main plugin.

It would also make plugins less likely to break if there were any changes to the api library as it would only need to be updated in the main plugin.
EG I copied the code from the 'mautic form integrator' plugin and noticed that it is using some deprecated methods which will be removed in Mautic 3.0, but the plugin hasn't been updated since it was released. If that was hooking into the main plugin that wouldn't matter as the main library could be updated without an update to that specific plugin. The WP action hooks would stay the same.

[robwent]

I think I was probably over thinking this.

Since hooks and actions and whatnot happen when other code runs, my previous comments probably don't make sense.

The main plugin would only need to provide the authentication part to get the API connected to the site.

Once connected, we can set an option to let other plugins know that the connection is available. Then other plugins could use the class with something like:

if (!get_option( 'mautic_api_active' )) {
    //Main plugin is not connected
    return flase;
}

if (!class_exists('MauticApi')) {
    //Check to see if the class is loaded by another plugin
    //If not, load it from the main plugin
    include_once plugin_dir_path( __DIR__ ).'wp-mautic/vendor/api.php';
}

$api        = new MauticApi();
$segmentApi = $api->newApi("segments", $auth, $baseUrl . '/api/');
$segments   = $segmentApi->getList();

Is there a better 'Wordpress' way to do something like this?

[shulard]

Hello @robwent,

I think that we can create a hook in the Mautic plugin which will be executed when the API is correctly configured. The this hook will give access to an "API" object and everything necessary to interact with the API (inspired by rest_api_init hook).

Then in the custom plugin we can just add a code like :

add_action('wpmautic_api_init', function(MauticApi $api) {
    //Here the $api variable contains a fully functional API wrapper.
});

I think it simpler than relying on custom loading when the plugin is active or not...

It's also possible to display a message in the admin to the user when the root plugin is not active using the is_plugin_active function.

Actually it's not possible to declare plugin dependencies within the WP ecosystem, there are different discussion around but nothing really active.

However, WordPress rely on a solid HTTP library (https://github.com/rmccue/Requests) to perform API calls, this is a good starting point 😄.

I've updated to global TODO list.

[robwent]

That sounds perfect!

Where's the TODO list?

[shulard]

In the issue description : #issue-233515074

[luizeof]

@shulard do you have any due date to add Mautic API?

I want to add Facebook Social Login to plugin (https://developers.facebook.com/docs/php/howto/example_facebook_login) , but would be nice use Mautic API to create user.

My idea is create a shortcode [mautic_facebook_login] to display Facebook Login Button and after successful login add lead to Mautic.

[shulard]

Hello @luizeof,

Sorry but I was really busy during the summer and can't find the time to start working on that wrapper... I hope adding this feature before the middle of september. I'll inform here when it'll be ready...

[shulard]

Hello guys,

Sorry about the inactivity here but I had a lot of different subjects to work on...

I found that @escopecz has already created an API client for Mautic. Maybe we can embed his code and use it inside our WordPress plugin ?

Have you already used it ? Any feedback ?

[robwent]

Probably better to use the official library? https://github.com/mautic/api-library

[luizeof]

@shulard we use the official api every day and is very stable.

[robwent]

I basically copied the form integrator plugin to integrate it into my own stuff.
Could take a look at that, but I did run into some issues refreshing OAuth tokens