Helper

Integrations

Integrate Helper with other services

Resend

Enables sending one-time password emails for login.

  1. Go to Resend and create an account or log in.
  2. Verify a domain to use for sending emails.
  3. Navigate to the API section to generate an API key.
  4. Add the API key as an environment variable: RESEND_API_KEY.
  5. Add your preferred email address on the verified domain as an environment variable: RESEND_FROM_ADDRESS. You can also add a sender name in this format: "Helper" <youremail@yourdomain.com>.

Gmail

Enables sending support emails from your Gmail or Google Workspace account.

  1. Go to the Google Cloud Console.
  2. Create a new project or select an existing one.
  3. Navigate to "APIs & Services" > "Credentials".
  4. Click "Create Credentials" and select "OAuth client ID".
  5. Choose "Web application" as the application type.
  6. Add https://<your-helper-domain>/api/connect/google/callback to the "Authorized redirect URIs".
  7. Click "Create". You will be shown the Client ID and Client Secret.
  8. Add these values as environment variables: GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
  9. Navigate to "APIs & Services" > "Library".
  10. Search for "Gmail API" and enable it for your project.
  11. Navigate to "APIs & Services" > "OAuth consent screen".
  12. Configure the consent screen. Under "Data access", add the .../auth/gmail.send scope.
  13. Add your Google account email address as a Test User under "Audience" while the app is in testing mode.

Google Pub/Sub

Enables the app to receive real-time notifications (e.g., new emails) from Gmail.

If running locally, set up and start Serveo, ngrok or similar to get a public forwarding URL pointing to localhost:3010.

  • Go to the Google Cloud Console and select the same project used for Google OAuth.
  • Navigate to "Pub/Sub" > "Topics".
  • Click "Create Topic". Give it a name (e.g., helper-email-dev) and click "Create".
  • Add the topic name as an environment variable: GOOGLE_PUBSUB_TOPIC_NAME.
  • Grant the Gmail service account permission to publish to this topic:
    • Go back to the "Topics" list and check the box next to your new topic.
    • Click "Permissions" in the info panel on the right (or click the topic name and go to the Permissions tab).
    • Click "Add Principal".
    • In the "New principals" field, enter gmail-api-push@system.gserviceaccount.com.
    • Assign the role "Pub/Sub Publisher".
    • Click "Save".
  • Create a service account for the push subscription authentication:
    • Go to "IAM & Admin" > "Service Accounts".
    • Click "Create Service Account".
    • Give it a name (e.g., pubsub-push-auth-dev) and an ID. Click "Create and Continue".
    • Grant the service account the "Service Account Token Creator" role (roles/iam.serviceAccountTokenCreator). This allows it to generate OIDC tokens for authentication. Click "Continue" and "Done".
    • Add the service account email (e.g., pubsub-push-auth-dev@<your-project-id>.iam.gserviceaccount.com) as an environment variable: GOOGLE_PUBSUB_CLAIM_EMAIL.
  • Create the push subscription:
    • Navigate to "Pub/Sub" > "Subscriptions".
    • Click "Create Subscription".
    • Give it an ID (e.g., helper-email-subscription-dev).
    • Select the Pub/Sub topic you created earlier (e.g., helper-email-dev).
    • Under "Delivery type", select "Push".
    • In the "Endpoint URL" field, enter your Helper domain followed by the webhook path: https://<your-helper-domain>/api/webhooks/gmail.
    • Check the box for "Enable authentication".
    • Select the service account you just created (e.g., pubsub-push-auth-dev@<your-project-id>.iam.gserviceaccount.com).
    • Leave other settings as default and click "Create".

Now linking your Gmail account from Settings → Integrations should grant Gmail access and webhooks for new emails should arrive on your local server.

Optional Integrations

Slack

Enables various features including messaging channels when tickets are received, messaging users when tickets are assigned, and an AI agent.

  1. Set up and start Serveo, ngrok or similar to get a public forwarding URL pointing to localhost:3010.
  2. Go to api.slack.com/apps and create a new app.
  3. Under "Basic Information", find your app credentials.
  4. Add the following values as environment variables:
    • SLACK_CLIENT_ID: Client ID from Basic Information
    • SLACK_CLIENT_SECRET: Client Secret from Basic Information
    • SLACK_SIGNING_SECRET: Signing Secret from Basic Information
  5. Under "OAuth & Permissions", add all scopes listed in lib/slack/constants.ts
  6. Under "Event Subscriptions", add https://<your-helper-domain>/api/webhooks/slack/event as the event request URL
  7. Also under "Event Subscriptions", subscribe to the following bot events:
    • app_mention
    • assistant_thread_started
    • message.channels
    • message.im
    • tokens_revoked
  8. Under "Interactivity & Shortcuts", add https://<your-helper-domain>/api/webhooks/slack/response as the interactivity request URL
  9. Under "Agents & AI Apps", check "Agent or Assistant"
  10. Under "App Home", check "Always Show My Bot as Online"
  11. Install the app to your workspace.

