Skip to main content

Housecall Pro

Updated this week

This guide explains how partners can configure the Newo.ai integration with Housecall Pro (HCP) and operate two core customer workflows: scheduling a new appointment and canceling an existing appointment.

Prerequisites

  • Housecall Pro MAX subscription.

  • Housecall Pro API key: Follow Housecall Pro’s article to obtain your API key.

Configure an HCP Newo.ai project

  1. On the Newo.ai Platform, navigate to your customers' Builder.
    ​

  2. Go to the Projects page and click the three dots icon in the top-right corner.

  3. Click Create New Project.
    ​

  4. Fill in the following fields and ensure Auto update enabled has been activated:

    • Idn: hcp

    • Title: hcp

    • Module: hcp_integration

  5. Click Create.
    ​

  6. Click the three dots icon next to the newly created Project.

  7. Click Force Update Project.
    ​

  8. Click Publish all.
    ​

Set up Housecall Pro attributes

  1. Navigate to the Attributes page.

  2. Type "hcp" into the search field and select Show Hidden to get a list of all related Housecall Pro attributes.
    ​

    ​

  3. The following attributes can be changed based on your customer's requirements:

    1. Assign Employee Automatically: Lets you auto-assign jobs to the most suitable employee based on Housecall Pro CRM tags (e.g., AC_install, Electrical). Tag each employee in Housecall Pro with the job types/services they handle; the integration picks a best-match when creating a job.

    2. Booking duration in hrs: Sets the length of the created appointment.

    3. Check existing client: When enabled, the integration searches Housecall Pro by phone number to find a matching customer before creating a new one. If found, their profile (name, email, address) is brought in so AI Employee doesn’t re-ask for details.

    4. For how many days get availability: Defines how many days beyond the requested date the integration should search for open time slots.

    5. Time Zone: Defines the company’s time zone and is used for all availability and scheduling calculations.

    6. Use events for autoselect: Uses events to mark employees as unavailable (e.g., day-off) during auto-assignment.

  4. Paste your HCP API key into the Housecall Pro API key attribute.

Important

Do not modify "static" attributes (for example, hcp_company_employees attribute).

Add a new Intent Type

  1. On the Attributes page, navigate to the "Intent Type Map - ITM (Business Onboarding Interview - BOI)" attribute.

  2. Replace the "Cancellation" Intent Type with the following:
    ​

    ## **[T] Cancellation**
    Client wants to cancel a scheduled visit.
    ConvoAgent starts the scenario: **"Cancel Reservation"**

  3. Click Save and Publish All.

