Skip to content

Commit 0006b92

Browse files
margaritagomezmargaritagomez
authored
VAP-6545 Add docs for GoHighLevel calendar integration (#396)
feat: add docs for GoHighLevel calendar integration
1 parent 334fcb4 commit 0006b92

File tree

5 files changed

+226
-0
lines changed

5 files changed

+226
-0
lines changed

‎fern/docs.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,9 @@ navigation:
253253
- page: Slack
254254
path: tools/slack.mdx
255255
icon: fa-brands fa-slack
256+
- page: GoHighLevel
257+
path: tools/go-high-level.mdx
258+
icon: fa-light fa-arrow-up
256259
- section: Knowledge retrieval
257260
path: knowledge-base/knowledge-base.mdx
258261
icon: fa-light fa-book

‎fern/static/images/tools/gohighlevel-connect.png

29.1 KB
Loading

‎fern/static/images/tools/gohighlevel-create.png

405 KB
Loading

‎fern/static/images/tools/gohighlevel-select.png

72.9 KB
Loading

‎fern/tools/go-high-level.mdx

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
title: GoHighLevel Integration
3+
subtitle: "Connect your assistant to GoHighLevel for seamless appointment scheduling, contact creation, and availability checking."
4+
slug: tools/go-high-level
5+
---
6+
7+
The GoHighLevel integration empowers your Vapi voice agents to directly interact with your clients\' GoHighLevel calendars. Your agents can use a suite of tools to manage the appointment lifecycle: check if a contact already exists using the **Get Contact** tool, create new leads or clients with the **Create Contact** tool, query specific GHL calendars for open slots via the **Check Availability** tool, and secure appointments associated with a contact using the **Create Event** tool. This enables your voice agent to handle the entire booking process seamlessly within the GHL calendar that your agency or client already uses.
8+
9+
## Prerequisites
10+
11+
Before you can use the GoHighLevel integration, you need to:
12+
13+
1. Have a GoHighLevel account.
14+
2. Have a calendar in GoHighLevel to which you have permission to create and edit events.
15+
3. Have access to the Vapi Dashboard.
16+
17+
## Setup Steps
18+
19+
### 1. Connect GoHighLevel Account
20+
21+
First, you need to connect your GoHighLevel account to Vapi:
22+
23+
1. Navigate to the Vapi Dashboard.
24+
2. Go to **Providers Keys** > **Tools Provider** > **GoHighLevel**.
25+
3. Click the **Connect** button.
26+
4. A GoHighLevel authorization popup will appear.
27+
5. Follow the prompts to authorize Vapi to access your GoHighLevel account.
28+
29+
<Note>
30+
The authorization process will request access to your GoHighLevel account to
31+
manage contacts, calendars, and appointments.
32+
</Note>
33+
34+
<Frame caption="Connect GoHighLevel Account">
35+
<img
36+
src="../static/images/tools/gohighlevel-connect.png"
37+
alt="Connect GoHighLevel Account"
38+
/>
39+
</Frame>
40+
41+
### 2. Create GoHighLevel Tools
42+
43+
After connecting your GoHighLevel account, create the tools:
44+
45+
1. Go to **Dashboard** > **Tools** page.
46+
2. Click the **Create Tool** button.
47+
3. Select **GoHighLevel** from the available options.
48+
4. Choose which tool(s) you want to create (e.g., Get Contact, Create Contact, Check Availability, Create Event).
49+
5. For each tool, provide a name.
50+
6. For the **Check Availability** and **Create Event** tools, ensure you provide a valid `calendarId`. You can find the `calendarId` for each of your calendars in GoHighLevel by navigating to **Settings** > **Calendars**. Each calendar listed will display its unique ID.
51+
52+
<Note>
53+
When creating an event in GoHighLevel, a `contactId` is required. Therefore,
54+
if you plan to use the **Create Event** tool, you **must** also add the **Get
55+
Contact** and **Create Contact** tools. This allows the assistant to first
56+
retrieve an existing contact\'s ID or create a new contact, and then use that
57+
ID to schedule the event.
58+
</Note>
59+
60+
<Frame caption="Create GoHighLevel Tools">
61+
<img
62+
src="../static/images/tools/gohighlevel-create.png"
63+
alt="Create GoHighLevel Tools"
64+
/>
65+
</Frame>
66+
67+
### 3. Add Tools to Assistant
68+
69+
Now, add your chosen GoHighLevel tool(s) to your assistant. For an example scenario where you want your assistant to book appointments, including finding a suitable time and managing contact information, you would add all four tools: Get Contact, Create Contact, Check Availability, and Create Event.
70+
71+
1. Navigate to **Dashboard** > **Assistants** page.
72+
2. Select your assistant.
73+
3. Go to the **Tools** tab.
74+
4. In the tools dropdown, select the GoHighLevel tool(s) you want to use.
75+
5. Click **Publish** to save your changes.
76+
77+
<Frame caption="Add GHL Tools to Assistant">
78+
<img
79+
src="../static/images/tools/gohighlevel-select.png"
80+
alt="Add GHL Tools to Assistant"
81+
/>
82+
</Frame>
83+
84+
### 4. Configure Assistant System Prompt
85+
86+
After adding the GoHighLevel tools to your assistant, it\'s crucial to provide a clear system prompt. This prompt guides the assistant on how and when to use each tool to achieve the desired workflow. For a typical appointment booking scenario, your system prompt instructs the AI on the sequence of operations and conditions for using each tool.
87+
88+
Here\'s an example system prompt to guide your assistant. Remember to replace `ghl_contact_get`, `ghl_contact_create`, `ghl_check_availability`, and `ghl_create_event` with the exact names you gave your tools if they are different.
89+
90+
```text
91+
You are a helpful and efficient scheduling assistant. Your primary goal is to book appointments for users. Follow these steps carefully:
92+
93+
1. **Gather Information**: Start by asking for the caller\'s full name and email address.
94+
2. **Check Existing Contact**: Use the `ghl_contact_get` tool to see if a contact already exists with the provided email.
95+
3. **Create Contact (if needed)**: If no contact is found, use the `ghl_contact_create` tool to create a new contact with their name and email.
96+
4. **Discuss Appointment Time**: Once you have a contact ID (either from an existing contact or a newly created one), ask the user for their preferred date and time for the appointment.
97+
5. **Check Availability**: Use the `ghl_check_availability` tool to check for open slots. It\'s a good idea to check for the entire preferred day to offer alternatives if their initial request isn\'t available.
98+
6. **Confirm Time**: Discuss the available options with the user and agree on a suitable time.
99+
7. **Book Appointment**: Finally, use the `ghl_create_event` tool to book the appointment, ensuring you use the correct contact ID.
100+
101+
**Important Guidelines:**
102+
* Always use `ghl_contact_get` to check for an existing contact *before* attempting to create one with `ghl_contact_create`.
103+
* You *must* have a contact ID (from `ghl_contact_get` or `ghl_contact_create`) *before* you can book an appointment with `ghl_create_event`.
104+
* Always confirm availability with `ghl_check_availability` *before* attempting to book an appointment with `ghl_create_event`.
105+
```
106+
107+
## Tool Configurations
108+
109+
### GoHighLevel Get Contact Tool
110+
111+
This tool uses both or one of the following fields to retrieve an existing contact:
112+
113+
- `email`: The email address of the contact to search for.
114+
- `phone`: The phone number of the contact to search for.
115+
116+
### GoHighLevel Create Contact Tool
117+
118+
This tool uses the following fields to create a new contact:
119+
120+
- `firstName`: The first name of the contact.
121+
- `lastName`: The last name of the contact.
122+
- `email`: The email address of the contact.
123+
- `phone`: The phone number of the contact.
124+
125+
### GoHighLevel Check Availability Tool
126+
127+
This tool uses the following fields to check for open appointment slots:
128+
129+
- `calendarId`: The ID of the GoHighLevel calendar to check.
130+
- `startDateTime`: The start of the time range to check for availability (epoch time in milliseconds).
131+
- `endDateTime`: The end of the time range to check for availability (epoch time in milliseconds).
132+
- `timezone`: The timezone for the availability check (e.g., "America/New_York").
133+
134+
### GoHighLevel Create Event Tool
135+
136+
This tool uses the following fields to book an appointment:
137+
138+
- `calendarId`: The ID of the GoHighLevel calendar in which to create the event.
139+
- `contactId`: The ID of the GoHighLevel contact to associate with the event.
140+
- `title`: The title or summary for the calendar event.
141+
- `startDateTime`: The start date and time for the event in ISO 8601 format.
142+
- `endDateTime`: The end date and time for the event in ISO 8601 format.
143+
144+
## Example Usage
145+
146+
Here's how the tools can be configured in your assistant's JSON setup:
147+
148+
```json
149+
{
150+
"model": {
151+
"provider": "openai",
152+
"model": "gpt-4o",
153+
"messages": [
154+
{
155+
"role": "system",
156+
"content": "You are a highly efficient scheduling assistant for appointments. Your goal is to seamlessly book appointments into a calendar. Follow this precise workflow:\\n\\n1. **Gather User Info**: Start by politely asking for the caller's full name and email address.\\n2. **Check Existing Contact**: Use the 'getGHLContact' tool to check if a contact already exists with the provided email.\\n3. **Create New Contact (if necessary)**: If no contact is found with the email, use the 'createGHLContact' tool to create a new contact. You will need their name and email for this.\\n4. **Determine Appointment Needs**: Once you have a contact ID (either from an existing or newly created contact), ask the user for their preferred date and time for the appointment, and the purpose of the appointment (e.g., 'dental checkup', 'initial consultation').\\n5. **Check Calendar Availability**: Use the 'checkGHLAvailability' tool to find open slots for the requested period. Check a broad enough range (e.g., the entire day) to offer alternatives if the exact preferred time is unavailable.\\n6. **Confirm Time with User**: Discuss the available options and confirm a suitable appointment time with the user.\\n7. **Book the Appointment**: Use the 'createGHLEvent' tool to schedule the appointment. Use the purpose of the appointment as the event title.\\n\\n**Critical Notes:**\\n- Always use 'getGHLContact' before 'createGHLContact'.\\n- You MUST have a contactId before calling 'createGHLEvent'.\\n- Always use 'checkGHLAvailability' before 'createGHLEvent'.\\n- Assume all appointments are 30 minutes long unless specified otherwise by the user.\\n- Today's date is {{now}}."
157+
}
158+
],
159+
"tools": [
160+
{
161+
"type": "gohighlevel.calendar.availability.check",
162+
"function": {
163+
"name": "checkGHLAvailability",
164+
"description": "Use this tool to check for available appointment slots in the GoHighLevel calendar. Today's date is {{now}}."
165+
},
166+
"metadata": {
167+
"calendarId": "CALENDAR_ID",
168+
"timeZone": "America/New_York"
169+
}
170+
},
171+
{
172+
"type": "gohighlevel.calendar.event.create",
173+
"function": {
174+
"name": "ghl_create_event",
175+
"description": "Use this tool to create a new appointment (event) in the GoHighLevel calendar. Today's date is {{now}}. - All appointments are 30 minutes long unless specified otherwise by the user."
176+
},
177+
"metadata": {
178+
"calendarId": "CALENDAR_ID"
179+
}
180+
},
181+
{
182+
"type": "gohighlevel.contact.get",
183+
"function": {
184+
"name": "getGHLContact",
185+
"description": "Use this tool to retrieve an existing contact from GoHighLevel using the user's email address. This helps avoid duplicate entries."
186+
}
187+
},
188+
{
189+
"type": "gohighlevel.contact.create",
190+
"function": {
191+
"name": "createGHLContact",
192+
"description": "Use this tool to create a new contact in GoHighLevel."
193+
}
194+
}
195+
]
196+
}
197+
}
198+
```
199+
200+
## Best Practices
201+
1. **Clear Instructions**: Provide clear instructions in your assistant's system message about when to use each calendar tool
202+
2. **Error Handling**: Include fallback responses for cases where either calendar tool fails
203+
3. **Time Zone Awareness**: Always specify the correct timezone for events and availability checks
204+
4. **Event Details**: Ensure all required fields are properly filled when creating events
205+
5. **Availability Flow**: Check availability before attempting to schedule events to avoid conflicts
206+
6. **Contact Prerequisite for Events**: Remember that creating an event in GoHighLevel requires a `contactId`. Ensure your assistant\'s logic always fetches or creates a contact (using the `getGHLContact` and `createGHLContact` tools) before attempting to book an appointment with the `createGHLEvent` tool.
207+
208+
<CardGroup cols={2}>
209+
<Card
210+
title="Need Help?"
211+
icon="question-circle"
212+
href="https://discord.gg/pUFNcf2WmH"
213+
>
214+
Join our Discord community for support with GoHighLevel integration
215+
</Card>
216+
<Card
217+
title="API Reference"
218+
icon="book"
219+
href="/api-reference/tools/create"
220+
>
221+
View the complete API documentation for tools
222+
</Card>
223+
</CardGroup>

0 commit comments

Comments
 (0)