Tag: n8n

Tools in Vapi! A Step-by-Step Full Guide – What are Tools? How to Set Up with n8n? by Henryk Brzozowski walks you through why tools matter, the main tool types, and how to build and connect your first tool with n8n. Umm, it’s organized with timestamps so you can jump to creating a tool, connecting n8n, improving and securing tools, and transferring functions. You’ll get a practical, hands-on walkthrough that keeps things light and useful.

You’ll also see concrete tool examples like searchKB for knowledge queries, checkCalendar and bookCalendar for availability and bookings, sendSMS for links, and transferCustomerCare for escalations, plus the booking flow that confirms “You’ve been booked” to close calls. Uhh, like, that makes it easy to picture real setups. By the end, you’ll know how to set up, secure, and improve tools so your voice AI agents behave the way you want.

What are Tools in Vapi?

Tools in Vapi are the mechanisms that let your voice AI agent do more than just chat: they let it take actions. When you wire a tool into Vapi, you extend the agent’s capabilities so it can query your knowledge base, check and create calendar events, send SMS messages, or transfer a caller to human support. In practice, a tool is a defined interface (name, description, parameters, and expected outputs) that your agent can call during a conversation to accomplish real-world tasks on behalf of the caller.

Definition of a tool in Vapi and how it extends agent capabilities

A tool in Vapi is a callable function with a strict schema: it has a name, a description of what it does, input parameters, and a predictable output shape. When your conversational agent invokes a tool, Vapi routes the call to your integration (for example, to n8n or a microservice), receives the result, and resumes the dialog using that result. This extends the agent from purely conversational to action-oriented — you can fetch data, validate availability, create bookings, and more — all in the flow of the call.

Difference between built-in functions and external integrations

Built-in functions are lightweight, internal capabilities of the Vapi runtime — things like rendering a small template, ending a call, or simple local logic. External integrations (tools) are calls out to external systems: knowledge APIs, calendar providers, SMS gateways, or human escalation services. Built-in functions are fast and predictable; external integrations are powerful and flexible but require careful schema design, error handling, and security controls.

How tools interact with conversation context and user intent

Tools are invoked based on the agent’s interpretation of user intent and the current conversation context. You should design tool calls to be context-aware: include caller name, timezone, reason for booking, and the agent’s current hypothesis about intent. After a tool returns, the agent uses the result to update the conversational state and decide the next prompt. For example, if checkCalendar returns “busy,” the agent should ask follow-up questions, suggest alternatives, and only call bookCalendar after the caller confirms.

Examples of common tool use cases for voice AI agents

Common use cases include: answering FAQ-like queries by calling searchKB, checking available time slots with checkCalendar, creating callbacks by calling bookCalendar, sending a link to the caller’s phone using sendSMS, and transferring a call to a human via transferCustomerCare. Each of these lets your voice agent complete a user task rather than just give an answer.

Overview of the Core Tools Provided

This section explains the core tools you’ll likely use in Vapi and what to expect when you call them.

searchKB: purpose, basic behavior, and typical responses

searchKB is for querying your knowledge base to answer user questions — opening hours, product details, policies, and so on. You pass a free-text query; the tool returns relevant passages, a confidence score, and optionally a short synthesized answer. Typical responses are a list of matching entries (title + snippet) and a best-effort answer. Use searchKB to ground your voice responses in company documentation.

checkCalendar: purpose and input/output expectations

checkCalendar verifies whether a requested time is available for booking. You send a requestedTime parameter in the ISO-like format (e.g., 2024-08-13T21:00:00). The response should indicate availability (true/false), any conflicting events, and optionally suggested alternative slots. Expect some latency while external calendar providers are queried, and handle “unknown” or “error” states with a friendly follow-up.

bookCalendar: required parameters and booking confirmation flow

bookCalendar creates an event on the calendar. Required parameters are requestedTime, reason, and name. The flow: you check availability first with checkCalendar, then call bookCalendar with a validated time and the caller’s details. The booking response should include success status, event ID, start/end times, and a human-friendly confirmation message. On success, use the exact confirmation script: “You’ve been booked and I’ll notify Henryk to prepare for your call…” then move to your closing flow.

sendSMS: when to use and content considerations

sendSMS is used to send a short message to the caller’s phone, typically containing a link to your website, a booking confirmation, or a pre-call form. Keep SMS concise, include the caller’s name if possible, and avoid sensitive data. Include a clear URL and a short reason: “Here’s the link to confirm your details.” Track delivery status and retry or offer alternatives if delivery fails.

