---
name: crisphive-retell-setup
description: "Walks a Crisphive customer step by step through connecting Crisphive to Retell. Retell + Crisphive: add the Crisphive MCP server to a Retell agent so it finds callers and books confirmed field visits during the call. Step by step. Use when the user wants to set up, test or troubleshoot Crisphive with Retell."
---

# Book field jobs by phone with Retell

## How to use this file (instructions for the AI assistant)

You are helping a Crisphive customer connect Crisphive to **Retell**. The person you are talking to may not be technical and has probably not read the guide. Everything you need is in the guide below — follow it, do not improvise.

1. **Start by asking two things:** whether they already have a Crisphive account they can sign in to, and how far they have got (nothing yet, or which step). Skip the steps they have already done.
2. **Give ONE step at a time.** Name the exact page, button and field from the guide, and the exact value to type. Wait for them to say it is done (or to send a screenshot) before the next step.
3. **Ask for a screenshot when they are stuck** or when what they see does not match the guide. Screens change; if a label in the guide is not on their screen, say so plainly, describe what the step is trying to achieve, and help them find the closest equivalent. Never invent a button name.
4. **Secrets never go in this chat.** API keys (`chsk_…`), webhook signing secrets (`whsec_…`) and OAuth client secrets are pasted only into the platform field the guide names. If the user pastes one here, tell them to revoke it in Crisphive and create a new one.
5. **Start in Rehearsal (the sandbox).** Recommend test keys (`chsk_test_…`) and Rehearsal mode until the test at the end of the guide works. Only then explain how to switch to Live.
6. **Finish with the guide’s test.** The setup is done only when the test in the guide succeeds (for example a job appears in the Crisphive dashboard). If it fails, use the Troubleshooting and FAQ sections below.
7. **Stay inside this guide.** For anything it does not cover, point the user to the full page or to support@crisphive.com instead of guessing.

Source page: https://docs.crisphive.com/docs/retell (last updated 2026-10-10). If the user asks, this file is generated from that page and is always in step with it.

---

# The guide

By the end of this guide your Retell agent will answer a call, find the caller in Crisphive, and book and confirm a technician visit before hanging up.

If a label on your screen differs from this guide, follow the meaning of the step and tell us at `support@crisphive.com`.

No code is needed. Retell handles the voice (listening, the AI model, speaking). Crisphive handles the scheduling: customers, technicians, skills, working hours and service areas. You connect them by giving Retell one web address and one key, under the agent’s **MCPs**.

## Three words you will meet

| Word | What it means in plain language |
| --- | --- |
| **Agent** | Retell’s name for the AI that answers the phone. |
| **MCP server** | A web address that gives an AI a list of actions it may take (look up a customer, book a job). Crisphive’s voice one is `https://api.crisphive.com/mcp/voice`. In Retell you add it under the agent’s **MCPs**. |
| **API key** | A long password that lets the agent act for your business. It starts with `chsk_test_` (practice data) or `chsk_live_` (your real business), and Crisphive shows it once. In Retell it goes into a header of the MCP. |

## What the agent can do

`/mcp/voice` gives the agent exactly the tools it needs on a phone call, which keeps each turn fast. In Retell you pick the three tools the prompt uses (Step 4); the others are there if you write your own flow.

