https://github.com/inkeep/helpscout-ticket-creation-vercel
https://github.com/inkeep/helpscout-ticket-creation-vercel
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/inkeep/helpscout-ticket-creation-vercel
- Owner: inkeep
- Created: 2024-02-28T05:56:21.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-10T05:27:50.000Z (about 2 years ago)
- Last Synced: 2025-12-03T08:28:07.171Z (6 months ago)
- Language: TypeScript
- Homepage: https://helpscout-ticket-creation-vercel.vercel.app
- Size: 268 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# HelpScout Create Ticket Example
## Getting Started
### From Scratch
Clone this repository:
```bash
git clone https://github.com/inkeep/helpscout-ticket-creation-vercel
```
Setup dependencies:
```bash
pnpm install
```
Copy the example env file to make a `.env.development.local` for local development.
```bash
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**
6. Provide an **App Name**, like "Inkeep Create Ticket Flow"
7. Provide any value for **Redirection URL**, like "https://{mydoamin}.com", it's not used.
8. Copy the **App ID** and **App Secret** fields into your env variables
```
HELPSCOUT_APP_ID=""
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:
```bash
https://secure.helpscout.net/settings/inbox//
```
Add it as an env variable:
```
HELPSCOUT_MAILBOX_ID=""
```
## Help Scout Access Tokens
HelpScout [access tokens](https://developer.helpscout.com/mailbox-api/overview/authentication/#client-credentials-flow) 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](https://vercel.com/docs/storage/edge-config/get-started#quickstart).
Once created, copy the `ID` of the Edge Config Store and add it as an env variable:
```
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=""
```
### Vercel API Access Token
Next, create a Vercel API access token. See [here](https://vercel.com/docs/rest-api#creating-an-access-token). 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=""
```
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](https://vercel.com)
```
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//projects//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](https://developer.helpscout.com/mailbox-api/endpoints/conversations/create/) 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.
```JSON
{
"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"
}
}
```