Book field jobs by phone with Vapi
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 up at vapi.ai). Calls are billed by Vapi; check Vapi’s pricing for your plan.
- A computer with a microphone to test in the browser. 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 (Step 7).
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.
Step 1 of 6In Settings → Developer → API Keys, click Create new API key. Keep Key type on Secret — never Publishable.
All steps
- 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 an Inbound assistant
In the Vapi dashboard (dashboard.vapi.ai) create a new agent. The Create an Agent screen offers Inbound, Outbound and Support, plus a box where you describe what you want to build. Choose Inbound.
Do not type into the “describe what you want to build” box: Vapi’s AI would write its own prompt, and it would not follow the booking rules. You paste Crisphive’s prompt in the next step.
The assistant page has the tabs Assistant, Logs, Tools, Analysis and Advanced, and the buttons Composer, Talk and Publish at the top. The Assistant tab holds the Transcriber, Model and Voice cards, then System prompt and First message.
The default model in the Model card booked our production test job; you can keep it. Whichever model you choose, run the practice call below before going live.
The default voice can be hard to understand on a call. In the Voice card, try a few voices and choose one that is easy to follow.
Step 3 — Paste the prompt and the first message
In the System prompt editor (the Visual or the Code view), replace everything with 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.
Set First message to the greeting in the second box below, with your business name in place of [Business name], and choose Assistant speaks first.
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?
[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.Step 1 of 3On the Create an Agent screen choose Inbound. Leave the describe box empty.
All steps
- On the Create an Agent screen choose Inbound. Leave the describe box empty.
- On the Assistant tab, paste the Crisphive prompt into System prompt and fill in your business name, city and timezone.
- Paste the greeting into First message and choose Assistant speaks first.
Step 4 — Create the Crisphive MCP tool
The tool is created once, in Vapi’s tool library, and then attached to the assistant (Step 5).
In the left navigation click Tools, then Create Tool, and choose MCP.
Enter crisphive.
Enter https://api.crisphive.com/mcp/voice.
For authentication, open the Server Configuration dialog and click New Custom Credential.
Authentication Type offers OAuth 2.0, 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: on. Leave Enable Encryption as it is.
Save the credential, then save the tool.
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.Step 1 of 7In the left navigation click Tools, then Create Tool, and choose MCP.
All steps
- In the left navigation click Tools, then Create Tool, and choose MCP.
- Name the tool crisphive.
- Enter the Server URL https://api.crisphive.com/mcp/voice.
- In the Server Configuration dialog, click New Custom Credential.
- Set Authentication Type to Bearer Token — not OAuth 2.0.
- Name the credential, and paste only your chsk_test_ key into Token — no “Bearer”.
- Keep Header Name on Authorization and turn Include Bearer Prefix on. Then save.
Step 5 — Attach the tool and publish
Open your assistant, go to its Tools tab and add the crisphive tool.
Click Publish at the top. The assistant only uses the tool and the new prompt after you publish.
Step 1 of 2On the assistant’s Tools tab, add the crisphive tool.
All steps
- On the assistant’s Tools tab, add the crisphive tool.
- Click Publish.
Step 6 — Test it with a practice call
Click Talk at the top of the assistant page and allow the browser to use your microphone. 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. |
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.
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. |
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 Step 5, then click Publish. |
| 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. |
| The assistant ignores the booking rules | Vapi wrote its own prompt from the describe box, 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. |
Step 7 — 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.
Edit the credential on the crisphive tool (or create a new one) and paste the chsk_live_… key into Token — still without the word Bearer. Publish 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.
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
FAQ
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.