Skip to content

API.md

Latest commit

 

History

History
521 lines (356 loc) · 16.1 KB

API.md

File metadata and controls

521 lines (356 loc) · 16.1 KB
Raw

Hellotext WordPress Plugin - API Documentation

Overview

This document provides comprehensive API documentation for the Hellotext WordPress plugin. The plugin integrates WooCommerce with Hellotext's customer engagement platform, tracking customer activities and synchronizing profiles.

Table of Contents

Core Concepts

Architecture

The plugin follows a clean architecture pattern with distinct layers:

  • Api/ - HTTP clients for external communication
  • Adapters/ - Transform WooCommerce data to Hellotext payloads
  • Events/ - Event handlers for WooCommerce hooks
  • Services/ - Business logic for profile and session management
  • Misc/ - WordPress integration (settings, scripts)

Session Management

The plugin uses a cookie-based session system (hello_session) to track anonymous users and associate their activities with Hellotext profiles.

HTTP Client

Hellotext\Api\Client

The main HTTP client for communicating with the Hellotext API.

Static Methods

request(string $method, string $path, array $data = []): array

Makes an HTTP request to the Hellotext API.

Parameters:

  • $method - HTTP method (GET, POST, PATCH, PUT, DELETE)
  • $path - API endpoint path
  • $data - Request payload

Returns:

[
    'request' => [
        'method' => string,
        'path' => string,
        'data' => array
    ],
    'status' => int,      // HTTP status code
    'body' => array|null  // Decoded JSON response
]

Example:

use Hellotext\Api\Client;
use Hellotext\Constants;

$response = Client::post(Constants::API_ENDPOINT_PROFILES, [
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email' => 'john@example.com'
]);
Convenience Methods
  • get(string $path, ?array $data = null): array
  • post(string $path, ?array $data = null): array
  • patch(string $path, ?array $data = null): array
  • put(string $path, ?array $data = null): array
  • delete(string $path, ?array $data = null): array
with_sufix(string $sufix = ''): self

Creates a client instance with a custom API suffix. Useful for testing.

Example:

$client = Client::with_sufix('/v2');

Event Tracking

Hellotext\Api\Event

Tracks customer activities and sends them to Hellotext.

Constructor

public function __construct(?string $session = null)

Creates a new event tracker. If no session is provided, it attempts to retrieve it from the hello_session cookie.

Methods

track(string $action, array $payload): void

Tracks an event with the given action and payload.

Parameters:

  • $action - Event action name (use constants from Constants::EVENT_*)
  • $payload - Event data

Example:

use Hellotext\Api\Event;
use Hellotext\Constants;

$event = new Event();
$event->track(Constants::EVENT_PRODUCT_VIEWED, [
    'object_parameters' => [
        'reference' => '123',
        'name' => 'Product Name',
        'price' => ['amount' => 2999, 'currency' => 'USD']
    ]
]);

Adapters

Adapters transform WooCommerce objects into Hellotext-compatible payloads.

Hellotext\Adapters\ProductAdapter

Transforms WooCommerce products.

Constructor

public function __construct(int|\WC_Product $product)

Accepts either a product ID or a WC_Product instance.

Methods

get(): array

Returns the adapted product payload.

Returns:

[
    'reference' => int,          // Product ID
    'source' => 'woo',
    'name' => string,
    'categories' => string[],
    'price' => [
        'amount' => int,         // Price in cents
        'currency' => string
    ],
    'tags' => string[],
    'image_url' => string,
    'url' => string             // Product permalink
]

Example:

use Hellotext\Adapters\ProductAdapter;

$adapter = new ProductAdapter($product_id);
$payload = $adapter->get();

Hellotext\Adapters\OrderAdapter

Transforms WooCommerce orders.

Constructor

public function __construct(\WC_Order $order)

Methods

get(): array

Returns the adapted order payload.

Returns:

[
    'reference' => int,          // Order ID
    'source' => 'woo',
    'status' => string,          // Order status
    'subtotal' => ['amount' => int, 'currency' => string],
    'total' => ['amount' => int, 'currency' => string],
    'tax' => ['amount' => int, 'currency' => string],
    'shipping' => ['amount' => int, 'currency' => string],
    'discount' => ['amount' => int, 'currency' => string],
    'items' => array[],          // Order items
    'url' => string
]

