> ## Documentation Index
> Fetch the complete documentation index at: https://docs.julian.11x.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chili Piper

> Connect Julian to Chili Piper so callers can book meetings through your existing routing rules.

Julian connects to Chili Piper through Ampersand, a managed integration provider that brokers third-party
connections securely. Once connected, Julian can read availability, follow your configured routing logic, and book
meetings during live calls.

## How authentication works

You authorize Chili Piper once from the Julian app at the organization level:

```text theme={null}
Integration Settings > Chili Piper > Connect
```

During that flow, provide a Chili Piper API key created by a Chili Piper super admin. Ampersand stores the credential
securely and scopes it to your organization.

<CardGroup cols={2}>
  <Card title="Credential handling" icon="shield-halved">
    Julian does not store your raw Chili Piper API key. Requests are made server-to-server through Ampersand's proxy.
  </Card>

  <Card title="Access control" icon="key">
    The connection can be updated or revoked from the same settings screen. Rotating the key in Chili Piper also cuts
    off access.
  </Card>
</CardGroup>

## Create the Chili Piper API key

You must be a **super admin** in your Chili Piper instance to generate API keys.

1. Go to your Chili Piper credentials page:

   ```text theme={null}
   https://<your-subdomain>.chilipiper.com/fire/admin/integrations/credentials
   ```

2. Generate a new API key.

3. Enable the permissions listed below.

4. Paste the key into the Julian Chili Piper connection flow.

## Required permissions

Grant the required permissions first, then add the permissions for the scheduling mode your team will use.

| Permission                      | Required                                      | Feature                 |
| ------------------------------- | --------------------------------------------- | ----------------------- |
| **Workspace** — read            | <Icon icon="circle-check" iconType="solid" /> | Every Chili Piper setup |
| **User** — read                 | <Icon icon="circle-check" iconType="solid" /> | Every Chili Piper setup |
| **Meeting** — read              | <Icon icon="circle-check" iconType="solid" /> | Every Chili Piper setup |
| **Scheduling Links** — schedule |                                               | Simple ChiliCal         |
| **Handoff** — schedule          |                                               | CRM Dependent           |
| **Concierge** — route           |                                               | CRM Dependent           |
| **Rule** — read                 |                                               | Full access             |
| **Team** — read                 |                                               | Full access             |
| **Routers** — read              |                                               | Full access             |
| **Distributions** — read        |                                               | Full access             |

**Workspace — read**, **User — read**, and **Meeting — read** are required for every setup. Julian uses them to load
workspaces and bookers during configuration, and to display booked meetings after a call.

Choose the smallest set that covers your intended scheduling mode. Select **Full access** when your team will use
both modes or wants to avoid updating the API key as it adopts additional Chili Piper capabilities.

## Scheduling modes

Julian supports two Chili Piper scheduling modes, selected per agent in the Chili Piper tool configuration. The
Julian-side names map to Chili Piper products as follows:

| Julian setting                | Chili Piper product       | CRM lookup during booking |
| ----------------------------- | ------------------------- | ------------------------- |
| **Simple ChiliCal** (default) | ChiliCal Scheduling Links | No                        |
| **CRM Dependent**             | Handoff                   | Yes                       |

Mode selection is deterministic: an agent configured for one mode always books through that mode, and Julian never
falls back from one to the other mid-call.

### Simple ChiliCal

Julian books through one of your ChiliCal scheduling links (round-robin, group, admin, or ownership links). The
caller's email is only used to send the invite; Chili Piper does not look the caller up in your CRM. The meeting host
is decided by the link itself, for example round-robin across the team.

Requirements:

* A scheduling link exists in your Chili Piper dashboard.
* The API key includes the **Scheduling Links: schedule** permission.

Choose this mode when any qualified rep can take the meeting and routing does not depend on CRM data.

### CRM Dependent

