Laravel Intercom

#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

#License

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