adambalan/helpscout-api

Helpscout API Library (PHP 7.1+)

The core purpose of this library is to manage Helpscout API. I built this as a separate tool for my company to be able to backup our documentation.

ATTN!!

I am currently flushing this out with more endpoints as time goes on to make this more of a useful tool.

Installing

composer install adambalan/helpscout-api

API's

All of the core API endpoint classes live under /Api/Get/.

All of them take a GuzzleHttp client and a ApiKey Contract.

Contracts

The contracts are interfaces which are basic value objects - get/set methods based on what the api at this time needs, the following contracts exist:

• ApiKey
• Article
• Category
• Collection
• Redirect
• site
• ArticlePostBody
• CategoryPostBody
• CollectionPostBody
• RequestPool

These are implemented and then passed to the Endpoint class methods where needed.

For further documentation see the generated documentation.

Examples

The core thing to understand is that the structure and flow goes like this:

• Get all collections
• Get all categories (Based on collection ID)
• Get all articles (Based on category ID)
  • Get single article based on article id's returned from above.

You can also get Articles through the collections:

• Get all Collections
• Get all Articles (Based on Collection ID)
  • Get Single Article based on Article ID from above.

Articles Will return a list of articles, unfortunately you have to use the article ID to get specific information like text from a single article.

Get All Articles

To get all articles you must have a category id, which you can get from getting all categories, which in turn, requires a collection id.

use HelpscoutApi\Api\Get\Articles;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\Category; // We will pretend we implemented this as CategoryValue;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$categoryValue = new CategoryValue('12345667');

$articles = new Article($client, $apiKey);
$articleJSON = $articles->getAll($categoryValue);

// Do something with $articleJSON.

Get All Articles with params

use HelpscoutApi\Api\Get\Articles;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\Category; // We will pretend we implemented this as CategoryValue;
use HelpscoutApi\Params\Article as ArticleParams;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$categoryValue = new CategoryValue('12345667');

// You can set the url params that come back as `?sort=number&status=number`:

$articleParams = new ArticleParams();
$articleParams->sort('number');
$articleParams->status('name');

$articles = new Article($client, $apiKey);

// We then pass $articleParams
$articleJSON = $articles->getAll($categoryValue, $articleParams);

// Do something with $articleJSON.

Post an article

The same concept will work for posting a category or collection, just swap out the ArticlePostBody for the Category or Collection post body contract.

use HelpscoutApi\Api\Post\Article;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\ArticlePostBody; // We will pretend we implemented this as ArticlePostBody;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articlePostBody->collectionID('123');
$articlePostBody->name('article name');
$articlePostBody->text('something');

$article = new Article($client, $apiKey);
$article->create($articlePostBodyValue);

// This will return a response, see https://developer.helpscout.com/docs-api/articles/create/
// for more information.

Delete an article

These concepts apply to categories and collections as well.

use HelpscoutApi\Api\Delete\Article;
use HelpscoutApi\Contracts\ApiKey;
use HelpscoutApi\Contracts\Article as ArticleContract;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articleContract = new ArticleContract('1234');
$article         = new Article($client, $apiKey);

$article->delete($articleContract); // Returns the \GuzzleHttp\Psr7\Response

You can view the tests to get a better understanding of how you would use the endpoints.

Update an article

ATTN!!

You can only update articles at this time.

Updating an article works the same way as creating an article with one minor difference, we pass an ArticlePutBody contract.

This contract contains three methods: id(string $articleId), getId(): string, articlePostBody(ArticlePostBody $articlePostBody)

There is one final method, the createPutBody() which is used to create the actual JSON for the request.

Much like the create, you can update a single, async and return a update request, all of which use PUT requests.

use HelpscoutApi\Api\Post\Article;
use HelpscoutApi\Contracts\ApiKey; // We will pretend we implemented this as ApiKeyValue;
use HelpscoutApi\Contracts\ArticlePostBody; // We will pretend we implemented this as ArticlePostBody;
use HelpscoutApi\Contracts\ArticlePutBody; // We will pretend we implemented this as ArticlePutBody;
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://docsapi.helpscout.net/v1/',
]);

$apiKey = new ApiKeyValue('xxxxxxxxxx');

$articlePostBody->collectionID('123');
$articlePostBody->name('article name');
$articlePostBody->text('something');

$articlePutBody->id('articleId');
$articlePutBody->articlePostBody($articlePostBody);

$article = new Article($client, $apiKey);
$article->update($articlePutBody);

// This will return a response, see https://developer.helpscout.com/docs-api/articles/update/
// for more information.

Request Async and Pools

ATTN!!

Currently this only works with articles and categories

When you want to do things in an async matter or you have an undefined amount of entities to post to a particular endpoint you can use the createAsync and createRequest. One will return a Promise and the other is intended to be used with Guzzels Pools;

Lets look at how you might do that.

createAsync()

use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\RequestException;

// ... Set up your article info to be posted, see previous examples.

$promise = $article->createAsync($articlePostBodyValue);
$promise->then(function(ResponseInterface $ri) {
  echo $ri->getStatusCode();
},
function(RequestException $e) {
  echo $e->getMessage();
});

As we can see createAsync() simply returns a promise.

createRequest()

Create request is meant to be used with the contract RequestPool to set the requests, as this method only returns a request object. You then set the requests to the pool array and then pass the RequestPool instance to the Pool class method pool, along with the client instance to the instantiation.

From there you call pool with a rejected call back function and an optional success callback function.

use HelpscoutApi\Contracts\RequestPool;
use HelpscoutApi\Api\Pool;

// ... Set up your article info to be posted, see previous examples.

$request = $article->createRequest($articlePostBodyValue);

$requestPool->pushRequest($request); // Push the request
$request->setConcurrency(1); // How many should we do before we wait for them all to complete?

$pool = new Pool($client);
$pool->pool($requestPool, function($reason, $index){ ... }, function($response){ ... });

// The first call back function is called when we are rejected.
// The second is optional and only called on success.

ATTN!!

If concurrency is not set or is less then or equal to 0, we will set the default to 20.

Dealing with responses

Helpscout doesn't return a response body with JSON about created objects, instead a lot of the information you might want are in the header, on piece of information that is important, at least when you create new resources, is the location and the id of the resource.

use HelpscoutApi\Request\Request;

// See above for creating an article:

$response = $article->create($articlePostBodyValue);
$responseObject = new Request($response);

$responseObject->getLocation();  // Returns the location of the created object.
$responseObject->getContents();  // Returns the contents of the returned body.

See class docs for Response