KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #ai #dsh-plugin #ai-agent #mcp #deepseek-harness #windows

helpscout-api-php

★ 102 Open GitHub ↗

PHP Wrapper for the Help Scout API

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Help Scout API PHP Client

[![Build Status](https://travis-ci.org/helpscout/helpscout-api-php.svg?branch=master)](https://travis-ci.com/helpscout/helpscout-api-php)
[![Maintainability](https://api.codeclimate.com/v1/badges/73d6bfd2fddd8483f8c8/maintainability)](https://codeclimate.com/repos/5c19426f34451a02c4000cab/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/73d6bfd2fddd8483f8c8/test_coverage)](https://codeclimate.com/repos/5c19426f34451a02c4000cab/test_coverage)

This is the official Help Scout PHP client. This client contains methods for easily interacting with the [Help Scout Mailbox API](http://developer.helpscout.net/help-desk-api-v2/).

| SDK Version | PHP Version | Branch   | Documentation                                                         |
|-------------|-------------|----------|-----------------------------------------------------------------------|
| `3.*`       | >= 7.3      | `master` | This page                                                             |
| `2.*`       | >= 7.1      | `v2`     | [`v2` branch](https://github.com/helpscout/helpscout-api-php/tree/v2) |

## Table of Contents

* [Installation](#installation)
 * [Usage](#usage)
   * [Examples](#examples)
   * [Authentication](#authentication)
   * [Customers](#customers)
     * [Email](#email)
     * [Address](#address)
     * [Phone Number](#phone-number)
     * [Social Profile](#social-profile)
     * [Chat Handles](#chat-handles)
     * [Website](#website)
     * [Properties](#properties)
   * [Mailboxes](#mailboxes)
   * [Conversations](#conversations)
     * [Threads](#threads)
       * [Attachments](#attachments)
   * [Chats](#chats)
   * [Tags](#tags)
   * [Teams](#teams)
   * [Users](#users)
   * [Reports](#reports)
   * [Webhooks](#webhooks)
   * [Workflows](#workflows)
 * [Error Handling](#error-handling)
   * [Validation](#validation)
 * [Pagination](#pagination)
 * [Testing](#testing)
 * [Getting Support](#getting-support)

## Installation

The recommended way to install the client is by using [Composer](https://getcomposer.org/doc/00-intro.md).

```bash
composer require helpscout/api "^3.0"
```

For Laravel projects, check out [`helpscout/api-laravel`](https://github.com/helpscout/helpscout-api-php-laravel)

## Usage

You should always use Composer's autoloader in your application to autoload classes. All examples below assume you've already included this in your code:

```php
require_once 'vendor/autoload.php';
```

### Authentication

Use the factory to create a client. Once created, you can set the various credentials to make requests.

```php
use HelpScout\Api\ApiClientFactory;

$client = ApiClientFactory::createClient();

// Set Client credentials if using that grant type.  Using this approach will lazily fetch an access token on-demand
// when needed.
$client->useClientCredentials($appId, $appSecret);

// Set Access token directly if you have it
$client->setAccessToken('abc123');

// Use a refresh token to get a new access token
$client->useRefreshToken($appId, $appSecret, $refreshToken);
```

**Note**

All credential types will trigger a pre-flight request to get an access token (HTTP 'POST' request). To avoid this, set the access token on the client before making a request using the `setAccessToken` method on the client.
```php
$client = ApiClientFactory::createClient();
$client->setAccessToken('asdfasdf');
```
The access token will always be used if available, regardless of whether you have other credentials set or not.

### Automatically Refreshing Expired Tokens

When a request fails due to an authentication error, the SDK can automatically try to obtain a new refresh token and then retry the given request automatically.  To enable this, you can provide a callback when creating the ApiClient which can be used to persist the token for other processes to use depending on your needs:

```php
$client = ApiClientFactory::createClient([], function (Authenticator $authenticator) {
    // This $authenticator contains the refreshed token
    echo 'New token: '.$authenticator->accessToken().PHP_EOL;
});
```

The callback can also be any class instance that implements `HelpScout\Api\Http\Auth\HandlesTokenRefreshes`:

```php
use HelpScout\Api\Http\Auth\HandlesTokenRefreshes;
use HelpScout\Api\Http\Authenticator;

$callback = new class implements HandlesTokenRefreshes {
    public function whenTokenRefreshed(Authenticator $authenticator)
    {
        // @todo Persist the token
    }
};
$client = ApiClientFactory::createClient([], $callback);
```

### Authorization Code Flow

Because the [authorization code](https://developer.helpscout.com/mailbox-api/overview/authentication/#authorization-code-flow) is only good for a single use, you'll need to exchange the code for an access token and refresh token prior to making additional api calls.  You'll also need to persist the tokens for reuse later.

```php
$client = ApiClientFactory::createClient();
$client = $client->swapAuthorizationCodeForReusableTokens(
    $appId,
    $appSecret,
    $authorizationCode
);

$credentials = $client->getAuthenticator()->getTokens();

echo $credentials['access_token'].PHP_EOL;
echo $credentials['refresh_token'].PHP_EOL;
echo $credentials['expires_in'].PHP_EOL;
```

In addition to providing the access/refresh tokens this will set the current auth to use those tokens, so you can freely make subsequent requests without reinitializing the client.

```
// uses the one-time authorization code for auth
$client = $client->swapAuthorizationCodeForReusableTokens(
    $appId,
    $appSecret,
    $authorizationCode
);

// uses access/refresh tokens for auth
$client->users()->list();
```

## Examples

This README contains a lot of examples, but there are more examples for you to experiment with in [`./examples`](https://github.com/helpscout/helpscout-api-php/tree/master/examples).

## Customers

Get a customer.  Whenever getting a customer, all it's entities (email addresses, phone numbers, social profiles, etc.) come preloaded in the same request.

```php
$customer = $client->customers()->get($customerId);
```

Get customers.

```php
$customers = $client->customers()->list();
```

Get customers with a filter.

As described in the API docs the [customer list can be filtered](http://developer.helpscout.net/help-desk-api-v2/customers/list) by a variety of fields. The `CustomerFields` class
provides a simple interface to set filter values. For example:

```php
use HelpScout\Api\Customers\CustomerFilters;

$filter = (new CustomerFilters())
    ->byFirstName('Tom')
    ->byLastName('Graham');

$customers = $client->customers()->list($filter);
```

Create a customer.

```php
use HelpScout\Api\Customers\Customer;

$customer = new Customer();
$customer->setFirstName('Bob');
// ...

try {
    $customerId = $client->customers()->create($customer);
} catch (\HelpScout\Api\Exception\ValidationErrorException $e) {
    var_dump($e->getError()->getErrors());
}
```

Update a customer.

```php
// ...
$customer->setFirstName('Bob');

$client->customers()->update($customer);
```

### Email

Create a customer email.

```php
use HelpScout\Api\Customers\Entry\Email;

$email = new Email();
$email->setValue('lucy@helpscout.com');
$email->setType('work');
// ...

$client->customerEntry()->createEmail($customerId, $email);
```

Update a customer email.

```php
// ...
$email->setType('home');

$client->customerEntry()->updateEmail($customerId, $email);
```

Delete a customer email.

```php
$client->customerEntry()->deleteEmail($customerId, $emailId);
```

### Address

Create a customer address.

```php
use HelpScout\Api\Customers\Entry\Address;

$address = new Address();
$address->setCity('Boston');
// ...

$client->customerEntry()->createAddress($customerId, $address);
```

Update a customer address.

```php
// ...
$address->setCity('Boston');

$client->customerEntry()->updateAddress($customerId, $address);
```

Delete a customer address.

```php
$client->customerEntry()->deleteAddress($customerId);
```

### Phone number

Create a customer phone.

```php
use HelpScout\Api\Customers\Entry\Phone;

$phone = new Phone();
$phone->setValue('123456789');
$phone->setType('work');
// ...

$client->customerEntry()->createPhone($customerId, $phone);
```

Update a customer phone.

```php
// ...
$phone->setType('home');

$client->customerEntry()->updatePhone($customerId, $phone);
```

Delete a customer phone.

```php
$client->customerEntry()->deletePhone($customerId, $phoneId);
```

### Chat Handles

Create a customer chat.

```php
use HelpScout\Api\Customers\Entry\ChatHandle;

$chat = new ChatHandle();
$chat->setValue('1239134812348');
$chat->setType('icq');
// ...

$client->customerEntry()->createChat($customerId, $chat);
```

Update a customer chat.

```php
// ...
$chat->setValue('1230148584583');

$client->customerEntry()->updateChat($customerId, $chat);
```

Delete a customer chat.

```php
$client->customerEntry()->deleteChat($customerId, $chatId);
```

### Social profile

Create a customer social profile.

```php
use HelpScout\Api\Customers\Entry\SocialProfile;

$socialProfile = new SocialProfile();
$socialProfile->setValue('helpscout');
$socialProfile->setType('twitter');
// ...

$client->customerEntry()->createSocialProfile($customerId, $socialProfile);
```

Update a customer social profile.

```php
// ...
$socialProfile->setType('facebook');

$client->customerEntry()->updateSocialProfile($customerId, $socialProfile);
```

Delete a customer social profile.

```php
$client->customerEntry()->deleteSocialProfile($customerId, $socialProfileId);
```

### Website

Create a customer website.

```php
use HelpScout\Api\Customers\Entry\Website;

$website = new Website();
$website->setValue('https://www.helpscout.com');
// ...

$client->customerEntry()->createWebsite($customerId, $website);
```

Update a customer website.

```php
// ...
$website->setValue('https://www.helpscout.net');

$client->customerEntry()->updateWebsite($customerId, $website);
```

Delete a customer website.

```php
$client->customerEntry()->deleteWebsite($customerId, $websiteId);
```

### Properties

Get a customer's properties and their values.

```php
$customer = $client->customers()->get(418048101);
// ...

foreach ($customer->getProperties() as $property) {
    echo $property->getName().': '.$property->getValue().PHP_EOL;
}
```

Update a customer's properties.
```php
use HelpScout\Api\Entity\Collection;
use HelpScout\Api\Entity\Patch;

$operations = new Collection(
    [
        new Patch('remove', 'property-1'),
        new Patch('replace', 'property-2', 'value'),
    ];
);
$client->customerEntry()->updateProperties($customerId, $operations);

```
## Mailboxes

Get a mailbox.

```php
$mailbox = $client->mailboxes()->get($mailboxId);
```

Get a mailbox with pre-loaded sub-entities.

A mailbox entity has two related sub-entities:

* Fields
* Folders

Each of these sub-entities can be pre-loaded when fetching a mailbox to remove the need for multiple method calls. The `MailboxRequest` class is used
to describe which sub-entities should be pre-loaded. For example:

```php
use HelpScout\Api\Mailboxes\MailboxRequest;

$request = (new MailboxRequest)
    ->withFields()
    ->withFolders();

$mailbox = $client->mailboxes()->get($mailboxId, $request);

$fields = $mailbox->getFields();
$folders = $mailbox->getFolders();
```

Get mailboxes.

```php
$mailboxes = $client->mailboxes()->list();
```

Get mailboxes with pre-loaded sub-entities.

```php
use HelpScout\Api\Mailboxes\MailboxRequest;

$request = (new MailboxRequest)
    ->withFields()
    ->withFolders();

$mailboxes = $client->mailboxes()->list($request);
```

## Conversations

Get a conversation.

```php
$conversation = $client->conversations()->get($conversationId);
```

You can easily eager load additional information/relationships for a conversation.  For example:

```php
use HelpScout\Api\Conversations\ConversationRequest;

$request = (new ConversationRequest)
    ->withMailbox()
    ->withPrimaryCustomer()
    ->withCreatedByCustomer()
    ->withCreatedByUser()
    ->withClosedBy()
    ->withThreads()
    ->withAssignee();

$conversation = $client->conversations()->get($conversationId, $request);

$mailbox = $conversation->getMailbox();
$primaryCustomer = $conversation->getCustomer();
```

Get conversations.

```php
$conversations = $client->conversations()->list();
```

Get conversations with pre-loaded sub-entities.

```php
use HelpScout\Api\Conversations\ConversationRequest;

$conversations = $client->conversations()->list(null, $request);
```

Narrow down the list of Conversations based on a set of filters.

```php
use HelpScout\Api\Conversations\ConversationFilters;

$filters = (new ConversationFilters())
    ->inMailbox(1)
    ->inFolder(13)
    ->inStatus('all')
    ->hasTag('testing')
    ->assignedTo(1771)
    ->modifiedSince(new DateTime('2017-05-06T09:04:23+05:00'))
    ->byNumber(42)
    ->sortField('createdAt')
    ->sortOrder('asc')
    ->withQuery('query')
    ->byCustomField(123, 'blue');

$conversations = $client->conversations()->list($filters);

```

You can even combine the filters with the pre-loaded sub-entities in one request

```php
use HelpScout\Api\Conversations\ConversationRequest;
use HelpScout\Api\Conversations\ConversationFilters;

$request = (new ConversationRequest)
    ->withMailbox()
    ->withThreads();

$filters = (new ConversationFilters())
    ->inMailbox(1)
    ->inFolder(13)
    ->byCustomField(123, 'blue');

$conversations = $client->conversations()->list($filters, $request);
```

Update the custom fields on a conversation:

```php
$customField = new CustomField();
$customField->setId(10524);
$customField->setValue(new DateTime('today'));
$client->conversations()->updateCustomFields($conversationId, [$customField]);
```

Create a new conversation, as if the customer sent an email to your mailbox.

```php

// We can specify either the id or email for the Customer
$customer = new Customer();
$customer->addEmail('my-customer@company.com');

$thread = new CustomerThread();
$thread->setCustomer($customer);
$thread->setText('Test');

// You can optionally add tags
$tag = new Tag();
$tag->setName('testing');
$conversation->addTag($tag);

try {
    $conversationId = $client->conversations()->create($conversation);
} catch (ValidationErrorException $e) {
    var_dump($e->getError()->getErrors());
}
```

Here's some other example scenarios where you might create conversations:

<details>
  <summary>Phone conversation, initiated by a Help Scout user</summary>

```
$user = $client->users()->get(31231);

$customer = new Customer();
$customer->setId(193338443);

$thread = new PhoneThread();
$thread->setCustomer($customer);
$thread->setCreatedByUser($user);
$thread->setText('Test');

$conversation = new Conversation();
$conversation->setSubject('Testing the PHP SDK v2: Phone Thread');
$conversation->setStatus('active');
$conversation->setType('phone');
$conversation->setMailboxId(80261);
$conversation->setCustomer($noteCustomer);
$conversation->setCreatedByUser($user);
$conversation->setThreads(new Collection([
    $thread,
]));
```
</details>
<details>
  <summary>Chat conversation, initiated by the Customer</summary>

```
$noteCustomer = new Customer();
$noteCustomer->setId(163315601);
$thread = new ChatThread();
$thread->setCustomer($noteCustomer);
$thread->setText('Test');
$conversation = new Conversation();
$conversation->setSubject('Testing the PHP SDK v2: Chat Thread');
$conversation->setStatus('active');
$conversation->setType('chat');
$conversation->setAssignTo(271315);
$conversation->setMailboxId(138367);
$conversation->setCustomer($noteCustomer);
$conversation->setThreads(new Collection([
    $thread,
]));

// Also adding a tag to this conversation
$tag = new Tag();
$tag->setName('testing');
$conversation->addTag($tag);

$conversationId = $client->conversations()->create($conversation);
```
</details>

Delete a conversation:

```php
$client->conversations()->delete($conversationId);
```

Update an existing conversation:

```php
$client->conversations()->move($conversationId, 18);
$client->conversations()->updateSubject($conversationId, 'Need more help please');
$client->conversations()->updateCustomer($conversationId, 6854);
$client->conversations()->publishDraft($conversationId);
$client->conversations()->updateStatus($conversationId, 'closed');
$client->conversations()->assign($conversationId, 127);
$client->conversations()->unassign($conversationId);
```

### Threads

#### Chat Threads

Create new Chat threads for a conversation.

```php
use HelpScout\Api\Customers\Customer;
use HelpScout\Api\Conversations\Threads\ChatThread;

$thread = new ChatThread();
$customer = new Customer();
$customer->setId(163487350);

$thread->setCustomer($customer);
$thread->setText('Thanks for reaching out to us!');