transferCustomerCare: when to escalate to a human and optional message

transferCustomerCare is for handing the caller to a human team member when the agent can’t handle the request or the caller explicitly asks for a human. Provide a destination (which team or queue) and an optional message to the customer: “I am transferring to our customer care team now 👍”. When you transfer, summarize the context for the human agent and notify the caller of the handover.

Tool Definitions and Parameters (Detailed)

Now dig into concrete parameters and example payloads so you can implement tools reliably.

searchKB parameters and example query payloads

searchKB parameters:

• query (string): the full user question or search phrase.

Example payload: { “tool”: “searchKB”, “parameters”: { “query”: “What are your opening hours on weekends?” } }

Expected output includes items: [ { title, snippet, sourceId } ] and optionally answer: “We are open Saturday 9–2 and closed Sunday.”

checkCalendar parameters and the expected date-time format (e.g., 2024-08-13T21:00:00)

checkCalendar parameters:

• requestedTime (string): ISO-like timestamp with date and time, e.g., 2024-08-13T21:00:00. Include the caller’s timezone context separately if possible.

Example payload: { “tool”: “checkCalendar”, “parameters”: { “requestedTime”: “2024-08-13T21:00:00” } }

Expected response: { “available”: true, “alternatives”: [], “conflicts”: [] }

Use consistent date-time formatting and normalize incoming user-specified times into this canonical format before calling the tool.

bookCalendar parameters: requestedTime, reason, name and success acknowledgement

bookCalendar parameters:

• requestedTime (string): 2024-08-11T21:00:00
• reason (string): brief reason for the booking
• name (string): caller’s full name

Example payload: { “tool”: “bookCalendar”, “parameters”: { “requestedTime”: “2024-08-11T21:00:00”, “reason”: “Discuss Voice AI demo”, “name”: “Alex Kowalski” } }

Expected successful response: { “success”: true, “eventId”: “evt_12345”, “start”: “2024-08-11T21:00:00”, “end”: “2024-08-11T21:30:00”, “message”: “You’ve been booked and I’ll notify Henryk to prepare for your call…” }

On success, follow that exact phrasing, then proceed to closing.

sendSMS parameters and the typical SMS payload containing a link

sendSMS parameters:

• phoneNumber (string): E.164 or region-appropriate phone
• message (string): the SMS text content

