---
name: crisphive-vapi-setup
description: "Walks a Crisphive customer step by step through connecting Crisphive to Vapi. Vapi + Crisphive: connect the Crisphive MCP tool to a Vapi assistant 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 Vapi."
---

# Book field jobs by phone with Vapi

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

You are helping a Crisphive customer connect Crisphive to **Vapi**. 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/vapi (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 Vapi assistant 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. Vapi 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 Vapi one web address and one key.

## Three words you will meet

| Word | What it means in plain language |
| --- | --- |
| **Assistant** | Vapi’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 Vapi it is added as a **tool**. |
| **API key** | A long password that lets the assistant act for your business. It starts with `chsk_test_` (practice data) or `chsk_live_` (your real business), and Crisphive shows it once. In Vapi it is stored as a **credential**. |

## What the assistant can do

`/mcp/voice` gives the agent exactly the tools it needs on a phone call, which keeps each turn fast.

| Tool | What the assistant 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/vapi#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 **Vapi account** (sign in at dashboard.vapi.ai; Google sign-in works). A new account starts with a few free credits; calls are billed by Vapi, so check Vapi’s pricing for your plan.
- A computer with a **microphone** to test in the browser with **Talk**. A phone number is only needed to go live.
- **A default duration on every job type the assistant may book** (Crisphive: **Settings → Job Types**). The default type “General” already has one.
- About **30 minutes**.

## Step 1 — Create the Crisphive API key

The key tells Crisphive which business the assistant 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/vapi#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: `Vapi voice assistant`.
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 Vapi voice assistant so you recognise the key later. — **Name**: `Vapi voice assistant`
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 assistant

1. **Skip the Create an Agent screen** — After you sign in to the Vapi dashboard (dashboard.vapi.ai), it opens **Create an Agent** with **Inbound**, **Outbound**, **Support** and a box *“Or describe what you want to build”*. Do **not** click **Inbound**: it starts Vapi’s AI **Agent Builder** chat, which asks about your business and writes its own prompt — one that does not follow the booking rules. Close the screen with the **X** at the top right.
2. **Create Assistant** — In the left navigation click **Assistants**, then the green **Create Assistant** button. Vapi creates **New Assistant** straight away from a blank template. (A new account also has a sample assistant called **Riley**; leave it.)
3. **Find your way around the assistant page** — At the top: the assistant’s name and version, and the buttons **Composer**, **Talk** and **Publish**. Below: the tabs **Assistant**, **Logs**, **Tools**, **Analysis** and **Advanced**. The **Assistant** tab shows **Model Presets** (**Balanced** is selected), the **Transcriber**, **Model** and **Voice** cards, then **System prompt** and **First message**.
4. **Keep the defaults for the first test** — A new assistant uses **GPT-4.1** (OpenAI) in the Model card and the voice **Elliot** (Vapi) in the Voice card. Keep them for your first practice call; if a voice is hard to follow on the phone, try others in the Voice card. Whatever you change, run the practice call below again before going live.

## Step 3 — Write the assistant’s instructions

1. **Paste the system prompt** — The **System prompt** box holds Vapi’s placeholder *“This is a blank template with minimal defaults…”*. Select everything in it and paste the prompt below. 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. Do not click **Generate** — it rewrites the prompt.
2. **Paste the first message** — Under **First message**, replace *“Hello.”* with the greeting in the box below the prompt card, with your business name in place of `[Business name]`. The selector next to it already reads **Assistant speaks first** — keep it.
3. **Remember to publish** — Your changes stay a draft until you click **Publish** in Step 5.

### 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 assistant uses it to turn “tomorrow at 10” into a booking time. Test with “tomorrow” before going live.

Screen in Vapi: **Assistants › New Assistant** (`dashboard.vapi.ai/assistants`)

1. Close the Create an Agent screen with the X. In the left navigation click Assistants, then Create Assistant. — click **Create Assistant**
2. On the Assistant tab, replace the System prompt with the Crisphive prompt and fill in your business name, city and timezone. — **System prompt**: `You are the phone booking assistant for [Business name], a field operations business serving [city]. …`
3. Replace the First message “Hello.” with the greeting. Keep Assistant speaks first. — **First 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 assistant to Crisphive

Vapi stores your Crisphive key as a **credential**, and the Crisphive address as an MCP **tool** that uses it. The tool is created once, in Vapi’s tool library, and then attached to the assistant (the last part of this step).

> **Create the credential first.** The tool page has a **Create Credential** button, but it leaves the page for **Settings › Integrations**, and a tool name and Server URL you have not saved yet are lost. Make the credential below, then fill in the tool.

1. **Open the credential form** — Open **Settings › Integrations** (or click **Create Credential** on a tool page before typing anything there). In the **Server Configuration** dialog, click **Add Custom Credential**. The form **New Custom Credential** opens.
2. **Choose Bearer Token** — **Authentication Type** offers **OAuth 2.0** (the default), **HMAC** and **Bearer Token**. Choose **Bearer Token**. Not OAuth 2.0: Vapi’s OAuth form is a client-credentials flow that asks for a Token URL, Client ID and Client Secret, which is not how Crisphive keys work.
3. **Fill in the credential** — **Credential Name**: for example `Crisphive Rehearsal`. **Token**: paste **only** your key, `chsk_test_…` — without the word Bearer. **Header Name**: keep `Authorization` (it is prefilled). **Include Bearer Prefix**: keep it **on** (the default). Leave **Enable Encryption** as it is.
4. **Save the credential** — Save. Vapi shows *“Custom credential created successfully.”* and a card with your credential name and **Bearer Token • Authorization**.
5. **Create the MCP tool** — In the left navigation click **Tools**, then **Create Tool**. In the menu, under **INTEGRATIONS**, click **MCP**. The tool is created at once with the name `mcp_tool`.
6. **Name and address** — Under **Tool Settings**, set **Tool Name** to `crisphive` (the description is optional). Under **Server Settings**, set **Server URL** to `https://api.crisphive.com/mcp/voice` and leave **Timeout** at 20 seconds.
7. **Pick the credential** — Under **Authorization**, open the **Credential** dropdown (it shows *No authentication*) and pick your credential, listed as **Crisphive Rehearsal (Bearer Token)**. Vapi shows **Authentication enabled**. Leave HTTP Headers and Encrypted Paths empty.
8. **Keep Streamable HTTP** — Under **MCP Settings**, keep **Protocol** on **Streamable HTTP (SHTTP)** — the default — not Server-Sent Events (SSE).
9. **Publish the tool** — Click **Publish** on the tool page. The **Publish Tool** dialog shows what changed (step 1 of 2); click **Next**, optionally type a version name, and click **Publish**. The button now reads **Published**.

> **Vapi adds “Bearer ” for you.** With Include Bearer Prefix on, Vapi sends `Authorization: Bearer <your token>`. If you also type `Bearer` into the Token field, Crisphive receives `Bearer Bearer chsk_…` and answers 401. Paste the key alone.

The tool page also has a **Test** panel with **List MCP Tools**, but Vapi answers *“Streamable HTTP protocol is not supported in testing yet.”* That is expected: test the connection with a practice call in Step 6 instead.

Screen in Vapi: **Credential › Tool** (`dashboard.vapi.ai/tools`)

1. In the Server Configuration dialog, click Add Custom Credential. — click **Add Custom Credential**
2. Set Authentication Type to Bearer Token — not OAuth 2.0, the default. — **Authentication Type**: `Bearer Token`
3. Name the credential, and paste only your chsk_test_ key into Token — no “Bearer”. — **Token**: paste your own key (never share it in this chat)
4. Keep Header Name on Authorization and Include Bearer Prefix on. Then save. — **Include Bearer Prefix**: on
5. In Tools click Create Tool, and under INTEGRATIONS choose MCP. — **Create Tool**: `MCP`
6. Set Tool Name to crisphive and Server URL to https://api.crisphive.com/mcp/voice. — **Tool Name**: `crisphive`
7. Pick your Bearer Token credential under Authorization, keep Protocol on Streamable HTTP (SHTTP), then Publish. — **Credential**: `Crisphive Rehearsal (Bearer Token)`

1. **Add the tool to the assistant** — Open your assistant, go to its **Tools** tab and click **Add tool**. Tick **crisphive**. Its row shows the type **MCP** and **Assign Tool Version: Latest**, so the assistant always uses the newest published version of the tool.

Screen in Vapi: **Assistant › Tools** (`dashboard.vapi.ai/assistants`)

1. On the assistant’s Tools tab, click Add tool and tick crisphive. Keep the tool version on Latest. — **Tools**: `crisphive`

## Step 5 — Publish

1. **Publish** — Click **Publish** at the top of the assistant page, then **Next** and **Publish** in the dialog. The button reads **Published** and the version number goes up. The assistant only uses the tool, the prompt and the greeting after you publish.

Screen in Vapi: **Assistant › Tools** (`dashboard.vapi.ai/assistants`)

1. Click Publish, then Next and Publish in the dialog. — click **Publish**

## Step 6 — Test it

Click **Talk** at the top of the assistant page and allow the browser to use your microphone; the assistant speaks the first message. (The dropdown next to Talk also offers **Chat**, a typed test, but on a pay-as-you-go Vapi organisation it needs a card on file under **Settings › Billing**. Talk does not.) Play the caller using these made-up details — they are safe: 613-555-01xx numbers are reserved for fiction, and Crisphive never sends texts or emails to 555 numbers or to `example.com` addresses.

| You say | What should happen |
| --- | --- |
| “My number is 613 555 0177.” | It reads the number back digit by digit. Say “yes”, and it looks you up with `+16135550177`. In a fresh Rehearsal environment you are not found, so it asks for your name. |
| “Alex Martin. Email alex dot martin at example dot com.” | It spells the name back letter by letter (“A-L-E-X M-A-R-T-I-N?”), then the email. Confirm each. |
| “145 Laurier Avenue West, Ottawa, K1P 5J3.” | It reads the whole address back. Confirm. |
| “My furnace stopped heating.” | This becomes the job description. |
| “Monday morning, around ten.” | It checks real availability and offers at most three open times. |
| When it asks “Can we send you text message updates about this visit?”, answer “No.” | No SMS consent is recorded. (Answer “yes” on another test to see consent recorded.) |
| “Yes.” (to its one-sentence summary) | Before booking it sums up your name, address, problem and time and waits for your yes. Then it books once. |

**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 assistant 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 assistant 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 assistant 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 assistant 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

Success: the assistant reads back the date, time and address, and only then says you are booked. The Crisphive dashboard (still in Rehearsal) shows the job with status **Confirmed** (opened, its window is titled **Booking Confirmed**), the address `145 Laurier Avenue West, Ottawa` and an assigned technician, and Customers lists Alex Martin once. The assistant’s **Logs** tab shows each tool call and Crisphive’s answer; a good booking answer contains `"confirmed": true`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Every call to Crisphive answers 401 `API_KEY_INVALID` | The Token holds `Bearer chsk_…` while Include Bearer Prefix is on, so Vapi sends `Bearer Bearer chsk_…`. Or Include Bearer Prefix is off, so the word Bearer is missing. Or the key is publishable, revoked or has a stray space. | Edit the credential: Token = the key alone, Header Name = `Authorization`, Include Bearer Prefix on. Use a **Secret** key. |
| The credential form asks for a Token URL, Client ID and Client Secret | Authentication Type is set to OAuth 2.0. | Choose **Bearer Token** instead. |
| Calls suddenly fail with 401 `API_KEY_EXPIRED` | The key reached its expiry date. | Create a new key, paste it into the credential’s Token, then revoke the old key. |
| The assistant has no Crisphive tools in the call | The tool was created but not added on the assistant’s Tools tab, or the assistant was not published afterwards. | Repeat the last part of Step 4, then click **Publish** (Step 5). |
| The tool cannot connect, or the assistant is slow and hesitant | The Server URL is wrong, or is not the voice address. | Set the Server URL to exactly `https://api.crisphive.com/mcp/voice`. |
| Clicking **Inbound** starts a chat that asks for your business name | That is Vapi’s AI Agent Builder, which writes its own prompt. | Close it with the **X** and use **Assistants → Create Assistant** (Step 2). |
| The tool’s name and Server URL disappeared | You clicked **Create Credential** on the tool page before saving; it opens Settings › Integrations and drops unsaved changes. | Create the credential first, then fill in and publish the tool (Step 4). |
| **List MCP Tools** says *“Streamable HTTP protocol is not supported in testing yet.”* | Vapi’s tool test panel cannot test Streamable HTTP servers. | Expected. Keep Streamable HTTP and test with a **Talk** call instead (Step 6). |
| **Chat** says *“Payment method required”* | Typed tests need a card on file in pay-as-you-go Vapi organisations. | Use **Talk**, or add a card under **Settings › Billing**. |
| The assistant ignores the booking rules | The prompt was written by Vapi’s Agent Builder or **Generate**, or the Crisphive prompt was changed. | Replace the whole System prompt with the Crisphive prompt and publish again. |
| The assistant is hard to understand | The default voice. | Choose another voice in the **Voice** card and publish again. |
| Bookings land an hour (or a day) off | The prompt has the wrong timezone, or the assistant 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 assistant 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 assistant 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 assistant 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 assistant 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 assistant 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. |

## 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 calendar reminder a week before it; Owners and Administrators are also emailed 7 days before.
3. **Swap the key** — Click **Edit** on your Crisphive credential’s card (or create a new Bearer Token credential and pick it on the `crisphive` tool) and paste the `chsk_live_…` key into **Token** — still without the word Bearer. Publish the tool and the assistant again.
4. **Give the assistant a phone number** — See [Connect a phone number](https://docs.crisphive.com/docs/vapi#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 assistant at once, revoke its key in Crisphive (**Settings → Developer → API Keys** → Revoke access). Every Crisphive call fails from that moment.

## Connect a phone number

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

1. **A number on Vapi** — Vapi offers free US phone numbers, and can import a number you already have with Twilio, Telnyx or Vonage. Assign the number to the assistant as the assistant 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 assistant’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. Ask your phone provider for the SIP details to use.

Numbers and call minutes are paid to Vapi 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 assistant what to do with the other calls:

| What the caller asks | What the assistant 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 Vapi, add a tool of type **Transfer Call** to the assistant.
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 assistant when to transfer: a complaint, a caller who asks for a person, and questions about an existing booking. Save and publish the assistant again.

> Outside office hours nobody answers a transferred call, so the assistant 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 assistant 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 assistant’s **Analysis** 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 Vapi, paste that address as the post-call webhook, so Vapi 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 assistant count toward your Crisphive plan like any other job. The connection itself needs no add-on.
- **Vapi**: calls are billed by Vapi, so check Vapi’s pricing for your plan. A new account starts with a few free credits.
- **Phone line**: numbers and call minutes are paid to Vapi or your phone provider, not to Crisphive.

A short test call costs very little: ours used 0.05 of the free credits a new Vapi account starts with.

## 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
- [Retell](https://docs.crisphive.com/docs/retell) — a phone agent with the Crisphive MCP server
- [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 Vapi assistant book jobs in Crisphive?**

Yes. Create an MCP tool in Vapi with the URL `https://api.crisphive.com/mcp/voice` and a Bearer Token credential holding your `chsk_…` key, add it on the assistant’s Tools tab and publish.

**Should the credential be OAuth 2.0 or Bearer Token?**

Bearer Token. Vapi’s OAuth 2.0 option is a client-credentials flow (Token URL, Client ID, Client Secret); a Crisphive voice agent uses a secret API key.

**Do I type “Bearer” in front of the key?**

No. Paste the key alone into Token and keep **Include Bearer Prefix** on; Vapi adds “Bearer ” itself. Typing it too sends “Bearer Bearer …”, which Crisphive refuses.

**Why the /mcp/voice address?**

Vapi imports every tool a server offers, and `/mcp/voice` offers exactly the tools a phone agent needs, which keeps each turn of the call fast.

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

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

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

Only what the scopes allow. With `customers_view`, `customers_manage`, `job_view`, `job_create` and `job_manage` it can look up and create customers and book jobs — nothing about your team, billing or settings.

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

No. When the number is not found, the assistant 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.

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

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

**Will customers get text messages?**

Only when the caller explicitly agrees and the assistant records it. Otherwise confirmations go by email when an address was given.

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

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