Download the PHP package helpscout/api without Composer

Help Scout API PHP Client

This is the official Help Scout PHP client. This client contains methods for easily interacting with the Help Scout Mailbox API.

Table of Contents

• Installation
• Usage
  • Examples
  • Authentication
  • Customers
    • Email
    • Address
    • Phone Number
    • Social Profile
    • Chat Handles
    • Website
    • Properties
  • Mailboxes
  • Conversations
    • Threads
    • Attachments
  • Chats
  • Tags
  • Teams
  • Users
  • Reports
  • Webhooks
  • Workflows
• Error Handling
  • Validation
• Pagination
• Testing
• Getting Support

Installation

The recommended way to install the client is by using Composer.

For Laravel projects, check out helpscout/api-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:

Authentication

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

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.

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:

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

Authorization Code Flow

Because the authorization code 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.

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.

Examples

This README contains a lot of examples, but there are more examples for you to experiment with in ./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.

Get customers.

Get customers with a filter.

As described in the API docs the customer list can be filtered by a variety of fields. The CustomerFields class provides a simple interface to set filter values. For example:

Create a customer.

Update a customer.

Email

Create a customer email.

Update a customer email.

Delete a customer email.

Address

Create a customer address.

Update a customer address.

Delete a customer address.

Phone number

Create a customer phone.

Update a customer phone.

Delete a customer phone.

Chat Handles

Create a customer chat.

Update a customer chat.

Delete a customer chat.

Social profile

Create a customer social profile.

Update a customer social profile.

Delete a customer social profile.

Website

Create a customer website.

Update a customer website.

Delete a customer website.

Properties

Get a customer's properties and their values.

Update a customer's properties.

Mailboxes

Get a mailbox.

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:

Get mailboxes.

Get mailboxes with pre-loaded sub-entities.

Conversations

Get a conversation.

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

Get conversations.

Get conversations with pre-loaded sub-entities.

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

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

Update the custom fields on a conversation:

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

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

Delete a conversation:

Update an existing conversation:

Threads

Chat Threads

Create new Chat threads for a conversation.

Customer Threads

Create new Customer threads for a conversation.

Note Threads

Create new Note threads for a conversation.

Phone Threads

Create new Phone threads for a conversation.

Reply Threads

Create new Reply threads for a conversation.

Get threads for a conversation.

Attachments

Get an attachment.

Create an attachment:

Delete an attachment:

Chats

Get a chat

List the chat events

Tags

List the tags

Teams

List the teams

List the members of a team

Users

Get a user.

Get users.

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

Reports

When running reports using the SDK, refer to the developer docs for the exact endpoint, parameters, and response formats. While most of the endpoints in this SDK are little more than pass-through methods to call the API, there are a few conveniences.

First, for the start, end, previousStart, and previousEnd parameters, you may pass a formatted date-time string or any object implementing the \DateTimeInterface as the parameter. The client will automatically convert these objects to the proper format.

For those parameters that accept multiple values (mailboxes, tags, types, and folders), you may pass an array of values and let the client convert them to the proper format. You may also pass a single value (or a comma-separated list of values) if you like.

To run the report, use the runReport method available on the ApiClient instance. Pass the class path of the report class you'd like to use as the first argument and the array of report parameters as the second argument. Be sure the keys in the parameter array match the URL params specified in the docs. The client will convert the JSON response returned by the API into an array.

Webhooks

Get a webhook.

List webhooks.

Create a webhook.

The default state for a newly-created webhook is enabled.

Update a webhook

This operation replaces the entire webhook entity, so you must provide the secret again. Once updated, the webhook will be in the enabled state again.

Delete a webhook.

Processing an incoming webhook

You can also use the SDK to easily process an incoming webhook. Signature validation will happen when creating the new object, so no need to check if it is valid or not. If the signatures do not match, the constructor of the IncomingWebhook object will throw an InvalidSignatureException to let you know something is wrong.

Once you have the incoming webhook object, you can check the type of payload (customer, conversation, or test) as well as retrieve the data (see example). If a customer or conversation, you can retrieve the model associated. Otherwise, you can get the payload as either an associative array or standard class object.

Workflows

Fetch a paginated list of all workflows.

Run a manual workflow on a list of conversations.

Change a workflow status to either "active" or "inactive"

Error handling

Any exception thrown by the client directly will implement HelpScout\Api\Exception and HTTP errors will result in Http\Client\Exception\RequestException being thrown.

If an OAuth2 token is not provided or invalid then a HelpScout\Api\Exception\AuthenticationException is thrown.

Validation

You'll encounter a ValidationErrorException if there are any validation errors with the request you submitted to the API. Here's a quick example on how to use that exception:

Pagination

When fetching a collection of entities the client will return an instance of HelpScout\Api\Entity\Collection. If the end point supports pagination then it will return an instance of HelpScout\Api\Entity\PagedCollection.

Testing

The SDK comes with a handy mock method on the ApiClient class. To use this, pass in the name of the endpoint you want to mock. You'll get a \Mockery\MockInterface object back. Once you set the mock, any subsequent calls to that endpoint will return the mocked object.

Once you've mocked an endpoint, you may want to clear it later on. To do this, you can use the clearMock($endpoint) method on the ApiClient.

Getting Support

Please open an issue for any SDK related problems or feature requests. For any issues that may involve sensitive customer or account data, please reach out to us via email at [email protected].