> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Zapier Integration
> Connect IllumiChat to 7,000+ apps with no-code Zapier automations
Connect IllumiChat to [Zapier](https://zapier.com) to automate your workflows across more than 7,000 apps — no code required. Push new leads into your CRM, alert your team in Slack when a ticket is created, sync conversations to a spreadsheet, or have your assistant follow up automatically.
The Zapier integration requires a **Pro plan or higher**. It authenticates with a **workspace API key**, so any Zap you build acts on behalf of your workspace rather than an individual user.
## How It Works
IllumiChat exposes **triggers** (events that start a Zap) and **actions** (steps a Zap can run in IllumiChat). You combine them with any other app Zapier supports.
In IllumiChat, go to **Settings → API Keys** and create a key. It starts with `wsk_live_`. Copy it somewhere safe — you will only see it once.
In the Zapier editor, add IllumiChat as a trigger or action and choose **Connect a new account**. Paste your API key into the connection wizard.
Pick a trigger (for example, **Lead Captured**) or an action (for example, **Create or Update Contact**), map the fields, and turn the Zap on.
## API Key Scopes
When you create the API key, grant the scopes for the features your Zaps use. The connection wizard reminds you of these:
| Scope | Needed for |
| ---------------- | ------------------------------------------------------------------- |
| `events:read` | All triggers (Lead Captured, Conversation Event) and sample data |
| `contacts:write` | The **Create or Update Contact** action and **Find Contact** search |
| `tickets:write` | The **Create Ticket** and **Update Ticket** actions |
| `chat:write` | The **Send Message to Conversation** action |
If a Zap fails to connect or returns a `403`, check that your key carries the scope listed above and that your workspace is on a Pro plan or higher.
## Triggers
Triggers are **instant** — IllumiChat pushes events to Zapier the moment they happen, so your Zaps run in real time rather than polling on a schedule.
### Lead Captured
Starts a Zap whenever a new contact is created — whether a visitor submits the widget lead form or a contact is added to your CRM. The trigger normalizes both into a single contact record so your downstream steps see consistent fields.
**Output fields:** `id`, `name`, `email`, `phone`, `source`, `isNew`, `createdAt`, `assistantId`, `assistantName`.
The trigger fires for leads from every assistant in the workspace; use the `assistantId` / `assistantName` output fields with a Zapier Filter step if you need to narrow to one assistant.
**Example Zaps:**
* New lead → create a row in Google Sheets
* New lead → add a contact in HubSpot and notify `#sales` in Slack
* New lead → send a welcome email via Gmail
### Conversation Event
A single trigger covering the conversation lifecycle. Pick which event fires the Zap from the **Event Type** dropdown:
| Event | Fires when |
| ------------------------------- | ---------------------------------------------- |
| `ticket.created` | A support ticket is opened |
| `ticket.assigned` | A ticket is assigned to an agent |
| `ticket.status_changed` | A ticket's status changes |
| `live_chat.session_queued` | A conversation is queued for a human agent |
| `live_chat.agent_assigned` | A human agent picks up a live chat |
| `live_chat.session_transferred` | A live chat is handed to another agent |
| `live_chat.session_ended` | A live chat session ends |
| `chat.conversation_started` | A new in-app conversation begins |
| `widget.conversation_started` | A website visitor starts a widget conversation |
Events fire workspace-wide; to narrow to one assistant, add a Zapier Filter step on the assistant fields in the event payload.
**Example Zaps:**
* New ticket → create an issue in Linear or Jira
* Ticket assigned → DM the assignee in Slack
* Live chat queued → alert your support team in Slack or Microsoft Teams
* Live chat ended → log the completed session to a spreadsheet or CRM
* Widget conversation started → notify `#sales` that a visitor is chatting
## Actions
### Create or Update Contact
Adds a contact to your IllumiChat CRM or updates an existing one (matched by email). Useful for keeping IllumiChat in sync with leads that originate in other tools.
Requires the `contacts:write` scope.
**Example Zap:** New Typeform submission → **Create or Update Contact** in IllumiChat.
### Create Ticket
Creates a support ticket in IllumiChat. Tickets created this way start in status `new` with source `api`.
Optionally link the ticket to an existing CRM contact by email. The action fails if no contact matches — add a **Find or Create Contact** step before it when the contact might not exist yet.
Requires the `tickets:write` scope.
**Example Zap:** New angry review in Trustpilot → **Create Ticket** assigned to your support queue.
### Update Ticket
Updates an existing ticket's status, priority, subject, or description. Map the **Ticket ID** from a Conversation Event trigger (every ticket event includes `data.ticket.id`) or from an earlier Create Ticket step. Setting the status to `resolved` or `closed` also stamps the ticket's resolved/closed time.
Requires the `tickets:write` scope.
**Example Zap:** Jira issue closed → **Update Ticket** to `resolved` in IllumiChat.
### Send Message to Conversation
Sends a message into an existing conversation.
This action only works on conversations that are in **live-chat takeover** mode (a human agent has taken over from the assistant). Sending to a conversation that is still AI-handled is rejected. Use it to bridge agent replies from another tool, not to inject messages into automated chats.
Requires the `chat:write` scope.
## Searches
### Find Contact
Looks up a contact in your IllumiChat CRM by exact email address. Pair it with **Create or Update Contact** using Zapier's **create if not found** option to get find-or-create behavior in one step.
Requires the `contacts:write` scope.
## Testing With Sample Data
When you click **Test trigger** in the Zap editor, IllumiChat returns a representative payload so you can map fields before any real event fires:
* If your workspace has received a recent event of that type, Zapier shows that **real** payload.
* Otherwise it shows a **fixture** with placeholder values, so you can still build and map your Zap.
## Managing the Connection
* A Zap's connection is tied to the API key you pasted. Revoking that key in **Settings → API Keys** disconnects every Zap using it.
* Turning a Zap off in Zapier automatically removes its event subscription in IllumiChat, so you stop receiving deliveries for it.
* The Zapier "account" label shows your workspace name, so you can tell multiple workspace connections apart.
## Troubleshooting
Confirm the key starts with `wsk_live_`, has not been revoked, and that your workspace is on a Pro plan or higher. The connection test also requires the `events:read` scope.
The Zapier integration is gated to Pro and above. Upgrade your workspace plan, then reconnect the account in Zapier.
Make sure the Zap is turned on and that you are generating the event in the right workspace (the connection is tied to one workspace's API key).
The conversation must be in live-chat takeover mode. The action cannot post into a conversation that the assistant is still handling automatically.
The **Contact Email** field only links to contacts that already exist in your CRM. Add a **Find or Create Contact** step before the Create Ticket step, or leave the field blank to create the ticket without a contact link.