Hellotext\Adapters\RefundAdapter

Transforms WooCommerce refunds.

Constructor

public function __construct(\WC_Order_Refund $refund)

Methods

get(): array

Returns the adapted refund payload.

Hellotext\Adapters\PriceAdapter

Converts prices to Hellotext format (cents-based).

Constructor

public function __construct(float|string|null $price)

Methods

get(): array

Returns price in cents with currency.

Returns:

[
    'amount' => int,    // Price in cents
    'currency' => string // e.g., 'USD'
]

Services

Hellotext\Services\CreateProfile

Manages Hellotext profile creation and association.

Constructor

public function __construct(?int $user_id, array $billing = [])

Parameters:

  • $user_id - WordPress user ID (null for guest checkout)
  • $billing - Billing data from checkout

Methods

process(): void

Executes the profile creation/association flow:

  1. Checks if profile exists
  2. Creates new profile if needed
  3. Associates profile with session
  4. Updates session metadata

Example:

use Hellotext\Services\CreateProfile;

$service = new CreateProfile($user->ID);
$service->process();

// For guest checkout with billing data
$service = new CreateProfile(null, [
    'first_name' => 'Jane',
    'last_name' => 'Smith',
    'email' => 'jane@example.com',
    'phone' => '+1234567890'
]);
$service->process();

Hellotext\Services\Session

Manages session encryption and cookies.

Static Methods

create(): string

Creates a new session identifier.

Returns: UUID session string

encrypt(string $session): string

Encrypts a session string using AES-256-CBC.

decrypt(string $encrypted_session): string

Decrypts an encrypted session string.

set_cookie(string $session): void

Sets the hello_session cookie with proper expiration and security flags.

Example:

use Hellotext\Services\Session;

$session = Session::create();
Session::set_cookie($session);

// Later, encrypt for storage
$encrypted = Session::encrypt($session);
add_post_meta($order_id, 'hellotext_session', $encrypted);

Constants Reference

Hellotext\Constants

All plugin constants are centralized in this class.

API Configuration

Constants::API_VERSION                  // 'v1'
Constants::API_ENDPOINT_TRACK          // '/v1/track/events'
Constants::API_ENDPOINT_PROFILES       // '/profiles'
Constants::API_ENDPOINT_SESSIONS       // '/sessions'
Constants::API_ENDPOINT_WEBCHATS       // '/v1/wordpress/webchats'
Constants::API_ENDPOINT_INTEGRATIONS_WOO // '/integrations/woo'

Session & Encryption

Constants::ENCRYPTION_METHOD           // 'aes-256-cbc'
Constants::SESSION_COOKIE_NAME        // 'hello_session'

WordPress Options

Constants::OPTION_BUSINESS_ID         // 'hellotext_business_id'
Constants::OPTION_ACCESS_TOKEN        // 'hellotext_access_token'
Constants::OPTION_WEBCHAT_ID          // 'hellotext_webchat_id'
Constants::OPTION_WEBCHAT_PLACEMENT   // 'hellotext_webchat_placement'
Constants::OPTION_WEBCHAT_BEHAVIOUR   // 'hellotext_webchat_behaviour'

User Meta Keys

Constants::META_PROFILE_ID            // 'hellotext_profile_id'
Constants::META_SESSION               // 'hellotext_session'

Event Names

Constants::EVENT_ORDER_PLACED         // 'order.placed'
Constants::EVENT_ORDER_CONFIRMED      // 'order.confirmed'
Constants::EVENT_ORDER_CANCELLED      // 'order.cancelled'
Constants::EVENT_ORDER_DELIVERED      // 'order.delivered'
Constants::EVENT_PRODUCT_PURCHASED    // 'product.purchased'
Constants::EVENT_PRODUCT_VIEWED       // 'product.viewed'
Constants::EVENT_CART_ADDED           // 'cart.added'
Constants::EVENT_CART_REMOVED         // 'cart.removed'
Constants::EVENT_REFUND_RECEIVED      // 'refund.received'
Constants::EVENT_COUPON_REDEEMED      // 'coupon.redeemed'

WordPress Hooks

The plugin registers these WooCommerce and WordPress hooks:

