---
title: "Zapier"
description: "New lead, handoff requested and unanswered-question triggers, connected with an API key."
source: https://hiy.ai/docs/zapier
---

# Zapier

Three triggers — a new lead, a conversation handed to you, and an unanswered
question — plus one action, **Ask the agent**, from any of the thousands of
apps Zapier connects to. No code: point a Zap at a trigger, or add the action
to one, and it runs in whatever app you already use.

**Warning:** Not connectable yet. The app is built and tested, but publishing it to
Zapier's own directory hasn't happened — search Zapier for **hiy** today and
you won't find it. See the [roadmap](/roadmap) for where this stands.

**Note:** Rolling out to selected workspaces first. Until then, the API keys card under
**Publish → Security** and every `/api/v1/zapier/*` endpoint answer as if
neither existed for a workspace outside the early list. Want in early? Ask at
[hello@hiy.ai](mailto:hello@hiy.ai).

## Authentication

Zapier asks for a single API key. Create one from any agent's
**Publish → Security** tab — see [API keys](/docs/api-keys) for how — and
paste it in. A key is scoped to your whole organization, so it works for
every agent, and Zapier's own "Test" step confirms it by listing your agents.

## Triggers

- **New lead** (`event`) — Someone left their contact details, whether or not the conversation was handed off. Event name `lead_captured`.
- **Handoff requested** (`event`) — A conversation was handed to you because the agent couldn't take it further — carries the same contact details, plus whether the twin had already admitted it didn't know something in that conversation. Event name `handoff`.
- **Unanswered question** (`event`) — Your twin couldn't answer something and a new question landed in your teach queue. Fires once per new question, never again for a repeat of one already queued. Event name `gap_opened`.

Pick which agent to watch from a dropdown built from your organization's
agents. Under the hood, each trigger tries to run as a **REST Hook** —
Zapier registers a URL with hiy once, and hiy posts to it the moment the
event happens, so there's no polling delay. If a Zap can't use REST hooks
(some plans and some trigger tests), it falls back to **polling**: hiy is
asked every few minutes for the most recent items of that kind.

**Note:** The two share nothing you need to think about — turning a Zap on and off, or
Zapier switching between hook and polling mode, is handled entirely on
Zapier's side.

## Actions

- **Ask the agent** (`action`) — Send a question to one of your agents from inside a Zap — a form submission, a Slack message, a row landing in a sheet — and get back the answer, plus its citations, the same shape a website visitor's chat receives. Counts as one message against your plan's monthly allowance, exactly like a real visitor's question; a **Paused** workspace, or a plan that's used up its messages, refuses the same way it would refuse a visitor.

Each call is asked cold — a Zap carries no memory of an earlier answer — and
is a real, counted exchange: if your agent doesn't know something, it lands
in your teach queue exactly as if a visitor had asked.

## Setting it up

1. Create an API key under **Publish → Security** and copy it.
2. In Zapier, search for **hiy** and start a Zap with one of the three
   triggers above, or add **Ask the agent** as a step in one.
3. Paste your API key when asked to connect your account.
4. Choose which agent to watch or ask.
5. For a trigger, pick or build the action in whatever app you're connecting
   to — a new row in a spreadsheet, a message in Slack, a card on a board.

Every plan includes this — there's no seat or plan gate on connecting
Zapier, only the early-workspace rollout above.