GitHub

Enables creating GitHub issues from tickets and replying to the customer when the issue is closed.

  1. Go to github.com/settings/apps and click "New GitHub App".
  2. Fill in the required fields, including a name for your app.
  3. Set the Callback URL to https://<your-helper-domain>/api/connect/github/callback
  4. Also set the post-installation Setup URL to https://<your-helper-domain>/api/connect/github/callback and check "Redirect on update"
  5. Set the following permissions:
    • Repository permissions:
      • Issues: Read & write
    • Account permissions:
      • Email addresses: Read-only
  6. After creating the app, note the App ID and generate a private key.
  7. Add the following values as environment variables:
    • GITHUB_APP_SLUG: The slug of your GitHub app (from the URL; it should be a dasherized version of your app's name)
    • GITHUB_APP_ID: The App ID found in the app settings
    • GITHUB_CLIENT_SECRET: The Client Secret from the app settings
    • GITHUB_PRIVATE_KEY: The contents of the private key file you downloaded

Jina

Enables the widget to read the current page for better AI context.

  1. Go to jina.ai and create an account or log in.
  2. Navigate to the API section to generate an API token.
  3. Add the token as an environment variable: JINA_API_TOKEN.

Firecrawl

Enables linking an existing knowledge base website for the AI to reference.

  1. Go to firecrawl.dev and create an account or log in.
  2. Generate an API key from your account settings or dashboard.
  3. Add the API key as an environment variable: FIRECRAWL_API_KEY.

Asset Proxy

Enables passing email assets through an intermediate server to increase security.

  1. Set up a proxy server with HMAC authentication.
Example CloudFlare Worker script
const SECRET_KEY = "<secret key>";
const EXPIRY_TIME = 300; // Signature expiry time in seconds (5 minutes)
 
async function verifySignature(request) {
  const url = new URL(request.url);
  const targetUrl = url.searchParams.get("url");
  const passedSignature = url.searchParams.get("verify");
  const expires = url.searchParams.get("expires");
 
  if (!targetUrl || !passedSignature || !expires) {
    return false;
  }
 
  const now = Math.floor(Date.now() / 1000); // Current time in seconds
  if (now > parseInt(expires, 10)) {
    return false; // Expired request
  }
 
  // Compute expected HMAC signature
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw",
    encoder.encode(SECRET_KEY),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"],
  );
 
  const dataToSign = `${targetUrl}:${expires}`;
  const signatureData = encoder.encode(dataToSign);
  const signatureBuffer = await crypto.subtle.sign("HMAC", key, signatureData);
  const expectedSignature = btoa(String.fromCharCode(...new Uint8Array(signatureBuffer)))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, ""); // URL-safe Base64 encoding
 
  return expectedSignature === passedSignature;
}
 
export default {
  async fetch(request) {
    if (!(await verifySignature(request))) {
      return new Response("Forbidden: Invalid or expired signature", { status: 403 });
    }
 
    const url = new URL(request.url);
    const targetUrl = url.searchParams.get("url");
 
    try {
      const response = await fetch(targetUrl, {
        method: request.method,
        headers: request.headers,
      });
 
      const newHeaders = new Headers(response.headers);
      const allowedOrigins = ["https://<your-helper-domain>"];
      const origin = request.headers.get("Origin");
 
      if (allowedOrigins.includes(origin)) {
        newHeaders.set("Access-Control-Allow-Origin", origin);
      }
 
      newHeaders.set("Access-Control-Allow-Methods", "GET");
      newHeaders.set("Access-Control-Allow-Headers", "*");
      newHeaders.set("X-Proxy-By", "Helper Content Proxy");
 
      return new Response(response.body, {
        status: response.status,
        headers: newHeaders,
      });
    } catch (error) {
      return new Response(`Error: ${error.message}`, { status: 500 });
    }
  },
};
  1. Add the following values as environment variables:
    • PROXY_URL: The URL of your proxy server
    • PROXY_SECRET_KEY: The same secret key you set in the script

Sentry

Enables error reporting and performance tracing.

  1. Go to sentry.io and create an account or log in.
  2. Create a new project for a Next.js application.
  3. In the project settings, find the DSN (Data Source Name).
  4. Add the DSN as an environment variable: NEXT_PUBLIC_SENTRY_DSN.

Self Hosting

Get started by setting up a Helper instance

Local Development

Customize and contribute to Helper

On this page