cuongcds / octivo-php

v0.1.1 2026-09-17 16:36 UTC

Requires

• php: >=8.0
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^9.6

MIT

Published on Packagist.org on 2026-09-17 16:42 UTC

README

PHP SDK for the Octivo CRM API. Lead capture is the first resource covered — a public, unauthenticated endpoint used by landing pages/widgets to create a row in crm_leads, scoped to a channel via its public source_id. More Octivo CRM resources will be added to this SDK over time.

Install

composer require cuongcds/octivo-php

Usage

use Octivo\Crm\OctivoClient;
use Octivo\Crm\LeadRequest;
use Octivo\Crm\Exception\ValidationException;
use Octivo\Crm\Exception\ApiException;

// baseUrl defaults to https://octivo.cloud; pass one to target a different environment.
$client = new OctivoClient('your-channel-source-id');

$request = LeadRequest::create()
    ->withName('Nguyen Van A')
    ->withEmail('[e-mail]')
    ->withPhone('0912345678')
    ->withMeta('usecase', 'chatbot_sales')
    ->withMeta('utm_source', 'facebook-ads')
    ->withMeta('utm_campaign', 'spring-promo');

try {
    $result = $client->createLead($request);
    // $result->id, $result->success
} catch (ValidationException $e) {
    // neither email nor phone was provided
} catch (ApiException $e) {
    // API rejected the request: $e->getStatusCode(), $e->getMessage(), $e->getResponseBody()
}

At least one of email/phone must be provided; name falls back server-side to the email/phone when omitted. Any extra field added via withMeta()/withMetaFields() is stored server-side in the lead's meta JSON column.

Optional reCAPTCHA v3

If the target server has recaptcha_secret_key configured, pass a client-generated token (action create_lead) via withRecaptchaToken(). It's ignored otherwise.

Custom HTTP transport

The client uses a cURL-based transport by default. Swap it by implementing Octivo\Crm\Http\HttpClientInterface and passing it as the third constructor argument to OctivoClient.

Examples

Runnable scripts are in examples/:

• examples/create-lead.php — full example with name, email, phone, and extra meta fields.
• examples/create-lead-minimal.php — minimal example with only a phone number.
• examples/create-lead-with-recaptcha.php — passing a client-generated reCAPTCHA v3 token via withRecaptchaToken().

composer install
OCTIVO_SOURCE_ID=your-channel-source-id php examples/create-lead.php

Errors

• Octivo\Crm\Exception\ValidationException — thrown client-side before any request is sent (missing email and phone).
• Octivo\Crm\Exception\ApiException — thrown when the API responds with an error (invalid source_id, invalid phone/email, reCAPTCHA failure). Carries getStatusCode() and getResponseBody().
• Octivo\Crm\Exception\OctivoException — base class, also thrown on transport failures (network error, timeout).

Reference

See docs/crm-lead-api.postman_collection.json for the underlying HTTP API this SDK wraps.