Help Scout API Essential Guide

What type of API does Help Scout provide?

Based on the search results provided, Help Scout offers a REST API. Here are the key points:

API Type

Help Scout provides a REST API, specifically called the Mailbox API.

Key Features

1. HTTPS-only API with authentication based on API keys.
2. Uses standard HTTP methods like GET, POST, PUT, DELETE.
3. Responses are typically in JSON format.
4. Uses standard HTTP status codes to indicate success or failure of requests.
5. Includes a Correlation-ID header in all responses for tracing interactions.

Authentication

• Authentication is done using API keys associated with Help Scout users.
• The API key is passed via HTTP Basic Authentication in the username field, with a dummy password in the password field.

API Versions

Help Scout offers multiple API versions:

1. Current Mailbox API (v2)
2. Legacy Mailbox API (v1)
3. Docs API

Does the Help Scout API have webhooks?

Yes, the official Help Scout API does have webhooks. Here are the key points about Help Scout's webhook functionality:

Webhook Availability

Help Scout offers webhooks as part of their API. Webhooks allow Help Scout to send notifications to your server when certain events occur in your Help Scout account.

Configuring Webhooks

Webhooks can be configured through the Help Scout user interface. To set them up:

1. Log in to Help Scout
2. Click on Manage > Apps in the top header bar
3. Select the Webhooks app

Available Events

Help Scout offers webhooks for a wide range of events. Some of the main event types you can subscribe to include:

• Conversation events (assigned, created, deleted, merged, moved, status updated, tags updated, custom fields updated)
• Customer events (created, updated, deleted)
• Reply events (customer reply, agent reply)
• Note events (created)
• Rating events (rating received)
• Chat events (created, customer replied)
• Tag events (created, updated, deleted)
• Survey events (response received)

Webhook Payload

When an event occurs, Help Scout will send a POST request to your specified URL with a JSON payload containing details about the event. The payload structure depends on the specific event type.

Security

Help Scout provides a way to verify that webhook requests are genuinely from Help Scout by including a signature in the X-HelpScout-Signature header.

Best Practices

• Use HTTPS for your webhook URL
• Implement signature verification to ensure requests are from Help Scout
• Handle retries, as Help Scout will retry failed webhook deliveries
• Be aware that webhooks can be automatically deactivated if too many events fail to deliver

In summary, Help Scout's webhook system provides a flexible way to integrate real-time updates from Help Scout into your own applications and workflows.

Rate Limits and other limitations

Here are the key points about the API Rate Limits for the Help Scout API:

Rate Limits by Plan

• Standard plan: Up to 200 calls per minute
• Plus plan: Up to 400 calls per minute
• Pro plan: Up to 800 calls per minute

Important Details

• The rate limit applies to all users associated with the same account collectively
• Write requests (POST, PUT, DELETE, PATCH) count as 2 requests toward the rate limit
• When the rate limit is exceeded, a 429 status code is returned

Rate Limit Headers

The API returns the following headers with each response to provide rate limit status:

• X-RateLimit-Limit-Minute: Maximum number of requests allowed per minute
• X-RateLimit-Remaining-Minute: Number of requests remaining in the current rate limit window
• X-RateLimit-Retry-After: Number of seconds to wait before retrying when rate limit is reached

Best Practices

• Monitor the rate limit headers to avoid exceeding limits
• Implement exponential backoff and retry logic when receiving 429 errors
• Consider adding delays or throttling requests if approaching the limit

Summary

The Help Scout API implements rate limiting based on the account's plan level. Monitoring the rate limit headers and implementing proper error handling for 429 responses is important to stay within the limits and ensure smooth API integration.

Latest API Version

Based on the search results, the most recent version of the Help Scout API appears to be version 2.0, also referred to as Mailbox API 2.0. Here are the key points:

Key Points:

1. The current version of the Help Scout Docs API is v1, as mentioned in the endpoints section: "All API requests are made to https://docsapi.helpscout.net/ and all requests are served over HTTPS. The current version is v1."

2. For the Mailbox API, version 2.0 was released and made available to all Help Scout users on paid plans on May 15, 2018.

3. The PHP SDK client was updated to support Mailbox API 2.0.

4. The latest version of the PHP SDK for the Help Scout API is 3.9.0, released on July 31, 2024.

Additional Information:

• The Mailbox API 2.0 went into beta on February 20, 2018.
• There have been several updates and improvements to the API since its release, including new webhook payload versions and documentation updates.
• The API uses OAuth2 for authentication.

It's important to note that while the Docs API is at version 1, the Mailbox API is at version 2.0. When working with Help Scout's APIs, make sure to use the appropriate version for the specific API you're interacting with.

How to get a Help Scout developer account and API Keys?

To get a developer account for Help Scout and create an API integration, you'll need to follow these steps:

1. Set up a Help Scout account

If you don't already have one, you'll need to create a Help Scout account. This is necessary to access the developer features.

2. Generate an API key

Once you have a Help Scout account:

1. Log in to your Help Scout account.
2. Click on the "person" icon in the top right corner, next to the search bar.
3. Click on "Your Profile".
4. In the left menu, click on "Authentication".
5. Select the "API Keys" tab.

Here, you can generate, view, or regenerate your API key. This key will be used to authenticate your API requests.

3. Create an OAuth2 application

To use the API for integrations:

1. Navigate to "Your Profile > My apps".
2. Click on "Create My App".
3. You'll need to provide a redirection URL if you're using the Authorization Code flow.

4. Familiarize yourself with the API documentation

Visit the Help Scout API documentation at https://developer.helpscout.com/. This documentation provides detailed information about:

• Authentication methods
• Available endpoints
• Rate limits
• Error handling
• And more

5. Choose your integration method

Help Scout offers several tools for developers:

• Apps: Display your own content as an internal sidebar application in the Mailbox
• Beacon: Live chat, help docs, and a customer portal all in one
• Mailbox API: Read and write data to Help Scout mailboxes
• Docs API: Read and write data to your Docs sites
• Webhooks: Get notified about activity in Help Scout

Choose the method that best fits your integration needs.

6. Implement your integration

Using your chosen programming language and the appropriate API client or library, implement your integration. Remember to:

• Use your API key for authentication
• Handle errors and edge cases
• Respect rate limits
• Implement pagination where necessary

7. Test your integration

Thoroughly test your integration to ensure it works as expected and handles various scenarios correctly.

What can you do with the Help Scout API?

Here are the key data models you can interact with using the Help Scout API, along with what is possible for each:

Conversations

• List conversations
• Create new conversations
• Update existing conversations
• Delete conversations
• Add tags to conversations
• Get conversation threads
• Create conversation threads
• Get conversation custom fields
• Update conversation custom fields

Customers

• List customers
• Create new customers
• Update existing customers
• Delete customers
• Get customer properties
• Update customer properties

Mailboxes

• List mailboxes
• Get mailbox details
• Create mailboxes
• Update mailboxes
• Delete mailboxes

Users

• List users
• Get user details
• Create users
• Update users
• Delete users

Tags

• List tags
• Create tags
• Update tags
• Delete tags

Workflows

• List workflows
• Get workflow details
• Run manual workflows

Reports

• Get various report data (e.g. company stats, user stats, conversation stats)

Attachments

• Upload attachments
• Get attachment details
• Delete attachments

Custom Fields

• List custom fields
• Create custom fields
• Update custom fields
• Delete custom fields

This covers the main data models and operations available through the Help Scout API. The API allows you to programmatically manage most aspects of your Help Scout account and data.