Skip to main content

Workiz integration

Updated today

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

Idn

workiz

Title

workiz

Registry

production

Module

workiz_integration

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

  1. Navigate to the Attributes page in the customer's Builder.

  2. Type workiz in the search field and select Show Hidden to display all related attributes.

  3. Set the following attributes based on the customer's requirements:

Attribute

Required

Description

workiz_api_key

Yes

Workiz API key. Found in Settings > Integrations > API.

workiz_api_secret

Yes

Workiz API secret. Found alongside the API key.

workiz_job_types

No

Job types available in Workiz. Auto-populated on publish — do not edit manually.

  1. Paste the API key into workiz_api_key and the API secret into workiz_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.

  1. 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

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

  2. Edit the following attributes, clicking Save after each change:

Attribute

Value

Booking - Cancellation - Enabled

True

Booking - Cancellation - Type

project

Booking - Type

project

  1. Click Publish all.

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 service job. 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 a Service Job"

    Important!!! You should carefully check

    for existing information.

    For all Steps use information from

    if 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 the Terms and Conditions & House Rules provided in the

    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

    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.

  3. 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

Did this answer your question?