Source: https://docs.cumuluslabs.io/qualification-booking
Content version: 1f7d73b5

# Qualify a request and book the agreed next step

A prospective customer has requested a consultation. Before arranging it, your team needs to understand their use case and whether they need a specialist. The agent asks those questions, offers times from your calendar and confirms the details before booking.

Build the conversation in Studio and connect your calendar and CRM. The example records are fictional; your team supplies the endpoints and contact eligibility rules.

## Design the conversation around decisions {#flow}

For the business access check below, your endpoint decides whether the caller may see the record. If you need verification through a private telephone keypad, use [the private verification workflow](/docs/sdk-private) instead of collecting sensitive answers in the conversation.

![A qualification flow spanning interest, need discovery, extraction, routing, booking and CRM follow-up](https://docs.cumuluslabs.io/docs-assets/qualification-map.png)

Keep discovery and specialist routing in the main graph. Use a booking component for availability, confirmation and reservation. Return a confirmed appointment or an exception to the main flow, then update the CRM with the agreed next step.

| Stage | Information you need | Decision |
| --- | --- | --- |
| Introduction | Why the person requested contact; whether now is appropriate | Continue or end respectfully |
| Need discovery | Use case, existing system, scale and timeline | Gather the missing facts rather than guessing |
| Qualification | Structured fields with defined types and choices | Standard booking, specialist follow-up or further information |
| Availability | Slots returned by the calendar service | Offer only currently returned options |
| Confirmation | Selected time, time zone, attendees and requested service | Request the reservation only after explicit agreement |
| Business response | Reservation identifier and final state | Confirm completion or record an exception |
| CRM handoff | Agreed next step and the original run identity | Store an accurate outcome for the human team |

## Define qualification fields {#fields}

![An extraction node for use case, monthly volume, decision timeline and specialist need](https://docs.cumuluslabs.io/docs-assets/qualification-fields.png)

Define fields an operator can use: `use_case` as text, `monthly_volume` as a number, `timeline` as an enum, and `needs_specialist` as a boolean. Describe how to collect each field and handle an unknown answer.

Keep unknown fields unknown. Validate extracted values in your business service before using them to authorize a booking or other transaction.

![A branch selecting specialist follow-up or the normal booking path](https://docs.cumuluslabs.io/docs-assets/qualification-routing.png)

Use defined variables in the routing conditions and keep a default path. Route requests outside the standard offering to a specialist case.

## Separate calendar reads from reservation writes {#actions}

![Availability, booking, follow-up-ticket and CRM actions bound to the agent](https://docs.cumuluslabs.io/docs-assets/booking-action-list.png)

`find_availability` reads your calendar. `book_appointment` requests a reservation. `create_ticket` records a specialist or exception case. `update_crm` records the agreed outcome. Give reads and writes separate contracts and test mocks.

For example, the availability endpoint can return a stable `slot_id`, displayed local time and time zone. The reservation endpoint can accept that slot ID and a known contact ID, then return `{ "state": "confirmed", "appointment_id": "APPT-DEMO-24" }`. Define those fields in your calendar service and map them into flow variables.

The reservation service must validate the slot again at commit time: another person can take it after the agent reads availability. It must also honor the idempotency contract so a retry does not create a second appointment.

## Confirm before booking {#confirmation}

![The booking component's confirmation node with the transition for explicit agreement](https://docs.cumuluslabs.io/docs-assets/booking-confirmation.png)

Read back the selected time and time zone. Check the requested service and attendee details. Only the explicit confirmation transition should reach the reservation function.

Test “I need a different time,” “I am not ready to book,” a correction to the attendee and an ambiguous response. Check that each answer takes the intended transition in a simulation.

![The booking-result branch distinguishing confirmation from a review path](https://docs.cumuluslabs.io/docs-assets/booking-result-branch.png)

Map the business response into the variable the branch reads. Confirm only a successful reservation response. Route an unavailable slot to review. Reconcile a timeout or unknown result with the calendar before attempting another reservation.

## Configure the phone experience {#phone}

![Voicemail detection and the configured message for the consultation example](https://docs.cumuluslabs.io/docs-assets/booking-voicemail.png)

Set a voicemail message that explains the consultation follow-up and gives a callback route. Leave out account details and appointment confirmation.

![Call behavior settings for interruption, reminders, silence and maximum duration](https://docs.cumuluslabs.io/docs-assets/booking-call-behavior.png)

Set interruption behavior, silence handling and maximum duration for the use case. Use an authorized carrier call to check turn-taking, voicemail detection and number routing alongside text simulations.

## Supply the known context at admission {#request}

This example starts a run for a requested consultation. Pass the contact ID from your business system.

<!-- operation:runs.create -->
```json
{
  "channel": "phone",
  "agent_id": "qualification-booking",
  "to": "+14155550124",
  "from": "+14155550100",
  "dynamic_variables": {
    "business_name": "Acme",
    "contact_id": "LEAD-DEMO-24",
    "service": "technical_consultation",
    "timezone": "America/New_York"
  },
  "metadata": { "lead_reference": "LEAD-DEMO-24", "requested_contact": "true" }
}
```

Use [Start a run](/docs/reference/runs.create) with a retained `Idempotency-Key`. Confirm contact eligibility in your business system; metadata only records the supplied context. For inbound calls, configure the number and published agent as described in [Phone](/docs/phone).

## Test the booking and failure paths {#acceptance}

| Test case | Evidence to inspect |
| --- | --- |
| Person declines to continue | The call ends without a booking write |
| Required qualification field is unknown | The defined information/follow-up route is taken |
| Caller changes the selected time | The confirmed slot matches the final agreement |
| Slot becomes unavailable | No unsupported “you are booked” statement |
| Reservation response is uncertain | Reconciliation or review before another write |
| Specialist required | A case or agreed handoff is recorded with the run reference |

Use node/path assertions for structure, tool assertions for the expected action and a judged criterion for the confirmation conversation. Validate real availability, reservation and CRM contracts separately. Inspect [run-linked action receipts](/docs/investigate-runs#receipts) before treating a meeting as scheduled.

Store the appointment or follow-up identifier with the run ID in your CRM. If the reservation result is unclear, use those identifiers to reconcile it with the calendar service.

For an outbound example with contact and language changes, site-access checks and primary/backup dispatch transfers, follow [Equipment-service coordination](/docs/outbound-service).