Typical SMS payload: { “tool”: “sendSMS”, “parameters”: { “phoneNumber”: “+48123456789”, “message”: “Hi Alex — here’s the link to confirm your details: https://example.com/confirm. See you soon!” } }

Keep SMS messages short, personalized, and include a clear call to action. Respect opt-out rules and character limits.

transferCustomerCare destinations and optional message to customer

transferCustomerCare parameters:

• destination (string): the team or queue identifier
• messageToCustomer (string, optional): “I am transferring to our customer care team now 👍”

Example payload: { “tool”: “transferCustomerCare”, “parameters”: { “destination”: “customer_support_queue”, “messageToCustomer”: “I am transferring to our customer care team now 👍” } }

When transferring, include a short summary of the issue for the receiving agent and confirm to the caller that the handover is happening.

Conversation Role and Prompting Best Practices

Your conversational style matters as much as correct tool usage. Make sure the agent sounds human, helpful, and consistent.

Persona: Hellen the receptionist — tone, phrasing, and allowed interjections like ‘Umm’ and ‘uhh’

You are Hellen, a friendly and witty receptionist. Keep phrasing casual and human: use slight hesitations like “Umm” and “uhh” in moderation to sound natural. For example: “Umm, let me check that for you — one sec.” Keep your voice upbeat, validate interest, and add small humor lines when appropriate.

How to validate interest, keep light and engaging, and use friendly humor

When a caller expresses interest, respond with enthusiasm: “That’s great — I’d love to help!” Use short, playful lines that don’t distract: “Nice choice — Henryk will be thrilled.” Always confirm intent before taking actions, and use light humor to build rapport while keeping the conversation efficient.

When to use tools versus continuing the dialog

Use a tool when you need factual data or an external action: checking availability, creating a booking, sending a link, or handing to a human. Continue the dialog locally for clarifying questions, collecting the caller’s name, or asking for preferred times. Don’t call bookCalendar until you’ve confirmed the time with the caller and validated availability with checkCalendar.

Exact scripting guidance for booking flows including asking for caller name and preferred times

Follow this exact booking script pattern:

1. Validate intent: “Would you like to book a callback with Henryk?”
2. Ask for name: “Great — can I have your name, please?”
3. Ask for a preferred time: “When would you like the callback? You can say a date and time or say ‘tomorrow morning’.”
4. Normalize time and check availability: call checkCalendar with requestedTime.
5. If unavailable, offer alternatives: “That slot’s taken — would 10:30 or 2:00 work instead?”
6. After confirmation, call bookCalendar with requestedTime, reason, and name.
7. On success, say: “You’ve been booked and I’ll notify Henryk to prepare for your call…” then close.

Include pauses and phrases like “Umm” or “uhh” where natural: “Umm, can I get your name?” This creates a friendly, natural flow.

Step-by-Step: Create Your First Tool in Vapi

Build a simple tool by planning schema, defining it in Vapi, testing payloads, and iterating.

Plan the tool: name, description, parameters and expected outputs

Start by writing a short name and description, then list parameters (name, type, required) and expected outputs (success flag, data fields, error codes). Example: name = searchKB, description = “Query internal knowledge,” parameters = { query: string }, outputs = { results: array, answer: string }.

Define the tool schema in Vapi: required fields and types

In Vapi, a tool schema should include tool name, description, parameters with types (string, boolean, datetime), and which are required. Also specify response schema so the agent knows how to parse the returned data. Keep the schema minimal and predictable.

Add sample payloads and examples for testing

Create example request and response payloads (see previous sections). Use these payloads to test your integration and to help developers implement the external endpoint that Vapi will call.

Test the tool inside a sandbox conversation and iterate

Use a sandbox conversation in Vapi to call the tool with your sample payloads and inspect behavior. Validate edge cases: missing parameters, unavailable external service, and slow responses. Iterate on schema, error messages, and conversational fallbacks until the flow is smooth.

How to Set Up n8n to Work with Vapi Tools

n8n is a practical automation layer for mapping Vapi tool calls to real APIs. Here’s how to integrate.

Overview of integration approaches: webhooks, HTTP requests, and n8n credentials

Common approaches: Vapi calls an n8n webhook when a tool is invoked; n8n then performs HTTP requests to external APIs (calendar, SMS) and returns a structured response. Use n8n credentials or environment variables to store API keys and secrets securely.

Configure an incoming webhook trigger in n8n to receive Vapi events

Create an HTTP Webhook node in n8n to receive tool invocation payloads. Configure the webhook path and method to match Vapi’s callback expectations. When Vapi calls the webhook, n8n receives the payload and you can parse parameters like requestedTime or query.

Use HTTP Request and Function nodes to map tool inputs and outputs

After the webhook, use Function or Set nodes to transform incoming data into the external API format, then an HTTP Request node to call the provider. After receiving the response, normalize it back into Vapi’s expected response schema and return it from the webhook node.

Secure credentials in n8n using Environment Variables or n8n Credentials

Store API keys in n8n Credentials or environment variables rather than hardcoding them in flows. Restrict webhook endpoints and use authentication tokens in Vapi-to-n8n calls. Rotate keys regularly and keep minimal privileges on service accounts.

Recommended n8n Flows for Each Tool

Design each flow to transform inputs, call external services, and return normalized responses.

searchKB flow: trigger, transform query, call knowledge API, return results to Vapi

Flow: Webhook → Parse query → Call your knowledge API (or vector DB) → Format top matches and an answer → Return structured JSON with results and answer. Include confidence scores and source identifiers.

checkCalendar flow: normalize requestedTime, query calendar provider, return availability

Flow: Webhook → Normalize requestedTime and timezone → Query calendar provider (Google/Outlook) for conflicts → Return available: true/false plus alternatives. Cache short-term results if needed to reduce latency.

bookCalendar flow: validate time, create event, send confirmation message back to Vapi

Flow: Webhook → Re-check availability → If available, call calendar API to create event with attendee (caller) and description → Return success, eventId, start/end, and message. Optionally trigger sendSMS flow to push confirmation link to the caller.

sendSMS flow: format message with link, call SMS provider, log delivery status

Flow: Webhook → Build personalized message using name and reason → HTTP Request to SMS provider → Log delivery response to a database → Return success/failure and provider delivery ID. If SMS fails, return error that prompts agent to offer alternatives.

transferCustomerCare flow: notify human team, provide optional handoff message to the caller

Flow: Webhook → Send internal notification to team (Slack/email/CRM) containing call context → Place caller into a transfer queue if available → Return confirmation to Vapi that transfer is in progress with a short message to the caller.

Mapping Tool Parameters to External APIs

Mapping is critical to ensure data integrity across systems.

Common data transformations: date-time normalization and timezone handling

Always normalize incoming natural-language times to ISO timestamps in the caller’s timezone. Convert to the calendar provider’s expected timezone before API calls. Handle daylight saving time changes and fallback to asking the caller for clarification when ambiguous.

How to map bookCalendar fields to Google Calendar or Outlook API payloads

Map requestedTime to start.dateTime, set an end based on default meeting length, use name as summary or an attendee, and include reason in the description. Include timezone fields explicitly. Example mapping: requestedTime -> start.dateTime, end = start + 30 mins, name -> attendees[0].email (when known) or summary: “Callback with Alex”.

Best practices for including the caller’s name and reason in events

Place the caller’s name in the event summary and the reason in the description so humans scanning calendars see context. If you have the caller’s phone/email, add as attendee to send a calendar invite automatically.

Design patterns for returning success, failure, and error details back to Vapi

Return a consistent response object: success (bool), code (string), message (human-friendly), details (optional technical info). For transient errors, include retry suggestions. For permanent failures, include alternative suggestions for the caller.

Scheduling Logic and UX Rules

Good UX prevents frustration and reduces back-and-forth.

Always check availability before attempting to book and explain to the caller

You should always call checkCalendar before bookCalendar. Tell the caller you’re checking availability: “Umm, I’ll check Henryk’s calendar — one sec.” If unavailable, offer alternatives immediately.

Use current time as guideline and prevent booking in the past

Use the current time (server or caller timezone) to prevent past bookings. If a caller suggests a past time, gently correct them: “Looks like that time has already passed — would tomorrow at 10:00 work instead?”

Offer alternative times on conflict and confirm user preference

When a requested slot is busy, proactively suggest two or three alternatives and ask the caller to pick. This reduces friction: “That slot is booked — would 10:30 or 2:00 work better for you?”

Provide clear closing lines on success: ‘You’ve been booked and I’ll notify Henryk to prepare for your call…’

On successful booking, use the exact confirmation phrase: “You’ve been booked and I’ll notify Henryk to prepare for your call…” Then ask if there’s anything else: “Is there anything else I can help with?” If not, end the call politely.

Conclusion

You now have a full picture of how tools in Vapi turn your voice agent into a productive assistant. Design precise tool schemas, use n8n (or your integration layer) to map inputs and outputs, and follow conversational best practices so Hellen feels natural and helpful.

Summary of the key steps to design, build, and integrate Vapi tools with n8n

Plan your tool schemas, implement endpoints or n8n webhooks, normalize inputs (especially date-times), map to external APIs, handle errors gracefully, and test thoroughly in a sandbox before rolling out.

Checklist of best practices to follow before going live

• Define clear tool schemas and sample payloads.
• Normalize time and timezone handling.
• Check availability before booking.
• Personalize messages with caller name and reason.
• Secure credentials and webhook endpoints.
• Test flows end-to-end in sandbox.
• Add logging and analytics for iterative improvement.

Next steps for teams: create a sandbox tool, build n8n flows, and iterate based on analytics

Start small: create a sandbox searchKB or checkCalendar tool, wire it to a simple n8n webhook, and iterate. Monitor usage and errors, then expand to bookCalendar, sendSMS, and transfer flows.

Encouragement to keep dialog natural and use the Hellen receptionist persona for better UX

Keep conversations natural and friendly — use the Hellen persona: slightly witty, human pauses like “Umm” and “uhh”, and validate the caller’s interest. That warmth will make interactions smoother and encourage callers to complete tasks with your voice agent.

You’re ready to build tools that make your voice AI useful and delightful. Start with a small sandbox tool, test the flows in n8n, and iterate — Hellen will thank you, and Henryk will be ready for those calls.

If you want to implement Chat and Voice Agents into your business to reduce missed calls, book more appointments, save time, and make more revenue, book a discovery call here: https://brand.eliteaienterprises.com/widget/bookings/elite-ai-30-min-demo-call