Connect Workiz to your AI Employee to enable automated service job scheduling and cancellation directly inside your Workiz account.
Prerequisites
An active Workiz account
Workiz API credentials (API Key and API Secret): Navigate to Settings > Integrations > API in your Workiz account to obtain these
At least one dispatcher-capable team member configured in Workiz
Create the Workiz project
Before configuring attributes, add the Workiz integration module to the customer's Builder. Follow the steps in Create a new project using these values:
Field | Value |
|
|
|
|
|
|
|
|
Ensure Auto update enabled is turned on, then click Create.
Once the project is created, click the three dots icon next to it and select Force Update Project to pull the latest module version.
Then click Publish all.
Set up Workiz attributes
Navigate to the Attributes page in the customer's Builder.
Type
workizin the search field and select Show Hidden to display all related attributes.Set the attributes listed in the table below, clicking Save after each.
Click Publish all.
Attribute | Required | Description |
| Yes | Workiz API key. Found in Settings > Integrations > API. |
| Yes | Workiz API secret. Found alongside the API key. |
| No | Job types available in Workiz. Auto-populated on publish — do not edit manually. |
❗❗ IMPORTANT
Do not modify workiz_job_types — it is populated automatically by the integration during the setup flow and should not be edited manually.
On publish, the setup flow synchronizes your Workiz dispatcher team and caches job type data into workiz_job_types.
Set up Booking attributes
On the Attributes page, type
bookingin the search field and select Show Hidden.Edit the following attributes, clicking Save after each change.
Click Publish all.
Attribute | Value |
Booking - Cancellation - Enabled |
|
Booking - Cancellation - Type |
|
Booking - Type |
|
Add a new Intent Type
On the Attributes page, navigate to the Intent Type Map - ITM (Business Onboarding Interview - BOI) attribute.
Replace the "Cancellation" Intent Type with the text below, then click Save and Publish all.
## **[T] Cancellation** Client wants to cancel a scheduled service job. ConvoAgent starts the scenario: "Cancel Reservation"
Add new Custom Agent Scenarios
On the Attributes page, navigate to the Custom Agent Scenarios attribute.
Add the following new scenarios, then click Save and Publish all.
## **Scenario 1:** "Schedule a Service Job"
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, gently guide the user toward scheduling a job 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 is not present, 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 you that the 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 the user's email address. ### **Step 1.9:** **CRITICAL STEP!!!** Submitting the job. 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 job request has not yet been submitted to the system. Suggest completing the booking first before switching to a different topic, otherwise the request 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 the booking was submitted, choose the scenario to proceed: - **If the conversation's initial inquiry was about modifying an existing job**: proceed with the **Cancellation** scenario, say something like: "Please let me know the date and time of your previous booking to proceed with the cancellation." - **If the conversation's initial inquiry was about creating a new job**: 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, 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 for the details of the booking (name, time, date, and phone number) the customer 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>
Test the integration
Call your AI Employee and try to schedule a service job. If successful, the job should appear in your Workiz account with the correct customer details and technician assignment.
To test cancellation, call your AI Employee and request to cancel an existing job. Verify the job status updates in Workiz accordingly.
Limitations
Feature | Status |
Availability checking | Not supported |
Rescheduling | Not supported |
Payment processing | Not supported |