Support toolsAgent copilot

Prehook Integration

Copy page

Integrate Inkeep Agent Copilot with Prehook.

Overview

Sometimes you may want to provide information from external systems to the Inkeep support copilot. This can include:

  • Payment information from your billing system
  • Account information from your CRM
  • Activity or product-specific data from your database
  • Uptime information from your application monitoring software

To accomplish this, you can use a prehook for the copilot. When a prehook is enabled, the following happens:

  1. When a support agent clicks on Smart Assist, Inkeep will make a request to an API route of your choosing.
  2. Your API route fetches information from any arbitrary backend service[s].
  3. Your API route returns that information and any custom instructions in the API route's response.
  4. That information is added as custom context for the AI copilot to consider.
  5. That context is persisted across the entire conversation with the copilot.

Think of the prehook as a way to inject dynamic, custom data or instructions into the Copilot's decision-making process.

1. Deploy your API route

You'll need to deploy an API endpoint that the Copilot can call.

A quick way to deploy is to use the below Vercel template: Deploy with Vercel

  1. Click the "Deploy with Vercel" button above
  2. Connect your GitHub account when prompted
  3. Generate a random API key using this command:
    openssl rand -base64 30 | cut -c1-40
  4. Enter this API key as the INKEEP_SUPPORT_COPILOT_API_KEY environment variable
  5. Click Deploy

Option 2: Deploy anywhere

As long as your API route follows the API contract, you can deploy and develop the API route in any cloud provider or API framework. A reference TypeScript template repository is provided here.

2. Write your custom logic

Below are the schemas that are used by the prehook. If you're using the reference template, you can customize your business logic in this file.

Request

The request to your API endpoint will include information the Copilot has in relation to the current ticket. You can use this information, like a user email or ID, to fetch information from downstream services.

Request examples

Request parameters

ParameterTypeDescription
ticketIdstringUnique identifier for the ticket for your support platform.
ticketingPlatformTypestringThe support platform type ("zendesk", "github", "plain", or "other").
ticketAttributesobjectInformation about the ticket provided by the support platform.
userAttributesobjectInformation about the user provided by the support platform.
organizationAttributesobjectInformation about the organization the user is a member of as provided by the support platform (for business-to-business type scenarios).
messagesMessageObject[]List of message objects containing conversation history.
Note
Note

The exact ticket, user and organization attributes provided are dependent on the support ticketing platform. If you'd like to fetch more information from the support platform, you can use the ticketId to query relevant information.

MessageObject

ParameterTypeDescription
idstringUnique identifier for the message.
createdAtdate (optional)Timestamp when the message was created.
contentstringThe message text content.
authorIdstringUnique identifier for the message author.
authorTypestringType of author ("user" or "member").
authorNamestring (optional)Name of the message author.
filesarrayList of attached files, each containing id and url.
isInternalCommentboolean (optional)Whether the message is an internal note.

Response

The response from your API endpoint should include any additional context you want to provide to the Copilot. You can also include specific instructions to guide how the Copilot should respond. All of the below are Optional.

Here's an example response:

{
  "userAttributes": [
    {
      "label": "payment_status",
      "value": "overdue",
      "description": "Customer has an overdue payment",
      "useWhen": "when user asks about billing issues"
    }
  ],
  "organizationAttributes": [
    {
      "label": "support_tier",
      "value": "enterprise",
      "description": "Organization has enterprise support",
      "audience": "member"
    }
  ],
  "prompt": "This is an enterprise customer, ensure you use a warm, expedient tone that reflects that we are urgently considering their request. There is currently an outage on the dashboard, so if they mention that, let them know this the team is aware and actively investigating."
}

Response format

ParameterTypeDescription
userAttributesAttributeObject[]Optional. List of attribute objects providing context about the user.
organizationAttributesAttributeObject[]Optional. List of attribute objects providing context about the organization.
ticketAttributesAttributeObject[]Optional. List of attribute objects providing context about the ticket.
promptstringOptional. Additional instructions to guide the Copilot's response.
Tip
Tip

The prompt field is best used for high-level instructions or context that doesn't fit naturally into the attributes. For example, prompt can include:

  • Real-time information on a wide-application situation: "There is currently an outage affecting our dashboard. If the user references an outage, link them to the tracker page here."
  • Tone/style guidance: "This is a VIP customer, use an expedited tone..."
  • Complex business rules: "If the user mentions feature X, first verify their subscription tier..."

Think of this as dynamic instructions or context for the bot beyond what can be described with attributes.

AttributeObject

FieldTypeDescription
labelstringSemantic, short identifier for the attribute (e.g., 'subscription_plan').
valuestringThe attribute's value (e.g., 'premium').
descriptionstringOptional explanation of the attribute's meaning or implications of the value.
useWhenstringOptional condition for when the copilot should consider or use this attribute.
audience"user" | "member" | "any"Optional field to specify which type of participant can see this attribute. Defaults to any.
Tip
Tip

useWhen and description should contain the core details of when this attribute may or may not be relevant and how it should be used.

For more complex scenarios, use xml or markdown format to specify behavior. Check out our prompting guide for ideas.

3. Configure the prehook in the Inkeep Dashboard

Once your endpoint is deployed, configure it from the Inkeep Dashboard. Creating a separate copilot integration is recommended if you want to test the prehook without affecting your main copilot. More on this in the Testing section below.

  1. Create a new Support Copilot integration in the Inkeep Dashboard. Follow the steps here and give it a name like "Support Copilot with Prehook".
  2. Expand Advanced Settings.
  3. Under Prehook URL, enter the full URL of your API endpoint. Example: https://your-app-deployment-url.vercel.app/api.
  4. Under Headers (JSON), enter the headers you want to include in the prehook request. See below.
  5. Click Save.

Once this is saved, this new Copilot will use your prehook to get additional context and instructions when it runs.

Custom headers

In the Headers (JSON) field, you can configure custom headers to be included in the prehook request. While Content-Type: application/json is always included, you can use this to add additional headers, like for authentication. The value should be a valid JSON object with double quotes.

Example: To secure the API request, you can configure the headers to include an API key. For example:

{ "Authorization": "Bearer your-api-key" }

The template implementation includes a validation for this, so your-api-key should match the value of the INKEEP_SUPPORT_COPILOT_API_KEY environment variable.

If using your own implementation, ensure you implement your own validation of relevant headers.

Note
Note

The Headers (JSON) field is encrypted at storage, so it's safe to include sensitive information like API keys.

4. Testing your prehook

Once you've configured your prehook in the Inkeep Dashboard, you can test it by updating your setup in your support platform and clicking on Smart Assist.

Developing locally with ngrok

To test your prehook locally before deploying to production, you can use ngrok to create a public URL for your local development server:

  1. Start your local development server:

    # If using the reference template:
    vercel dev   # Runs on http://localhost:3000/api
     
    # If using your own implementation:
    # Start your server using your preferred method
  2. Install and set up ngrok:

  3. Create a secure tunnel to your local server:

    # Replace 3000 with your local server's port number
    ngrok http 3000
  4. In the ngrok output, copy the HTTPS URL (e.g., https://1234-your-tunnel.ngrok.app/api)

  5. Use this URL as your prehook URL in the Inkeep Dashboard

Note
Note

Important: The ngrok URL is temporary and changes each time you restart ngrok.

Testing in your support platform