Skip to main content

Draft replies for your support team in Zendesk

In this tutorial, you build a Zendesk action flow that drafts a reply for every new ticket, from all the knowledge you index with Kapa. Kapa indexes your knowledge sources (your documentation site, Notion, Confluence, GitHub, PDFs, support tickets) into one searchable knowledge base. The flow sends the ticket's content to Kapa's Chat API and attaches the answer as an internal comment: the draft is waiting before your agent even opens the ticket, and they edit and send it, or discard it.

The whole setup happens inside Zendesk's Admin Center, with no custom code and no separate hosting, and it is deterministic: you decide exactly when Kapa is called and where its answer lands, and a human decides what reaches the customer.

If you would rather have agents ask for drafts on demand inside the ticket view, without building anything, Kapa's prebuilt Zendesk Agent sidebar app does that; this tutorial covers the unprompted flavor, a draft on every new ticket.

By the end of this tutorial, you will have:

  • A Zendesk custom action that calls Kapa's Chat API with the content of a new ticket.
  • An action flow that runs on every created ticket and posts the drafted reply as an internal comment.

Before you start​

You need:

  • A Kapa project whose indexed knowledge sources contain the knowledge you want the drafts to draw from. Because every draft passes through a human before anything reaches the customer, internal sources (runbooks, past tickets, internal wikis) are as useful here as public documentation.
  • Zendesk admin access with permission to manage connections, custom actions, and action flows in the Admin Center.

Get your Kapa credentials​

The Zendesk side needs three values from the Kapa platform:

  1. Project ID: the unique identifier of your Kapa project. Go to Settings > Projects and copy it from the table.
  2. Integration ID: navigate to Integrations (under Configuration in the sidebar), click Add new integration, choose Custom (API), and copy the new integration's ID. It attributes the drafting flow's conversations, so they show up separately in the dashboard and Analytics.
  3. API key: navigate to API Keys (under Configuration in the sidebar), click Add new API key, and copy the key.

Keep the three values at hand; you paste them into Zendesk in the next sections.

Create a connection for your Kapa API key​

Zendesk stores API credentials in connections, separate from the actions that use them. You set the connection up once and reference it from the custom action.

  1. In Admin Center, go to Apps and integrations > Connections and create a new connection.
  2. Configure it:
    • Connection name: a recognizable name, for example Kapa API.
    • Connection type: API Key.
    • Header name: X-API-KEY. Kapa rejects requests that send the key under Authorization or any other header name.
    • Value: paste your Kapa API key.
    • Allowed domain: api.kapa.ai.
  3. Save the connection.

Create the custom action​

The custom action holds the API call: it sends the ticket's content to Kapa and returns the drafted answer.

  1. In Admin Center, go to Apps and integrations > Custom Actions and create a new custom action.
  2. Configure it:

    • Name: a recognizable name, for example Draft Kapa reply.

    • Description: what the action does, for your team, for example "Sends a ticket's content to Kapa and returns a drafted, knowledge-grounded reply."

    • Inputs: add a single input of type text, named query. This is a named parameter of the action, an empty slot for now; the action flow you build next fills it with the ticket's content on every run.

    • Request Method: POST.

    • Endpoint URL: https://api.kapa.ai/query/v1/projects/<PROJECT_ID>/chat/, with your Kapa project ID in the path.

    • Authentication: select the connection you created in the previous section.

    • Body: paste the following JSON and replace <INTEGRATION_ID> with your Kapa integration ID. Then replace <INPUT> by clicking {+} in the body editor and selecting your query input; this inserts a placeholder that Zendesk swaps for the input's value on every run. Do not leave <INPUT> as literal text, or Kapa receives the placeholder instead of the ticket content:

      {
        "integration_id": "<INTEGRATION_ID>",
        "query": "Suggest a response for this query, reply with only plaintext: <INPUT>"
      }

    • Outputs: define one output, answer, the drafted reply text. The response contains further fields you can expose if you want richer drafts; answer is all this flow needs.

  3. Save the custom action.

The integration_id associates the conversations with the Custom (API) integration you created, so they show up attributed in the dashboard and Analytics and you can separate the drafting flow's traffic from your other deployments. Always include it.

Create the action flow​

The action flow ties it together: it runs when a ticket is created, calls the custom action, and posts the draft.

  1. In Admin Center, go to Apps and integrations > Action Flows and create a new action flow.
  2. Add a trigger: Tickets > Lifecycle > Ticket created.
  3. Add a Look up ticket action and set its input to the Ticket ID from the trigger step. The trigger only carries the ticket's ID; this step fetches the full ticket so its content is available to later steps.
  4. Add your Draft Kapa reply custom action; custom actions often sit at the bottom of the Add step panel. In its query input field, click Add variable > Look up ticket > Description. This is where the pieces connect: on every run, the new ticket's description becomes the query input, and Zendesk splices it into the request body where you placed the {+} placeholder, so Kapa receives the actual ticket text.
  5. Add an Update ticket action:
    • Ticket ID: the ticket ID from the trigger.
    • Comment is public: false, so the draft lands as an internal comment only your team sees. Setting it to true would send Kapa's answer straight to the customer instead; do not do that until you have reviewed enough drafts to trust them.
    • Comment: the answer output from the custom action.
  6. Save and activate the flow.

Tune the drafting style (optional)​

Out of the box, the drafts follow Kapa's default response style. A customization shapes them into how your team actually writes, and because you associate it with the integration, nothing changes on the Zendesk side.

  1. Navigate to Customizations (under Configuration in the sidebar) and create a new customization. Give it a name, for example Zendesk drafts.
  2. Under Style & Tone, click + Add item for each rule the drafts should follow. Each instruction has a name and a description, for example:
    • No salutations: "Do not open with a greeting or close with a sign-off. Return only the body of the reply."
    • Short and concise: "Keep the reply as short as possible while answering the question. Do not restate the question or add background the customer did not ask for."
    • No internal links: "Never include links to internal sources, such as past support tickets or internal wiki pages. Use them to inform the answer, but only link public documentation."
  3. Check the preview panel on the right, which shows the system instructions with your changes applied.
  4. In the Integrations selector on the customization, pick your Custom (API) integration and save. The association also works the other way around, from the Customization column of the Integrations table.

Every draft the flow requests now follows these instructions. The third rule is also what makes internal knowledge sources safe to draw on: the model can use a past ticket to get the answer right without the draft pointing your customer at it. For guidance on writing instructions that models follow reliably, see Write effective instructions.

Verify it works​

Create a test ticket, for example by submitting your support form or sending an email to your support address. Open the ticket in the Agent Workspace: within a few moments, Kapa's drafted answer appears as an internal comment. Your agent can copy it into the reply, edit it, and send it.

Summary​

In this tutorial, you:

  • Created a Zendesk connection that sends your Kapa API key in the X-API-KEY header.
  • Built a custom action that sends a ticket's content to Kapa's Chat API and returns the drafted answer.
  • Built an action flow that runs on every created ticket and posts the draft as an internal comment for your agents.

Next steps​