kevinwbh/chatrace-php-sdk

SDK for Chatrace Services

v1.0 2026-07-20 20:36 UTC

Requires

• php: ^8.0
• guzzlehttp/guzzle: ^7

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

• Kevin William Baylón Huerta

Published on Packagist.org on 2026-07-20 20:38 UTC

README

PHP SDK for the Chatrace API.

🇪🇸 Leer en español

Requirements

• PHP ^8.0
• guzzlehttp/guzzle ^7

Installation

composer require kevinwbh/chatrace-php-sdk

Quick start

require __DIR__ . '/vendor/autoload.php';

use Kevinwbh\Chatrace\Chatrace;

$chatrace = new Chatrace('YOUR_API_KEY');

$contact = $chatrace->contacts()->create([
    'first_name' => 'John',
    'last_name'  => 'Doe',
    'phone'      => '[phone]',
    'email'      => '[e-mail]',
]);

$chatrace->contacts()->sendText($contact['id'], 'Hi, this is a message from Chatrace!', 'whatsapp');

Contacts endpoints

All methods on $chatrace->contacts() (an instance of Kevinwbh\Chatrace\Endpoints\Contacts) return a plain array decoded from the API's JSON response, or throw an exception on failure.

Method	API endpoint	Description
getById(string $id)	GET /contacts/{id}	Get a contact by id.
findByCustomField(string $fieldId, string $value)	GET /contacts/find_by_custom_field	Find contacts by a custom field value. $fieldId accepts 'phone', 'email', or any custom field id. Returns an array of matches (empty if none).
getByPhone(string $phone)	—	Shortcut over findByCustomField('phone', ...). Returns the first match or throws ApiException if none found.
getByEmail(string $email)	—	Shortcut over findByCustomField('email', ...). Returns the first match or throws ApiException if none found.
create(array $data)	POST /contacts	Create a new contact (phone, email, first_name, last_name, gender, actions).
getTags(string $id)	GET /contacts/{id}/tags	List tags assigned to a contact.
addTag(string $id, string $tagId)	POST /contacts/{id}/tags/{tagId}	Add a tag to a contact.
removeTag(string $id, string $tagId)	DELETE /contacts/{id}/tags/{tagId}	Remove a tag from a contact.
getCustomFields($id)	GET /contacts/{id}/custom_fields	List all custom field values for a contact.
getCustomFieldValue($id, $customFieldId)	GET /contacts/{id}/custom_fields/{customFieldId}	Get a single custom field value.
setCustomField($id, $customFieldId, $value)	POST /contacts/{id}/custom_fields/{customFieldId}	Set a custom field value.
removeCustomField($id, $customFieldId)	DELETE /contacts/{id}/custom_fields/{customFieldId}	Remove a custom field value.
sendFlow($id, $flowId)	POST /contacts/{id}/send/{flowId}	Send a flow to a contact.
sendText($id, string $text, string $channel = 'omnichannel')	POST /contacts/{id}/send/text	Send a text message.
sendFile($id, string $url, string $type, string $channel = 'omnichannel')	POST /contacts/{id}/send/file	Send a file (type: file, image, audio, video).
sendContent($id, array $data)	POST /contacts/{id}/send_content	Run multiple actions / send multiple messages in one call.
saveAiMessages($id, array $messages)	POST /contacts/{id}/ai/save_messages	Save messages to the contact's AI message history.

More endpoint groups (Accounts, Pipelines, Agents, Calendars, Ecommerce, ...) will be added incrementally — see CHANGELOG.md.

Error handling

Every failed request throws an exception from Kevinwbh\Chatrace\Exceptions:

Exception	When
AuthenticationException	HTTP 401 — invalid or expired API key.
ValidationException	HTTP 422 — invalid parameters. Use getErrors() for the field-level errors.
ApiException	Any other HTTP error, or a logically-failed 2xx response. Base class of the two above.

All three expose getStatusCode(): int and getResponseData(): ?array (the raw decoded API response body, when available).

use Kevinwbh\Chatrace\Exceptions\ApiException;
use Kevinwbh\Chatrace\Exceptions\ValidationException;

try {
    $chatrace->contacts()->create(['phone' => 'not-a-real-phone']);
} catch (ValidationException $e) {
    print_r($e->getErrors());
} catch (ApiException $e) {
    echo $e->getStatusCode() . ': ' . $e->getMessage();
}

Custom HTTP client / options

Chatrace and Http\Client accept an optional Guzzle client and a request options array, useful for testing (MockHandler) or overriding base_uri, timeout, proxies, etc.:

use GuzzleHttp\Client as Guzzle;
use Kevinwbh\Chatrace\Chatrace;

$chatrace = new Chatrace('YOUR_API_KEY', null, ['timeout' => 5]);

// or inject your own Guzzle instance entirely (e.g. wired to a MockHandler in tests)
$chatrace = new Chatrace('YOUR_API_KEY', new Guzzle([...]));

Testing

composer install
composer test

License

MIT