Add new Custom Agent Scenarios

  1. On the Attributes page, navigate to the "Custom Agent Scenarios" attribute.

  2. Add the following new scenarios:
    ​

    ## **Scenario 1:** "Schedule an Appointment"

    Important!!! You should carefully check <ExistingCustomerInfo> for existing information.

    For all `Steps` use  information from <ExistingCustomerInfo> if it presents. Do not ask user to provide if it presents in <ExistingCustomerInfo>.

    ### **Step 1.1:**  Follow **Reconfirming or Gathering Service** procedure.

    ### **Step 1.2:** **CRITICAL STEP!!!** Checking provided service. Make sure that the requested service from the User is present in the **Products and Services** section. If you see such a service – say: "Yes, we provide this service... <Name the most suitable service from your list>". If you do not see a similar service in the **Products and Services** section – say: "You know, unfortunately we do not provide this service. We provide services such as... <Name the most suitable service from your list>."

    ### **Step 1.2.2:** If we do provide the requested service, then gently push the user towards making an appointment with [[project_business_name]] for the service. Example: "Could you please provide your zip code so I can check if we serve your area?"

    ### **Step 1.3:**  **CRITICAL STEP!!!** Checking provided area. Say the special **code-phrase**: **"Give me a moment to double-check if we serve your area. I will get back to you shortly."** If the user has provided their zip code. Check <ExistingCustomerInfo> for zip code, if it not presents - gently ask them to provide it.
    Clarifications:
    - If your last message in the `<ConversationHistory>` states "Give me a moment to double-check if we serve your area. I will get back to you shortly.", it means you are in the process of checking. In this case, every subsequent response must be: "Give me a moment, I will get back to you shortly."
    - If the **Base instruction** tells to let the User that their zip code is served: **code-phrase** **tell the user about the conditions and the diagnostic/estimation fee** using the `Terms and Conditions & House Rules` provided in the <BusinessContext> and the `needed service` category. Ensure that you provide the conditions exactly as they are. It is essential to inform the user about the service fee. Finish providing service conditions with **Reconfirming or Gathering User Name** procedure.

    ### **Step 1.4:** **CRITICAL STEP!!!** Follow  **Gathering Preferred Date and Time** procedure.

    ### **Step 1.5:** Follow **Gathering Availability Information** procedure.

    ### **Step 1.6:** Follow **Reconfirming or Gathering Phone Number** procedure.

    ### **Step 1.7:** Follow **Gathering Physical Address** procedure to get the User's address.

    ### **Step 1.8**  **CRITICAL STEP!!!** Follow **Reconfirming or Gathering Email Address** procedure to obtain User's email address.

    ### **Step 1.9:** **CRITICAL STEP!!!** Submitting the booking. Say the special **code-phrase**: **"I'm submitting your booking right now. Please give me a moment, and I'll get back to you shortly."** This is a required phrase — without it, the booking will not go through, so you must say it at this step.
    - If the user changes the conversational topic or inquiry during this step, let them know that the current reservation has not yet been submitted to the system. Suggest completing the booking first before switching to a different topic, otherwise the reservation will not be processed.
    - **If you need to clarify something, do so and after the User provides the needed information**, say **code-phrase**:  "Thanks. I'm submitting your booking right now. Please wait a moment, I'll get back to you shortly."
    You must **remain on this step** until you see a confirmation of successful booking from the booking system in the `<ActionsStates>` section. As soon as the confirmation arrives, proceed to the next step.
    If you receive an error message in `<ActionsStates>` from the booking system, apologize, inform the User that the booking system is temporarily unavailable, and proceed with the "Regular Transfer" scenario.

    ### **Step 1.10:** Once you see in <ActionsStates> that booking was submitted, choose the scenario to proceed:
    - **if the **conversation** initial inquiry was about modifying an existing reservation**: proceed with the **Cancellation** scenario, say something like: "Please let me know the date and time of your previous reservation to proceed with the cancellation".
    - **if the **conversation** initial inquiry was about creating a new reservation**: proceed with the **Finish Conversation** scenario.

    ---

    ## **Scenario 11:** "Cancel Reservation" 

    ### **Step 11.1:** Say the special **code-phrase**: **"Give me a moment to double-check if I have information about your bookings, I will get back to you shortly."**.

    ### **Step 11.2:** Wait for the response from the booking system, and based on that response, you have to decide how to proceed:
    <Case1 condition=**"The system can't find user bookings"**> 
    During Working Hours: ConvoAgent should say that they will transfer the call to a human co-worker and start the scenario: **"Regular Transfer"**.
    During Non-Working Hours: ConvoAgent should ask the details of the booking (name, time, date and phone number) the guest wants to cancel. Then, ConvoAgent should start the scenario: **"Relaying Message to the Manager"**.
    </Case1>

    <Case2 condition=**Booking system found user's reservation"**> Proceed with the next step.
    </Case2>

  3. Click Save and Publish All.
    ​

Set up Booking attributes

  1. On the Attributes page, type "booking" into the search field and select Show Hidden.

  2. Edit the following attributes (Save each one as you make edits):

    1. Booking - Cancellation - Enabled: Set to True.

    2. Booking - Cancellation - Type: Set to project.

    3. Booking - Check Availability - Enabled: Set to True.

    4. Booking - Check Availability - Type: Set to project.

    5. Booking - Type: Set to project.

    6. Booking - Create Booking - Schema: Add the below code snippet

      ?

  3. Click Publish All.
    ​

Test the integration

Call your AI Employee and try to schedule an appointment. If successful, you should see the appointment appear in Housecall Pro.

Related Articles
Agent success classification and assessment
Lead identification and Lead Value calculation
Configure the outbound caller
Cal.com
Did this answer your question?