Hook Handler Purpose
woocommerce_after_single_product hellotext_product_viewed Track product.viewed
woocommerce_after_cart hellotext_trigger_cart_updated Compare current and previous cart state
woocommerce_add_to_cart hellotext_trigger_cart_updated Compare current and previous cart state
woocommerce_cart_item_removed hellotext_trigger_cart_updated Compare current and previous cart state
woocommerce_after_cart_item_quantity_update hellotext_trigger_cart_updated Compare current and previous cart state
woocommerce_applied_coupon hellotext_coupon_redeemed Track valid coupon.redeemed events
woocommerce_after_order_details hellotext_order_placed Track order.placed and persist encrypted session metadata on the order; render-based hook, so duplicate prevention is required
woocommerce_order_status_changed track_order_status Track order.confirmed, order.cancelled, and order.delivered
woocommerce_order_refunded hellotext_refund_created Track refund.received
user_register hellotext_user_registered Track customer registration/profile flow
hellotext_woocommerce_cart_updated hellotext_cart_updated Track cart.added and cart.removed
update_option custom_field_updated Recreate integration after Business ID changes
admin_init hellotext_settings_init Register plugin settings
admin_head / wp_head hellotext_script Inject frontend/admin scripts

WooCommerce Compatibility

Compatibility posture as of 2026-06-11. See WooCommerce Compatibility and API Audit for the full hook/API audit, HPOS assessment, compatibility matrix, and release recommendations.

Area Status Notes
WooCommerce order metadata HPOS-aligned metadata access Uses WC_Order metadata CRUD for Hellotext session metadata.
Order status and refund events HPOS-aligned metadata access Reads session metadata from the order object instead of get_post_meta().
Product, cart, coupon events Public hook/API usage Uses WooCommerce hooks and objects, not order storage internals.
Automated tests Mock-backed unit coverage Event tests cover outbound payloads without real WordPress/WooCommerce runtime or HPOS datastore coverage.
Runtime verification Required before declaration Test with HPOS enabled and disabled in a real WooCommerce site before declaring formal compatibility in the plugin header/runtime.

Do not add a formal HPOS compatibility declaration until the release candidate has passed runtime checks on WooCommerce with HPOS enabled and disabled.

Actions

hellotext_create_profile

Triggers profile creation/association.

Parameters:

  • $payload - Either user ID (int) or billing data (array)

Usage:

// For logged-in user
do_action('hellotext_create_profile', $user_id);

// For guest with billing data
do_action('hellotext_create_profile', [
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email' => 'john@example.com',
    'phone' => '+1234567890'
]);

WooCommerce Integration Hooks

The plugin automatically hooks into these WooCommerce actions:

  • woocommerce_after_order_details - Track order placement
  • woocommerce_order_status_changed - Track order status updates
  • woocommerce_order_refunded - Track refunds
  • woocommerce_add_to_cart - Track cart additions
  • woocommerce_cart_item_removed - Track cart removals
  • woocommerce_applied_coupon - Track coupon usage
  • wp_footer - Inject tracking scripts and webchat

Testing

For testing information, see DEVELOPMENT.md.

Environment Variables

The plugin respects the following environment variables:

  • APP_ENV - Environment mode: production, development, or test
  • HELLOTEXT_API_URL - Override API URL (development only)

Example (.htaccess):

SetEnv APP_ENV development
SetEnv HELLOTEXT_API_URL https://api-dev.hellotext.com

Error Handling

Most methods that interact with external APIs will throw exceptions on failure. Always wrap critical API calls in try-catch blocks:

try {
    $adapter = new ProductAdapter($product_id);
    $payload = $adapter->get();
} catch (\Exception $e) {
    error_log('Hellotext: Failed to adapt product - ' . $e->getMessage());
}

Security

Authentication

All API requests include an Authorization: Bearer header with either:

  • Business ID for event tracking
  • Access Token for profile/session management

Session Encryption

Sessions are encrypted using AES-256-CBC before storage in the database. The encryption key is derived from WordPress security keys.

Data Sanitization

All user input is sanitized using WordPress functions (sanitize_text_field(), etc.) before processing.

License

This plugin is licensed under GPL v2. See LICENSE for details.