| Tool | What the agent uses it for |
| --- | --- |
| `listCustomers` (by phone) | Find the caller by the number they read out and confirmed; ask a returning customer “Am I speaking with …?”. |
| `bookAndConfirmJobRequest` | Create, size and confirm the job at the chosen time — one call. |
| `listJobRequestBookingWindows` | Which days and parts of the day are open. |
| `listMatchingSlots` | Exact start times for a job already created (step-by-step flow). |
| `listJobTypes` | Match the caller’s problem to one of your job types. |
| `getJobRequest` | Reads one job by its id. Not used by this prompt: questions about an existing booking go to a person (see [Calls that are not bookings](https://docs.crisphive.com/docs/retell#not-bookings)). |
| `createCustomer`, `createJobRequest`, `quoteJobRequest`, `confirmJobRequest` | The same booking in separate steps. |

## Before you start

- A **Crisphive account** where you are the **Owner**, or have **Developer** access (needed to create API keys; by default only the Owner has it).
- A **Retell account** (sign in at dashboard.retellai.com; Google sign-in works). A new account starts on a free trial, and the typed test in Step 6 works without a card. Calls are billed by Retell, so check its pricing for your plan.
- A computer with a modern browser. A microphone is only needed if you also test by voice; a phone number only to go live.
- **A default duration on every job type the agent may book** (Crisphive: **Settings → Job Types**). The default type “General” already has one.
- About **30 minutes**.

## Retell facts that shape the setup

- **Header authentication only.** Retell has no OAuth sign-in for MCP servers, so you type the API key into a header — **including the word Bearer**, which Retell does not add for you.
- **No automatic retries.** If a tool call fails, Retell does not try again; the prompt tells the agent to apologise and say the team will call back. Give Crisphive time with a 20-second timeout.
- **Tools are added one at a time.** Each Crisphive tool is added with its own **Add Tool** dialog.
- **Tool answers are capped at 15,000 characters.** Crisphive’s voice answers fit: the largest measured, `getJobRequest`, is about 6,500 characters (a job with a crew of several technicians is larger).
- Retell reads the tool list with POST requests. If your IT team watches the logs, a `405` on a GET request is normal: Crisphive does not offer SSE.

## Step 1 — Create the Crisphive API key

The key tells Crisphive which business the agent works for and what it may do. You create a test key now and a live key when you go live (see [Go live](https://docs.crisphive.com/docs/retell#go-live)).

1. **Switch to Rehearsal** — In the left sidebar of the Crisphive dashboard, click **Rehearsal** in the **Rehearsal | Live** switch, then click **Switch**. Rehearsal is Crisphive’s sandbox: isolated test data, and no real customer or technician is ever texted or emailed. A key created while you are in Rehearsal starts with `chsk_test_` and only ever touches the test data.
2. **Open API Keys** — Go to **Settings → Developer → API Keys** ([crisphive.com/app/settings/developer/api-keys](https://crisphive.com/app/settings/developer/api-keys)) and click **Create new API key**. Creating keys needs Developer access, which by default only the Owner has.
3. **Choose Secret and name the key** — Key type: **Secret**. Never **Publishable** — a publishable `chpk_` key is only for the booking widget on your website and is refused everywhere else. Name: `Retell voice agent`.
4. **Choose how long it lasts** — In **Expires in (days)** keep **30 days** for a test key. Keys always expire: 30 days by default, anything from 1 to 365 days chosen when you create the key. The Owner and Administrators are emailed 7 days before a key expires.
5. **Restrict it to booking** — Under **Scopes** choose **Restricted** and select `customers_view`, `customers_manage`, `job_view`, `job_create` and `job_manage`. Nothing else is needed for booking.
6. **Create and copy** — Click **Create API key**, then **Copy**, then **Done**. The full key is shown only once — paste it into your password manager. If you lose it, create a new key and revoke the old one.

Screen in Crisphive: **Create new API key** (`crisphive.com/app/settings/developer/api-keys`)

1. In Settings → Developer → API Keys, click Create new API key. Keep Key type on Secret — never Publishable. — **Key type**: `Secret`
2. Type the name Retell voice agent so you recognise the key later. — **Name**: `Retell voice agent`
3. Keep Expires in (days) on 30 days for a test key. You can choose up to 365 days. — **Expires in (days)**: `30 days`
4. Under Scopes choose Restricted and select customers_view, customers_manage, job_view, job_create, job_manage. — **Selected scopes**: `customers_view, customers_manage, job_view, job_create, job_manage`
5. Click Create API key. — click **Create API key**
6. Click Copy. The key starts with chsk_test_ and is never shown again. Then click Done. — click **Copy**

## Step 2 — Create the agent

1. **Create your workspace** — On a new Retell account, the **Create your workspace** screen asks for a **Workspace name** and “What best describes you?” (**Business**, Agency, Developer, Other). Choose **Business**, answer “How large is your call center team?” and click **Continue**. You can **Skip** “How did you hear about us?”.
2. **Skip Conductor** — The next screen, **Conductor**, offers to “generate a ready-to-deploy voice agent” from your website. Click **Skip**: a generated agent carries its own prompt, which does not follow the booking rules.
3. **Create a voice agent** — In the left navigation click **Agents**, open the **Create an Agent** dropdown and choose **Voice Agent**.
4. **Choose Single prompt** — In the **Create agent** dialog, **Conversational flow** is selected by default — switch the type to **Single prompt**.
5. **Start from scratch** — Choose the **Build from scratch** card (“Start with a blank agent”), not a template or **Generate from prompt** — their instructions would conflict with the booking rules. Click **Create agent**.

Screen in Retell: **Create agent** (`dashboard.retellai.com/agents`)

1. In Create your workspace, enter a name and choose Business, then Continue. Skip the Conductor screen. — **What best describes you?**: `Business`
2. In Agents, open the Create an Agent dropdown and choose Voice Agent. — **Create an Agent**: `Voice Agent`
3. Switch the type from Conversational flow to Single prompt. — **Type**: `Single prompt`
4. Choose Build from scratch, then click Create agent. — click **Create agent**

## Step 3 — Write the agent’s instructions

The agent page shows the agent’s name, a version (**V0**) and the buttons **Test**, **Conductor** and **Publish** at the top. Below them a row holds the model, the voice and the language; then a large prompt box and the **Welcome Message**. The right column holds Functions, Knowledge Base & Memory, Speech settings and further down **MCPs**; the test panel (**Test Audio** / **Test LLM**) is on the far right. Changes save automatically (“Auto saved at …”), but callers only get them after you publish.

1. **Paste the prompt** — Paste the prompt below into the prompt box. Replace every `[Business name]` (in the prompt and the first message), `[city]` (for example “Ottawa, Canada”) and `[timezone]` — your business’s IANA timezone, for example `America/Toronto`. `[timezone]` appears three times: in the first line and twice in step 5. The timezone matters most: Crisphive reads every time as your business’s local clock.
2. **Let the agent speak first** — **Welcome Message** starts on **User speaks first**. Change it to **AI speaks first**.
3. **Set a custom greeting** — A second dropdown appears, set to **Dynamic message**. Choose **Custom message** and paste the greeting below into the box that appears, with your business name in place of `[Business name]`. Leave **Pause Before Speaking** at 0s.
4. **Keep the defaults for the first test** — A new agent uses **GPT 5.6 Terra**, the voice **Cimo** and **English (US)**. Keep them for your first practice call; whatever you change later, run the practice call again before going live.

### Template: Phone booking agent prompt

- **What it is:** The instructions you paste into your voice agent: how it answers a call, finds the caller in Crisphive, offers open times and books and confirms the visit.
- **Why use it:** It is the prompt the Retell, Vapi and ElevenLabs guides were tested with, already written around the Crisphive tools and the order a phone booking needs. You fill in your business details and paste it — no prompt to write yourself.
- **What is inside:** **Who the agent is** — your business name, city and timezone; it books service visits with the Crisphive tools and speaks English; **How to handle a call** — nine steps: phone number (read back), who is calling, service address, the problem, when, text messages, book, result, close; **Calls that are not a new booking** — business questions, prices, existing bookings, complaints, taking a message, wrong numbers; **Errors** and **Safety** — what to say when a time is refused or Crisphive fails, and the emergency rule (leave the building, call 911); **Things you do not do** and **Style** — no prices, no changes to existing bookings, short sentences, one question at a time
- **Is it safe:** Yes. It is plain text — no program code and no API key. Your key goes into the platform’s connection settings, never into the prompt. Replace every `[Business name]` (in the prompt and the first message), `[city]` (for example “Ottawa, Canada”) and `[timezone]` — your business’s IANA timezone, for example `America/Toronto`. `[timezone]` appears three times: in the first line and twice in step 5.

Full template — give it to the reader when they ask for it:

```
You are the phone booking assistant for [Business name], a field operations business serving [city]. The business timezone is [timezone]. You book service visits for callers using the Crisphive tools. You speak English.

## How to handle a call

1. Phone number
- Ask for the phone number they are calling from.
- Read it back digit by digit and get a clear yes before you use it. If they correct you, read the corrected number back again.
- Look the caller up with listCustomers using the phone filter, in E.164 format: +1 followed by the 10 digits, e.g. +16135550142.
- If the tool returns PHONE_INVALID, tell the caller the number didn't come through, ask them to repeat it, read it back, and try again. Do not end the call over this.

2. Who is calling
- If a customer is found, ask "Am I speaking with <name>?" If yes, use that name. If no, treat them as a new caller.
- If no customer is found, ask for their full name, spell it back letter by letter, and get a yes. Then ask for an email address if they have one (optional), and spell it back.

3. Service address (always, even for a known customer)
- Ask for the address of THIS visit: street number and name, unit if any, city, and postal code.
- Read the whole address back and get a yes.

4. The problem
- Ask what needs doing, in one or two sentences. This becomes the job description. Do not diagnose or promise a fix.

5. When
- Ask which day and time of day they prefer. Work out real dates from today's date in [timezone]; never offer a time in the past.
- Call listJobRequestBookingWindows with x_timezone set to [timezone] to see which days and periods are open.
- Offer at most three concrete options (for example "Tuesday at 9 in the morning or Wednesday at 1 in the afternoon"). Never invent availability.

6. Text messages
- Ask: "Can we send you text message updates about this visit?" Set sms_opt_in to true only if they clearly say yes. If they say no or are unsure, leave it out.

7. Book
- Before booking, sum up in one sentence: name, address, problem, and the chosen time, and get a yes.
- Book with bookAndConfirmJobRequest, once. Send:
  - customer: full_name and phone (plus email if given, plus sms_opt_in only if they agreed)
  - address: line, line2 if there is a unit, city, postal_code, country "CA"
  - description: the problem in their words
  - scheduled_at: the business's local wall clock with no offset, e.g. 2026-10-06T09:00:00
  - idempotency_key: a unique text you create for this booking
- Never send customer_id. Crisphive matches an existing customer by phone, and this makes sure the visit uses the address the caller just gave.
- If the tool timed out or gave no answer, resend the exact same request with the SAME idempotency_key.
- If you change anything in the request (for example after fixing the time or the address), use a NEW idempotency_key.

8. Result
- If "confirmed" is true: say the visit is booked and read back the day, date, time and address. You may give the booking reference (short_code), read slowly.
- If "confirmed" is false: say "I've saved your request. Our team will call you back shortly to confirm the exact time." Do not book again and do not promise a time.

9. Close
- Ask if there is anything else about this visit, thank them, and end the call.

## Calls that are not a new booking
- Questions about the business (opening hours, areas served, services offered): answer only from information you have been given. If you do not know, say so and offer to take a message. Never guess.
- Price questions: say the team will discuss pricing, then offer to book a visit or take a message.
- An existing booking (when the technician is coming, changing the time, cancelling): you cannot look up or change existing bookings. If you can transfer calls, offer to transfer the caller to the team; otherwise take a message.
- A complaint, or the caller asks for a person: transfer the call if you can; otherwise take a message.
- Taking a message: get their name, their phone number (read it back), and what they need in one sentence. Tell them the team will call them back, then end the call politely.
- Wrong numbers, sales calls and spam: say politely that this line is for booking service visits and end the call.

## Errors
- If the chosen time is refused as invalid or in the past, apologise, offer another time, and book again with a NEW idempotency_key.
- For any other error_code, apologise briefly, say the team will call them back, and end politely. Never read error codes or technical details aloud.

## Safety
- If the caller mentions a gas smell, smoke, fire, sparking, flooding near electricity, or anyone being hurt, tell them to leave the building and call 911 now. Do not book in that situation.

## Things you do not do
- Never quote prices or give estimates. Say the team will discuss pricing.
- Never change or cancel an existing booking yourself (see "Calls that are not a new booking").
- Never share information about other customers, technicians, or the schedule beyond the times you offer.
- Never mention tools, systems, JSON, or that you are looking things up in a database. Say "one moment" while you check.

## Style
- This is a phone call: short sentences, one question at a time.
- Say numbers, dates and times the way people speak them ("Tuesday the sixth at nine in the morning").
- Be warm and calm. If you did not understand, ask them to repeat.
```

```
Thanks for calling [Business name]. I can book a service visit for you. Can I start with the phone number you're calling from?
```

> Replace `[timezone]` in all three places (the first line and twice in step 5): the agent uses it to understand “tomorrow at 10”. Test with “tomorrow” before going live.

Screen in Retell: **Agent** (`dashboard.retellai.com/agents`)

1. Paste the Crisphive prompt into the prompt box and fill in your business name, city and timezone. — **Prompt**: `You are the phone booking assistant for [Business name], a field operations business serving [city]. …`
2. Change Welcome Message from User speaks first to AI speaks first. — **Welcome Message**: `AI speaks first`
3. Switch Dynamic message to Custom message, and paste the greeting. — **Custom message**: `Thanks for calling [Business name]. I can book a service visit for you. Can I start with the phone number you're calling from?`

## Step 4 — Connect the agent to Crisphive

1. **Open Add MCP** — In the right column of the agent page open **MCPs** (“Enable your agent with capabilities of MCPs”) and click **Add MCP**. The **Add MCP** dialog opens.
2. **MCP name and URL** — **MCP name**: `crisphive`. **URL**: `https://api.crisphive.com/mcp/voice`. The URL field is masked like a password; the eye icon shows what you typed.
3. **Timeout (ms)** — Change the default 10000 to **20000** (20 seconds). Retell does not retry a failed call, so leave Crisphive room on a busy moment.
4. **Headers** — Under **Headers** click **New key value pair**. Key: `Authorization`. Value: `Bearer chsk_test_…` typed in full — the word `Bearer`, exactly one space, your key, and no space at the end. Retell does **not** add “Bearer” for you.
5. **Save** — Leave **Query Parameters** empty and click **Save**. The MCP card **crisphive** now shows **Tools** and an **Add Tools** button.

Screen in Retell: **Add MCP** (`dashboard.retellai.com/agents`)

1. In the agent’s right column, open MCPs and click Add MCP. — click **Add MCP**
2. Set MCP name to crisphive and URL to https://api.crisphive.com/mcp/voice. — **URL**: paste your own key (never share it in this chat)
3. Change Timeout (ms) from 10000 to 20000. — **Timeout (ms)**: `20000`
4. Under Headers, click New key value pair and enter the key Authorization. — **Headers — key**: `Authorization`
5. Set its value to Bearer, one space, then your chsk_test_ key — typed in full. Then click Save. — **Headers — value**: paste your own key (never share it in this chat)

On the crisphive MCP card click **Add Tools**. In the **Add Tool** dialog, **Tool Access Scope** lists the ten Crisphive voice tools and takes one at a time, so open the dialog three times — once per tool below. Do not add the others, such as `confirmJobRequest`: the prompt does not use them.

| Tool Access Scope | Static Sentence (Talk While Waiting) |
| --- | --- |
| `listCustomers` | “One moment while I look that up.” |
| `listJobRequestBookingWindows` | “One moment while I check the schedule.” |
| `bookAndConfirmJobRequest` | “One moment while I book that for you.” |

1. **Pick the tool** — In **Tool Access Scope** select the tool. Leave **Store Fields as Variables** empty.
2. **Talk While Waiting** — Under **During Execution Feedback**, tick **Talk While Waiting**. Choose **Static Sentence** (not Prompt) and type the sentence from the table, so the caller hears something while Crisphive answers. Leave **Play typing sound** unticked.
3. **Talk After Action Completed** — **Talk After Action Completed** is ticked by default — keep it, then save. Repeat for the next tool.

Screen in Retell: **Add Tool** (`dashboard.retellai.com/agents`)

1. On the crisphive MCP click Add Tools and select listCustomers. Tick Talk While Waiting and enter the Static Sentence “One moment while I look that up.”. — **Tool Access Scope**: `listCustomers`
2. Add Tools again and select listJobRequestBookingWindows, with the Static Sentence “One moment while I check the schedule.”. — **Tool Access Scope**: `listJobRequestBookingWindows`
3. Add Tools again and select bookAndConfirmJobRequest, with the Static Sentence “One moment while I book that for you.”. — **Tool Access Scope**: `bookAndConfirmJobRequest`

The values to copy:

```
MCP name:           crisphive
URL:                https://api.crisphive.com/mcp/voice
Timeout (ms):       20000
Headers:
  Authorization     Bearer chsk_test_…     (chsk_live_… when you go live)
Query Parameters:   (none)

Tools (Add Tools, one at a time — Talk While Waiting → Static Sentence):
  listCustomers                  “One moment while I look that up.”
  listJobRequestBookingWindows   “One moment while I check the schedule.”
  bookAndConfirmJobRequest       “One moment while I book that for you.”
```

## Step 5 — Publish

1. **Publish** — When all three tools are listed under the MCP, click **Publish** at the top. In the dialog, **Version Name** and **Version Description** are optional; click **Publish**.

## Step 6 — Test it

In the test panel on the right of the agent page, open **Test LLM** and choose **Manual Chat** (“Manually chat with the agent”). It worked on a free trial without a card; Retell shows its price per message on the card. The agent sends the greeting; you type the caller’s side. Use a made-up number in the 555 range of a real area code and an address **inside one of your Crisphive service areas**. 613-555-01xx numbers are reserved for fiction, and Crisphive never sends texts or emails to 555 numbers or to `example.com` addresses.

This is what our test chat looked like (the number belonged to a customer already in our Rehearsal data):

| Caller typed | Agent answered |
| --- | --- |
| 613 555 0188 | *Six one three, five five five, zero one eight eight. Is that right?* |
| Yes | *One moment while I look that up.* Then *Am I speaking with Sam Tremblay?* |
| Yes | Asks for the address, including the street number, city and postal code. |
| 300 Bank Street, Ottawa, K2P 1X8 | Reads the address back, then asks what needs doing. |
| Loud furnace noise | Asks which day and time suit you. |
| Next Friday morning around 10 | *One moment while I check the schedule.* Then offers *Friday, October 16th at 10 am*. |
| Yes | Asks whether it may send text message updates about the visit. |
| Yes | Reads back the whole summary — name, address, problem and time. |
| Yes, book it | *One moment while I book that for you.* Then *Your visit is booked for Friday, October 16th at 10 in the morning … Your reference is R-E-Q, C-A, K-R-V-F-G-N-9-B.* |

To hear the agent, open **Test Audio** instead, click **Run Test** and allow the browser to use your microphone. Run a spoken test before going live: a voice call behaves differently from a typed one (numbers and names are heard, not read).

**More calls worth trying before you go live:**

| Scenario | What should happen |
| --- | --- |
| **A new caller.** Call from a number Crisphive does not know (in Rehearsal, any other 613-555-01xx number, for example 613 555 0188). | The agent finds no customer, so it asks for your full name and spells it back, then asks for an email (optional) and spells it back. You do not create the customer first: Crisphive creates it automatically when the visit is booked. Call again from the same number and the agent asks “Am I speaking with …?” — Crisphive matched you by phone and never creates a second customer for the same number. |
| **A wrong number.** Give a number with one wrong digit, and when it is read back say “No, it’s 613 555 0177.” | The agent reads the corrected number back again and only looks it up after your yes. |
| **A number that cannot exist.** Give one digit too few (“613 555 017”) and say yes to the read-back. | Crisphive answers `PHONE_INVALID`. The agent says the number didn’t come through, asks you to repeat it, reads it back and tries again — it does not end the call. |

## Check the result

Each Crisphive step shows in the chat as **Tool called : *name*** and **Tool response : *name***, with a **Debug** link on every turn — the place to look when something goes wrong.

Success: the agent reads back the date, time and address, and only then says you are booked. In the Crisphive dashboard (still in Rehearsal), **Bookings** shows the new job (`REQ-CA-…`) with status **Confirmed**, the customer, the address, the day and time, and an assigned technician.

## Fallback: custom functions (only if MCPs are unavailable)

**MCPs is the way to connect Retell to Crisphive, and it works** — we connected it on production. Use custom functions only if your agent has no **MCPs** section. Only three of the voice tools can be custom functions: `createCustomer`, `createJobRequest` and `bookAndConfirmJobRequest`. Retell never lets the AI fill in a query parameter or a part of the URL, so the tools that need one (`listCustomers`, `listJobTypes`, `listJobRequestBookingWindows`, `listMatchingSlots`, `getJobRequest`, and `quoteJobRequest` and `confirmJobRequest`, which need the job’s id in the URL) are not possible. The agent can still book, but cannot recognise returning callers or offer open times.

A minimal `bookAndConfirmJobRequest` function (POST, the Crisphive API, your key in the header):

```json
{
  "name": "bookAndConfirmJobRequest",
  "description": "Book, schedule and confirm a job in one call at scheduled_at (the business's local time, no offset). Returns confirmed true/false.",
  "http": {
    "method": "POST",
    "url": "https://api.crisphive.com/v1/job-requests/book-and-confirm",
    "headers": {
      "Authorization": "Bearer chsk_test_…"
    }
  },
  "parameters": {
    "type": "object",
    "properties": {
      "customer": {
        "type": "object",
        "properties": {
          "full_name": { "type": "string" },
          "phone": { "type": "string", "description": "E.164, e.g. +16135550177" },
          "email": { "type": "string" },
          "sms_opt_in": { "type": "boolean" }
        }
      },
      "address": {
        "type": "object",
        "properties": {
          "line": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "postal_code": { "type": "string" },
          "country": { "type": "string" }
        }
      },
      "scheduled_at": { "type": "string", "description": "e.g. 2026-10-06T10:00:00" },
      "description": { "type": "string" },
      "job_type_id": { "type": "string" }
    }
  }
}
```

> Do **not** add a fixed `Idempotency-Key` header to a custom function. Crisphive replays the first answer for a repeated key, so a key that never changes would make every later call return the first caller’s booking.

If you go this way, remove the `listCustomers` lookup from step 1 of the prompt (keep the read-back) and the `listJobRequestBookingWindows` call from step 5, and have the agent ask for a preferred time directly. A time nobody can take comes back as `confirmed: false` and the job waits in your queue.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Tool Access Scope** in Add Tool stays empty or loading, or every Crisphive call fails | Crisphive answered 401: the header value is wrong (missing `Bearer `, lowercase `bearer`, two spaces or a trailing space, a publishable or revoked key), or the MCP was edited without pressing **Update**. | Set the header to exactly `Authorization` = `Bearer chsk_…`, press **Update**, then reopen Add Tools. |
| Calls suddenly fail with 401 `API_KEY_EXPIRED` | The key reached its expiry date. | Create a new key, update the header value, press Update, then revoke the old key. |
| The tool list does not load, and the URL may be wrong | The URL field is masked, so a typo is easy to miss. | Click the eye icon and check it reads exactly `https://api.crisphive.com/mcp/voice`. |
| A `405` on a GET request in the logs | Normal: Retell lists tools with POST; Crisphive does not offer SSE. | Nothing to fix. |
| There is no prompt box, only a flow editor | The agent was created as a Conversational flow (the default type). | Create a new agent and choose **Single prompt**. |
| The agent waits in silence when the call starts | **Welcome Message** is still on **User speaks first** (the default). | Choose **AI speaks first**, then **Custom message**, paste the greeting and publish. |
| The agent ignores the booking rules | The agent was made by **Conductor**, **Generate from prompt** or a template, or the Crisphive prompt was changed. | Replace the whole prompt with the Crisphive prompt and publish again. |
| The agent has the prompt but never calls Crisphive | A tool was not added with Add Tools, or the agent was not published. | Add `listCustomers`, `listJobRequestBookingWindows` and `bookAndConfirmJobRequest`, then click **Publish**. |
| A tool call fails once and the agent gives up | Retell does not retry, or the timeout is too short. | Set **Timeout (ms)** to 20000; the prompt already says the team will call back. |
| Bookings land an hour (or a day) off | The prompt has the wrong timezone, or the agent sent a time with an offset (`400 JOB_REQUEST_INVALID_INPUT` with `data.means_locally`). | Replace `[timezone]` everywhere in the prompt. Times must be local wall clock without an offset, e.g. `2026-10-06T10:00:00`. |
| A tool answers 403 `API_KEY_SCOPE_INSUFFICIENT` | The key is restricted and lacks a scope the tool needs (named in `data.required_scope`). | Edit the key’s scopes in Crisphive (**Settings → Developer → API Keys**) to include all five booking scopes. |
| The job was created without an address | The agent booked with `customer_id` for a returning customer whose record has no address. | Use the system prompt unchanged: it always sends `customer` + `address`, and Crisphive matches the existing customer by phone. |
| The agent told the caller a time, but the job is not confirmed | Crisphive answered `confirmed: false` (the job was saved in your queue) and the prompt did not check it. | Keep step 8 of the prompt. Then confirm the job from the dashboard or call the customer. |
| `confirmed: false` with `refusal.error_code` `JOB_REQUEST_NO_TECHNICIAN_AVAILABLE` | Nobody who has the skills, covers that address and works at that hour is free. | Check the technicians’ working hours and service areas cover the address. The job waits in the coordinator queue — do not book it again. |
| The customer’s name is spelled wrong | Speech-to-text misheard it. | Keep step 2 of the prompt: the agent spells the name back letter by letter and waits for a yes. |
| `400 PHONE_INVALID` | The number was not sent in international format, or a digit was misheard. | The prompt sends E.164 (`+1` then ten digits) and, on `PHONE_INVALID`, asks the caller to repeat the number, reads it back and tries again (step 1). |
| The agent booked under a wrong number | Speech-to-text misheard a digit, and the number was used without being confirmed. | The prompt reads the number back before looking it up (step 1); make sure that step is in your prompt. |
| `400 JOB_REQUEST_QUOTE_INVALID` with `data.reason` `job_type_has_no_default_duration` | The job type the agent picked has no default duration. Nothing was created. | Set a default duration on that job type (**Settings → Job Types**), or book without a job type (“General” is used). |
| The customer got no text message | Crisphive only texts customers who agreed to SMS, and never texts 555 test numbers. | Expected. Real callers who say yes to texts get them; others get email. |
| Every custom-function booking returns the same old job | A fixed `Idempotency-Key` header is set on the function. | Remove that header. |

## Go live

1. **Prepare live data** — Switch the Crisphive dashboard to **Live**; check job type durations, technician hours, skills and service areas.
2. **Create a live key** — Create a Secret key in live mode (`chsk_live_…`) with the same five scopes; choose an expiry up to 365 days and set a reminder a week before. Owners and Administrators are also emailed 7 days before.
3. **Swap the header** — Edit the crisphive MCP in Retell, set the header value to `Bearer chsk_live_…`, press **Update** and **Publish** the agent.
4. **Connect a phone number** — See [Connect a phone number](https://docs.crisphive.com/docs/retell#phone-number) below.
5. **Place one real test call** — Book a visit for yourself, check it on the live board, then cancel it.

> To stop the agent at once, revoke its key in Crisphive (**Settings → Developer → API Keys** → Revoke access).

## Connect a phone number

Until now you talked to the agent in the browser. It answers real calls only once a phone number is attached to it. There are three ways:

1. **A number on Retell** — Retell sells US and Canadian phone numbers. Assign the number to the agent as the agent that answers incoming calls.
2. **Keep your business number and forward calls** — With your phone provider, forward calls from your existing business number to the agent’s number: always, when nobody answers, when the line is busy, or after hours. A good start is after-hours and missed calls only, so your team still answers during the day.
3. **Connect your phone system** — If your business has its own phone system, connect it over SIP. Retell supports SIP.

Numbers and call minutes are paid to Retell or your phone provider, not to Crisphive. Then call the number from your own phone and book a test visit.

## Calls that are not bookings

Not every caller wants a new visit. The prompt already tells the agent what to do with the other calls:

| What the caller asks | What the agent does |
| --- | --- |
| Opening hours, areas served, services offered | Answers only from information in its prompt. If it does not know, it says so and offers to take a message. Add your opening hours, areas and services to the prompt if you want it to answer these. |
| A price or an estimate | Says the team will discuss pricing, then offers to book a visit or take a message. |
| An existing booking: when the technician is coming, changing the time, cancelling | Cannot look up or change existing bookings. Transfers the call if it has a transfer tool (below); otherwise takes a message. |
| A complaint, or “can I speak to a person?” | Transfers the call if it can; otherwise takes a message. |
| A wrong number, a sales call or spam | Says the line is for booking service visits and ends the call politely. |
| Gas smell, smoke, fire, sparking, flooding near electricity, an injury | Tells the caller to leave the building and call 911. Does not book. |

A message is the caller’s name, phone number (read back) and what they need in one sentence. Two setups make sure these calls reach your team.

**Setup 1 — Transfer the call to a person.**

1. **Add the transfer tool** — In Retell, add a **Transfer Call** function to the agent.
2. **Set where calls go** — Set the destination to your office or coordinator phone number.
3. **Leave the prompt as it is** — The prompt already tells the agent when to transfer: a complaint, a caller who asks for a person, and questions about an existing booking. Save and publish the agent again.

> Outside office hours nobody answers a transferred call, so the agent should take a message instead. Add your office hours to the prompt, for example under “Calls that are not a new booking”: `Transfer calls only Monday to Friday, 8 am to 5 pm. Outside those hours, take a message.`

**Setup 2 — Get every message to your team.**

> A message the agent takes is **not** stored in Crisphive today: only bookings reach Crisphive. Set this up so that no call is lost.

1. **Capture the details of every call** — In the agent’s **Post call extraction** settings, add four fields to fill in after each call: the caller’s name, their phone number, the reason for the call and the message.
2. **Catch the summary with an automation** — In [Zapier](https://docs.crisphive.com/docs/zapier), [Make](https://docs.crisphive.com/docs/make) or [n8n](https://docs.crisphive.com/docs/n8n), start a new workflow with a webhook trigger that catches incoming data, and copy its web address.
3. **Send it after each call** — In Retell, paste that address as the post-call webhook, so Retell sends the call summary there when a call ends.
4. **Forward it to your team** — Add a step that sends the name, phone number, reason and message as an email or a Slack message to whoever calls customers back.
5. **Test it** — Make a practice call where you only leave a message, and check that it reaches your team.

## What it costs

- **Crisphive**: jobs booked by the agent count toward your Crisphive plan like any other job. The connection itself needs no add-on.
- **Retell**: calls are billed by Retell, so check its pricing for your plan. A new account starts on a free trial; the typed Manual Chat test worked on it without a card, and Retell shows its price per message on the card.
- **Phone line**: numbers and call minutes are paid to Retell or your phone provider, not to Crisphive.

## Related guides and reference

- [Voice agents overview](https://docs.crisphive.com/docs/voice-agents) — the voice tool set and booking rules
- [ElevenLabs](https://docs.crisphive.com/docs/elevenlabs) — a phone agent that books confirmed visits
- [Vapi](https://docs.crisphive.com/docs/vapi) — a phone assistant with the Crisphive MCP tool
- [MCP server reference](https://docs.crisphive.com/mcp) — every tool, the tool profiles and client setup
- [Book and confirm a job](https://docs.crisphive.com/technical-reference/book-and-confirm-job-request) — the API call behind every booking step

## FAQ

**Can a Retell agent book jobs in Crisphive?**

Yes. Add an MCP on the agent with the URL `https://api.crisphive.com/mcp/voice` and an `Authorization: Bearer chsk_…` header, then add the three tools with Add Tools.

**Can I test the booking without a phone number or a card?**

Yes. In the agent’s test panel open **Test LLM** and choose **Manual Chat**: you type the caller’s side and the agent books for real in your practice data. It worked on a free trial without a card.

**Do I type “Bearer” in the header value?**

Yes. Retell sends the header exactly as typed, so the value is `Bearer chsk_…` — the word Bearer, one space, the key. (Vapi is the opposite: it adds Bearer itself.)

**Does Retell support signing in to Crisphive instead of a key?**

No. Retell has no OAuth for MCP servers, so you use an API key in a header.

**Which kind of Crisphive key do I need?**

A **Secret** key — `chsk_test_` for practice, `chsk_live_` for real bookings. Publishable `chpk_` keys only work for the website booking widget.

**What can the agent do with my key?**

Only what its scopes allow. With the five booking scopes it can look up and create customers and book jobs, nothing else.

**Does a new caller have to exist in Crisphive first?**

No. When the number is not found, the agent asks the caller’s name (and email, if any), and Crisphive creates the customer when the visit is booked. Next time the same number finds the same customer — never a duplicate.

**Will Crisphive’s answers fit Retell’s 15,000-character limit?**

Yes for voice use. The largest measured answer, reading a job back, is about 6,500 characters; a job with a large crew is bigger.

**Why did the agent say the team will call back?**

Crisphive returned `confirmed: false`: the job is saved in your queue, but no technician could take that time. A coordinator schedules it.

**Can I use Retell custom functions instead of MCP?**

Only as a fallback when MCPs is not available: three tools (create customer, create job, book and confirm) can be custom functions. Caller look-up and open-time tools need MCP.

**How do I remove the agent’s access?**

Revoke its API key in Crisphive (**Settings → Developer → API Keys**). Keys also expire on the date you chose.