TimeZest Scheduling

TimeZest Scheduling

The "book a tech against this PSA ticket" workflow is what TimeZest exists for. This skill walks the canonical flow: resolve the agent, resolve the appointment type, create the scheduling request with the PSA association, then poll for the customer's response.

Anti-triggers

TimeZest schedules by sending the customer a link and letting them pick. Three neighbouring systems schedule by someone else picking:

• You already know the time and just need it on a calendar — write the event straight into the mailbox with m365-calendar. Creating a TimeZest request for a time already agreed sends the customer a pointless booking link.
• Dispatching a technician to a service window — the PSA service call is the record that carries dispatch and billing; use the autotask plugin (autotask-service-calls) or the equivalent PSA plugin. TimeZest links to that ticket, it does not replace it.
• Changing the ticket itself — status, notes, time entries, and assignment are PSA work (connectwise, halopsa, kaseya/autotask); TimeZest only attaches a booking to it.
• Configuring which slots are bookable — availability rules and durations live on the appointment type, not the request; use timezest-appointment-types.

API Tools

Resolve the actors

Manage scheduling requests

Common Workflows

Book a tech against a PSA ticket

1. Resolve the technician:
   • If a name was given, call timezest_agents_list and match.
   • If a team was given, call timezest_teams_list.
2. Resolve the appointment type:
   • Call timezest_appointment_types_list and pick the one that matches the ticket type (e.g. "Onsite Visit", "Remote Session").
3. Create the request:
   • Call timezest_scheduling_create_request with:
     • agent_id or team_id
     • appointment_type_id
     • associated_entities linking to the PSA ticket
4. Capture the returned scheduling request ID for follow-up.

Track a pending request

1. Call timezest_scheduling_get with the request ID.
2. Inspect the state to determine: sent / clicked / booked / canceled / expired.
3. If the request has been clicked but not booked after a reasonable window, surface that to the dispatcher — the link may need to be resent.

Cancel a request

1. Call timezest_scheduling_get to confirm current state.
2. Call timezest_scheduling_cancel to revoke the customer link.
3. Notify the originator (dispatcher or AM).

List recent activity

1. Call timezest_scheduling_list.
2. Group by status to give dispatch a queue view: how many sent, how many waiting on the customer, how many booked today.

Edge Cases

• No availability - If an agent has no slots in the requested window, TimeZest still creates a request but the customer will see "no times available". Surface the agent's calendar gap to the dispatcher.
• Multiple PSA systems - One MSP may run more than one PSA in parallel. Always set the correct associated_entities.type.
• Cancellation race - A customer may book a slot in the same second a dispatcher cancels. Always re-fetch state after a cancel call.

Best Practices

• Never create a scheduling request without a PSA association.
• Resolve agent and appointment_type by name through list calls in the same session; do not cache IDs across days.
• Treat the scheduling request as the source of truth, not the PSA ticket - the PSA only sees the booking after it is confirmed.

Related Skills

• api-patterns - Auth, polling, and PSA association