Book field jobs by phone with Vapi
AI 어시스턴트로 설정하기
- 무엇인가요
- 설정 파일: 이 Vapi 가이드를 ChatGPT, Claude 등 AI 채팅용 지시문으로 다시 쓴 것입니다.
- 왜 사용하나요
- 파일이 없으면 AI 어시스턴트는 Crisphive와 Vapi을 연결하는 방법을 기억에 의존해 추측할 뿐이며, 그 기억은 틀리거나 오래되었을 수 있습니다. 이 파일이 있으면 이 가이드 그대로 한 단계씩 안내하고, 어디까지 했는지 묻고, 무엇을 클릭할지 정확히 알려 주며, 결과를 함께 확인합니다.
- 들어 있는 것
- 이 페이지의 모든 단계(현재 화면, 버튼, 입력값 포함)
- 어시스턴트 규칙: 한 번에 한 단계, Rehearsal에서 시작, 마지막에 테스트
- 이 페이지와 Crisphive 지원으로 가는 링크
- 안전한가요?
- 네. 일반 텍스트(Markdown)로, 프로그램이 아니며 설치할 것도, 키도 없습니다. 저장하기 전에 미리 보기로 브라우저에서 읽어 볼 수 있습니다.
파일은 영어로 되어 있습니다. API 키나 비밀번호를 채팅에 붙여 넣지 마세요.
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). |
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).
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.
Go to Settings → Developer → API Keys (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.
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.
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.
Under Scopes choose Restricted and select customers_view, customers_manage, job_view, job_create and job_manage. Nothing else is needed for booking.
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.
6단계 중 1단계In Settings → Developer → API Keys, click Create new API key. Keep Key type on Secret — never Publishable.
모든 단계
- In Settings → Developer → API Keys, click Create new API key. Keep Key type on Secret — never Publishable.
- Type the name Vapi voice assistant so you recognise the key later.
- Keep Expires in (days) on 30 days for a test key. You can choose up to 365 days.
- Under Scopes choose Restricted and select customers_view, customers_manage, job_view, job_create, job_manage.
- Click Create API key.
- Click Copy. The key starts with chsk_test_ and is never shown again. Then click Done.
Step 2 — Create the assistant
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.
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.)
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.
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
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.
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.
Your changes stay a draft until you click Publish in Step 5.
Phone booking agent prompt
- 무엇인가요
- 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.
- 왜 사용하나요
- 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.
- 들어 있는 것
- 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
- 안전한가요?
- 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 exampleAmerica/Toronto.[timezone]appears three times: in the first line and twice in step 5.
Thanks for calling [Business name]. I can book a service visit for you. Can I start with the phone number you're calling from?
[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.3단계 중 1단계Close the Create an Agent screen with the X. In the left navigation click Assistants, then Create Assistant.
모든 단계
- Close the Create an Agent screen with the X. In the left navigation click Assistants, then Create Assistant.
- On the Assistant tab, replace the System prompt with the Crisphive prompt and fill in your business name, city and timezone.
- Replace the First message “Hello.” with the greeting. Keep Assistant speaks first.
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).
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.
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.
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.
Save. Vapi shows “Custom credential created successfully.” and a card with your credential name and Bearer Token • Authorization.
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.
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.
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.
Under MCP Settings, keep Protocol on Streamable HTTP (SHTTP) — the default — not Server-Sent Events (SSE).
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.
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.
7단계 중 1단계In the Server Configuration dialog, click Add Custom Credential.
모든 단계
- In the Server Configuration dialog, click Add Custom Credential.
- Set Authentication Type to Bearer Token — not OAuth 2.0, the default.
- Name the credential, and paste only your chsk_test_ key into Token — no “Bearer”.
- Keep Header Name on Authorization and Include Bearer Prefix on. Then save.
- In Tools click Create Tool, and under INTEGRATIONS choose MCP.
- Set Tool Name to crisphive and Server URL to https://api.crisphive.com/mcp/voice.
- Pick your Bearer Token credential under Authorization, keep Protocol on Streamable HTTP (SHTTP), then Publish.
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.
1단계 중 1단계On the assistant’s Tools tab, click Add tool and tick crisphive. Keep the tool version on Latest.
모든 단계
- On the assistant’s Tools tab, click Add tool and tick crisphive. Keep the tool version on Latest.
Step 5 — 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.
1단계 중 1단계Click Publish, then Next and Publish in the dialog.
모든 단계
- Click Publish, then Next and Publish in the dialog.
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
Switch the Crisphive dashboard to Live; check job type durations, technician hours, skills and service areas.
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.
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.
See Connect a phone number below.
Book a visit for yourself, check it on the live board, then cancel it.
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:
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.
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.
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.
In Vapi, add a tool of type Transfer Call to the assistant.
Set the destination to your office or coordinator phone number.
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.
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.
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.
In Vapi, paste that address as the post-call webhook, so Vapi sends the call summary there when a call ends.
Add a step that sends the name, phone number, reason and message as an email or a Slack message to whoever calls customers back.
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 — the voice tool set and booking rules
- ElevenLabs — a phone agent that books confirmed visits
- Retell — a phone agent with the Crisphive MCP server
- MCP server reference — every tool, the tool profiles and client setup
- Book and confirm a job — the API call behind every booking step
자주 묻는 질문
Can a Vapi assistant book jobs in Crisphive?
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?
Do I type “Bearer” in front of the key?
Why the /mcp/voice address?
/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?
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?
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?
Why did the assistant say the team will call back?
confirmed: false: the job is saved in your queue, but no technician could take that exact time. A coordinator schedules it from the dashboard.