PHPackages                             helpscout/api-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. helpscout/api-laravel

ActiveLibrary[API Development](/categories/api)

helpscout/api-laravel
=====================

Service provider and facade to integrate the Help Scout Mailbox API 2.0 with Laravel and Lumen

2.1.3(1y ago)8490.0k—0.9%52MITPHPPHP ^7.3|^8.0

Since Dec 19Pushed 2mo ago27 watchersCompare

[ Source](https://github.com/helpscout/helpscout-api-php-laravel)[ Packagist](https://packagist.org/packages/helpscout/api-laravel)[ Docs](https://www.helpscout.com)[ RSS](/packages/helpscout-api-laravel/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (11)Used By (2)

Help Scout Service Provider and Facade for Laravel and Lumen
============================================================

[](#help-scout-service-provider-and-facade-for-laravel-and-lumen)

[![Build Status](https://camo.githubusercontent.com/370ef9330e68468f0e3b80255581a9ff3a7bb7101823ced4d2413f77aba558c8/68747470733a2f2f7472617669732d63692e6f72672f68656c7073636f75742f68656c7073636f75742d6170692d7068702d6c61726176656c2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/helpscout/helpscout-api-php-laravel)[![Maintainability](https://camo.githubusercontent.com/a9fa169d4ae7f04b1d912cf4f3e27cbb0fcb5fc6954847864c0e1a30af7c8a38/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f31626132613066353330616436353761356165342f6d61696e7461696e6162696c697479)](https://codeclimate.com/repos/5c1a626b8f1a3a02c4002349/maintainability)

This package contains a service provider and facade for use with [Laravel](http://laravel.com) and [Lumen](http://lumen.laravel.com/).

Installation
------------

[](#installation)

The Help Scout Service Provider can be installed via [Composer](http://getcomposer.org) by requiring the `helpscout/api-laravel` package in your project's `composer.json`.

```
{
    "require": {
        "helpscout/api-laravel": "~2.0"
    }
}
```

Then run a composer update

```
php composer.phar update
```

To use the Help Scout Service Provider, you must register the provider when bootstrapping your application.

### Lumen

[](#lumen)

In Lumen find the `Register Service Providers` in your `bootstrap/app.php` and register the Help Scout Service Provider.

```
    $app->register(HelpScout\Laravel\HelpScoutServiceProvider::class);
```

### Laravel

[](#laravel)

In Laravel find the `providers` key in your `config/app.php` and register the Help Scout Service Provider.

```
    'providers' => [
        // ...
        HelpScout\Laravel\HelpScoutServiceProvider::class,
    ]
```

Find the `aliases` key in your `config/app.php` and add the Help Scout facade alias.

```
    'aliases' => [
        // ...
        'HelpScout' => HelpScout\Laravel\HelpScoutFacade::class,
    ]
```

Configuration
-------------

[](#configuration)

This package offers two ways to configure your client from within the service provider. You can use the `client_credentials` auth type or you can use the `legacy_token` auth type.

### Client Credentials Flow

[](#client-credentials-flow)

The `client_credentials` auth type uses the OAuth2 grant of the same name described on the [Mailbox API 2.O Authentication page](https://developer.helpscout.com/mailbox-api/overview/authentication/#client-credentials-flow).

When using this method, if the API client does not have an `access_token` when a request is make, it will make a pre-flight request to retrieve that token from the Mailbox 2.0 `https://api.helpscout.net/v2/oauth2/token` endpoint. Every subsequent request to the API after that will use the `access_token` retrieved in this first request. See [this page](https://developer.helpscout.com/mailbox-api/overview/authentication/#client-credentials-flow) for more details about the `client_credentials` authorization flow.

To use this grant type, set the following environment variables:

```
HS_AUTH_TYPE=client_credentials
HS_APP_ID=your-app-id
HS_APP_SECRET=your-app-secret

```

### Legacy Credentials Flow

[](#legacy-credentials-flow)

To ease the transition of legacy apps to the new API, the API client uses the [transition service](https://developer.helpscout.com/mailbox-api/migration/transition-service/) to exchange the legacy `clientId` and `apiKey` for an `access_token`.

Just as with the `client_credentials` flow described above, if the API client does not have an `access_token` when attempting an API call, it will make a pre-flight request to the transition service to exchange the legacy credentials for a valid `access_token`.

To use this grant type, set the following environment variables:

```
HS_AUTH_TYPE=legacy_credentials
HS_CLIENT_ID=your-client-id
HS_API_KEY=your-api-key

```

### Changing credentials between requests

[](#changing-credentials-between-requests)

If you do not provide credentials when the client is created, you must provide either an `access_token` or valid credentials for one of the two auth types described above. You can do this with a concrete instance of the client like so:

```
$client = app('helpscout');
$client->useClientCredentials($appId, $appSecret);

$webhooks = $client->webhooks()->list();
```

To customize the configuration file, publish the package configuration using Artisan.

```
php artisan vendor:publish  --provider="HelpScout\Laravel\HelpScoutServiceProvider"

// or
php artisan vendor:publish  --tag="helpscout"
```

The settings can be found in the generated `config/helpscout.php` configuration file.

Usage
-----

[](#usage)

This service provider offers several ways to use the API Client from within your app. You can resolve the client instance from the container by using the `helpscout` alias, by specifying the `Helpscout\Api\ApiClient` class name, or you may type-hint the client in a class constructor or a method signature. If you configured the client with credentials as described above, there is no further configuration needed.

Use the full class name to get the client from the container.

```
$client = app(\HelpScout\Api\ApiClient::class);
$webhooks = $client->webhooks()->list();
```

Use the alias to get the client from the container.

```
$client = app('helpscout');
$webhooks = $client->webhooks()->list();
```

Or, type-hint the client in a constructor or method signature.

```
use HelpScout\Api\ApiClient;
use HelpScout\Api\Entity\PagedCollection;

class Foo
{
    private $api;

    public function __construct(ApiClient $api)
    {
        $this->api = $api;
    }

    public function getWebhooks(): PagedCollection
    {
        return $this->api->webhooks()->list();
    }
}
```

Additionally, you can request and resolve specific API Endpoints from the container in a similar fashion. For a list of the endpoints and their aliases, see the `ApiClient::AVAILABLE_ENDPOINTS` in the API client library. In the same fashion as the `ApiClient` class, the container will return a fully-configured endpoint that is ready for use as long as you specified the auth type and appropriate credentials in your `config/helpscout.php` file.

```
use HelpScout\Api\Webhooks\WebhooksEndpoint;
use HelpScout\Api\Entity\PagedCollection;

class Foo
{
    private $endpoint;

    public function __construct(WebhooksEndpoint $endpoint)
    {
        $this->endpoint = $endpoint;
    }

    public function getHsWebhooks(): PagedCollection
    {
        return $this->endpoint->list();
    }
}

// usage
$foo = app(Foo::class);
$webhooks = $foo->getHsWebhooks();

// using the endpoints registered alias...
$webhookEndpoint = app('hs.webhooks');
$webhooks = $webhookEndpoint->list();
```

If the `HelpScout` facade is registered within the `aliases` section of the application configuration, you can also use the following technique.

```
$webhooks = HelpScout::webhooks()->list();
```

Links
-----

[](#links)

- [HelpScout PHP Client on Github](https://github.com/helpscout/helpscout-api-php)
- [Help Scout on Packagist](https://packagist.org/packages/helpscout/)
- [Laravel website](http://laravel.com/)
- [Lumen website](http://lumen.laravel.com/)

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance67

Regular maintenance activity

Popularity44

Moderate usage in the ecosystem

Community24

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 67.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~251 days

Recently: every ~406 days

Total

10

Last Release

445d ago

Major Versions

1.0.3 → 2.0.02020-05-06

PHP version history (3 changes)1.0.0PHP ^7.1

2.0.0PHP ^7.3

2.1.0PHP ^7.3|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/2a560935372705d52a621836e7bee49a6d6576c646bc87feb4c7832baf9e8fc0?d=identicon)[helpscout](/maintainers/helpscout)

---

Top Contributors

[![bkuhl](https://avatars.githubusercontent.com/u/524933?v=4)](https://github.com/bkuhl "bkuhl (31 commits)")[![davidstanley01](https://avatars.githubusercontent.com/u/844070?v=4)](https://github.com/davidstanley01 "davidstanley01 (8 commits)")[![snags88](https://avatars.githubusercontent.com/u/9381931?v=4)](https://github.com/snags88 "snags88 (3 commits)")[![coffeeneer](https://avatars.githubusercontent.com/u/4289336?v=4)](https://github.com/coffeeneer "coffeeneer (2 commits)")[![hsleewis](https://avatars.githubusercontent.com/u/867824?v=4)](https://github.com/hsleewis "hsleewis (1 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (1 commits)")

---

Tags

apilaravellumensupporthelp deskhelpscout

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/helpscout-api-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/helpscout-api-laravel/health.svg)](https://phpackages.com/packages/helpscout-api-laravel)
```

###  Alternatives

[spatie/laravel-fractal

An easy to use Fractal integration for Laravel applications

1.9k15.1M99](/packages/spatie-laravel-fractal)[mollie/laravel-mollie

Mollie API client wrapper for Laravel & Mollie Connect provider for Laravel Socialite

3624.1M28](/packages/mollie-laravel-mollie)[helpscout/api

Help Scout API v2 Client

1002.1M4](/packages/helpscout-api)[mpclarkson/freshdesk-laravel

Laravel package for the Freshdesk API (v2)

1767.3k](/packages/mpclarkson-freshdesk-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)