This guide explains how partners can configure the Newo.ai integration with Workiz and operate two core customer workflows: scheduling a new service job and canceling an existing one.
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 following attributes based on the customer's requirements:
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. |
Paste the API key into
workiz_api_keyand the API secret intoworkiz_api_secret, clicking Save after each.
❗❗ IMPORTANT
Do not modify workiz_job_types — it is populated automatically by the integration during the setup flow and should not be edited manually.
Click Publish all.
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:
Attribute | Value |
Booking - Cancellation - Enabled |
|
Booking - Cancellation - Type |
|
Booking - Type |
|
Click Publish all.
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 following:
## [T] Cancellation Client wants to cancel a scheduled service job. ConvoAgent starts the scenario: "Cancel Reservation"
Click Save and Publish all.
Add new Custom Agent Scenarios
On the Attributes page, navigate to the Custom Agent Scenarios attribute.
Add the following new scenarios:
## Scenario 1: "Schedule a Service Job"
Important!!! You should carefully check
for existing information.
For all
Stepsuse information fromif it presents. Do not ask user to provide if it presents in
.
### 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...
". 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...
."
### 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
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 theTerms and Conditions & House Rulesprovided in theand the
needed servicecategory. 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
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:
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".
Proceed with the next step.
Click Save and Publish all.
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 |
