HelpScout Create Ticket Example

Getting Started

From Scratch

Clone this repository:

git clone https://github.com/inkeep/helpscout-ticket-creation-vercel

Setup dependencies:

pnpm install

Copy the example env file to make a .env.development.local for local development.

cp .env.example .env.development.local

Add to an existing project

If you'd like to add an API route to an existing Next.js project:

1. Copy the files under api/create-support-ticket into your own API route.
2. Install deps via pnpm add @vercel/edge-config zod
3. Follow the rest of these instructions to get the .env variables you need

Create HelpScout application

1. Login to HelpScout

2. Open your profile picture then select Your Profile.

3. Click on the My Apps tab.

4. Click on Create My App

5. Provide an App Name, like "Inkeep Create Ticket Flow"

6. Provide any value for Redirection URL, like "https://{mydoamin}.com", it's not used.

7. Copy the App ID and App Secret fields into your env variables

HELPSCOUT_APP_ID="<HELPSCOUT_APP_ID>"
HELPSCOUT_APP_SECRET="<HELPSCOUT_APP_SECRET>"

Get a mailbox ID

1. Open Inbox tab on HelpScout

2. On left bottom corner open click on the Gear Icon and select Edit Inbox

3. Copy the ID from the page URL:

https://secure.helpscout.net/settings/inbox/<HELPSCOUT_MAILBOX_ID>/

Add it as an env variable:

HELPSCOUT_MAILBOX_ID="<HELPSCOUT_MAILBOX_ID>"

Help Scout Access Tokens

HelpScout access tokens received via client-credentials (service-to-service authentication) expire after two days. To avoid fetching a new access token on every request, we'll use Vercel's Edge Config to cache the latest access token, which is optimized for scenarios with high read and low write operations.

Create Edge Config Store

Create an Edge Config Store instance for your project. See here.

Once created, copy the ID of the Edge Config Store and add it as an env variable:

EDGE_CONFIG_ID="<EDGE_CONFIG_ID>"

Creating an Edge Config Store will also automatically create an EDGE_CONFIG env variable in your Vercel project. This is used for reading from the Store using the @vercel/edge-config SDK.

For local development, you can visit your project's Settings > Environment Variables and copy it.

Set it as an env variable:

EDGE_CONFIG="<EDGE_CONFIG>"

Vercel API Access Token

Next, create a Vercel API access token. See here. This is used to write to the Edge Config. Set the scope to the Vercel team you'd like it to apply to.

Add it as env variable:

VER_API_ACCESS_TOKEN="<VER_API_ACCESS_TOKEN>"

Lastly, set the Vercel Team ID for where your project is located. You can find this under Settings under your Team in the Vercel dashboard

VER_TEAM_ID="<VER_TEAM_ID>"

Inkeep Preview URL (optional)

If you'd like to attach a link to the Inkeep Dashboard view of the AI-chat for reference, then set the following:

INKEEP_CHAT_PREVIEW_ROOT=https://portal.inkeep.com/<ORG_ALIAS>/projects/<PROJECT_ID>/chat/sandbox

This will be added as an internal-facing note to the supprot conversation.

Run locally

pnpm dev

API Routes

/api/create-support-ticket - Create a new conversation/ticket in your inbox.

See the HelpScout Create Conversation API for full customization.

Example Request

Note that the request is generated by your client side, please validate that the types and request body align.

There's an example Zod validation and types in api/create-support-ticket/requestSchemaValidation.ts. Validation should be optimistic.

{
  "formDetails": {
    "firstName": "John",
    "email": "j@domain.com",
    "additionalDetails": "Would like to change my password, please."
  },
  "chatSession": {
    "messages": [
      {
        "role": "user",
        "content": "How do I change my password?"
      },
      {
        "role": "assistant",
        "content": "Sorry, I wasn't able to find information about that. Please reach out to support."
      }
    ],
    "chatSessionId": "12345"
  },
  "client": {
    "currentUrl": "https://example.com/help"
  }
}