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.

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