Laravel Intercom

A PHP/Laravel client for the Intercom REST API. Covers contacts, conversations, messages, companies, tags, articles, admins and events through a simple, typed API built on Laravel's Http client.

Features

• Contacts: list, get, create, update, search, delete, tag/untag
• Conversations: list, get, search, reply, close
• Messages: create (in-app or email, from an admin to a user)
• Companies: list, get, create, update
• Tags: list, create, delete
• Articles: list, get, create, update, delete
• Admins: list, get
• Events: create, list (per user)
• Throws IntercomException (with the original API error body) on any non-2xx response
• Throws InvalidArgumentException before hitting the API when a required field is missing

Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-intercom

Publish the config file:

php artisan vendor:publish --tag=intercom-config

Set your Intercom credentials in .env:

INTERCOM_API_KEY=your-access-token

Find your access token under Settings > Developers in your Intercom workspace.

Configuration

// config/intercom.php
return [
    'api_key' => env('INTERCOM_API_KEY', ''),
    'api_version' => env('INTERCOM_API_VERSION', '2.11'),
    'default_per_page' => env('INTERCOM_DEFAULT_PER_PAGE', 15),
];

Usage

The package is resolved via the Intercom facade or by injecting JeffersonGoncalves\Intercom\Intercom. Each resource is exposed as a method returning a dedicated resource class.

Contacts

use JeffersonGoncalves\Intercom\Facades\Intercom;

// List (cursor-based pagination via per_page / starting_after)
$contacts = Intercom::contacts()->list(['starting_after' => $cursor]);

$contact = Intercom::contacts()->get('507f191e810c19729de860ea');

$contact = Intercom::contacts()->create([
    'email' => 'jane@example.com',
    'name' => 'Jane Doe',
]);

Intercom::contacts()->update($contact['id'], ['name' => 'Jane D.']);

Intercom::contacts()->search('email', 'jane@example.com');

Intercom::contacts()->tag($contact['id'], $tagId);
Intercom::contacts()->untag($contact['id'], $tagId);

Intercom::contacts()->delete($contact['id']);

Conversations

$conversations = Intercom::conversations()->list();

$conversation = Intercom::conversations()->get(1);

Intercom::conversations()->search('state', 'open');

Intercom::conversations()->reply($conversation['id'], 'Thanks for reaching out!', $adminId);

Intercom::conversations()->close($conversation['id'], $adminId, 'Resolved.');

Messages

Intercom::messages()->create(
    body: 'Welcome aboard!',
    adminId: $adminId,
    to: $userId,
);

Companies

$companies = Intercom::companies()->list();

$company = Intercom::companies()->create('company-42', ['name' => 'Acme Inc']);

Intercom::companies()->update($company['id'], ['name' => 'Acme Inc.']);

Tags

$tags = Intercom::tags()->list();

$tag = Intercom::tags()->create('vip');

Intercom::tags()->delete($tag['id']);

Articles

$articles = Intercom::articles()->list();

$article = Intercom::articles()->create(
    title: 'How to reset your password',
    authorId: $adminId,
    state: 'published',
    body: '<p>Steps to reset your password...</p>',
);

Intercom::articles()->update($article['id'], ['title' => 'How to reset your password (updated)']);

Intercom::articles()->delete($article['id']);

Admins and Events

Intercom::admins()->list();
Intercom::admins()->get($adminId);

Intercom::events()->create('invited-friend', $userId, metadata: ['invitee' => 'jane@example.com']);
Intercom::events()->list($userId);

Error handling

Any non-2xx API response throws JeffersonGoncalves\Intercom\Exceptions\IntercomException, which exposes the decoded error body:

use JeffersonGoncalves\Intercom\Exceptions\IntercomException;

try {
    Intercom::contacts()->get('unknown-id');
} catch (IntercomException $e) {
    logger()->error($e->getMessage(), $e->errorBody());
}

Missing required fields (e.g. email on contacts()->create()) throw InvalidArgumentException before any HTTP call is made.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jefferson Gonçalves
• All Contributors

License

The MIT License (MIT). Please see License File for more information.