Julian books through a Chili Piper Handoff router. When Julian requests availability, Chili Piper looks up the
caller's email in your connected CRM (HubSpot or Salesforce) and evaluates your routing rules against that record, so
meetings can go to the account owner, the right territory rep, and so on.

Two behaviors to be aware of, both by design:

* The caller **must exist as a contact in your CRM**. If Chili Piper finds no match, the booking fails with an error
  rather than silently booking through a scheduling link, so the slots shown and the meeting booked always come from
  the same routing decision.
* Assignment always goes through a Chili Piper **distribution** (queues and rules), never direct user assignment.

Requirements:

* Your CRM is connected to Chili Piper.
* A Handoff router is configured in your Chili Piper dashboard.
* A distribution with assignees is configured.
* The workspace ID and booker ID from your Chili Piper dashboard are set in the Julian tool configuration.

Choose this mode when who gets the meeting depends on CRM ownership, territory, or other record-level routing rules.

### Chili Piper APIs used by each mode

Both modes call Chili Piper's Edge API (base URL `https://fire.chilipiper.com/api/fire-edge/v1/org`) server-to-server
through Ampersand's proxy. Each mode is a two-step flow: an init call returns available slots, then a schedule call
books the selected slot.

**Simple ChiliCal (Scheduling Links endpoints):**

| Step                                      | Endpoint                                                                                             |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Find a usable link (unless one is pinned) | `POST /schedulingLinks/list-round-robin`, `/list-admin-one-on-one`, `/list-group`, `/list-ownership` |
| Get availability                          | `POST /schedulingLinks/init-simple`                                                                  |
| Book the meeting                          | `POST /schedulingLinks/routing/{routeId}/schedule-simple`                                            |

The `routeId` returned by the init call is reused at booking time, so the round-robin assignment made when slots were
shown is the rep who actually gets booked.

**CRM Dependent (Handoff endpoints):**

| Step                                  | Endpoint                                                                                              |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Route the caller and get availability | `POST /handoff/workspace/{workspaceId}/booker/{bookerId}/init-simple`                                 |
| Book the meeting                      | `POST /handoff/routing/{routingId}/router/{routerId}/path/{pathId}/booker/{bookerId}/schedule-simple` |

The Handoff init call is where the CRM lookup happens: the response includes the matched CRM contact along with the
router, path, and assignee that Chili Piper selected. A missing CRM match is what produces the booking error described
above.

Both modes also use a few discovery endpoints (`GET /workspace`, `GET /workspace/users`, `GET /user/read/{userId}`)
that power the Julian configuration screens; these are not part of the live booking flow.

## What happens during a call

When a caller reaches a point where a meeting should be booked, Julian uses Chili Piper in real time. The exact
endpoints depend on the [scheduling mode](#scheduling-modes) above, but the shape of the flow is the same:

1. Julian selects the appropriate workspace based on conversation context, such as Support, SMB, Mid-Market, or
   Enterprise. This segmentation is configurable and can also use known input values, such as CSV or lead attributes.
2. Julian fetches live availability for the selected workspace.
3. Julian follows the routing rules configured in Chili Piper, such as round-robin, distributions, or ownership rules.
4. Julian books the caller into the resulting slot and host.

In short:

```text theme={null}
workspace -> availability -> routing -> booking
```

## Setup questions

Before going live, your 11x contact may ask for a few details about your Chili Piper setup:

* How do you currently handle scheduling in Chili Piper?
* Is your CRM connected to Chili Piper?
* Do you manage all routing rules and CRM updates within Chili Piper, or do you run custom automations on top of it?
* Which Chili Piper workspaces are relevant for your Julian use case?
* Do you use Simple ChiliCal and handle routing afterward, or does Chili Piper handle routing end-to-end (CRM
  Dependent)?
* What type of ChiliCal links do you use (round-robin, group, admin, ownership)?
* Do you need Concierge support?

These answers help 11x configure the correct call-time routing and segmentation for your team.