CumulusDocs
Open Studio
On this page

Build an agent for service calls

Alex manages a warehouse where the loading-bay equipment has stopped working. Acme Equipment Care calls to arrange help. Alex needs a technician visit or a dispatcher, and the service team needs a clear record of what was agreed.

Build an agent that handles this conversation in Studio. It checks the contact, reads available visits from your scheduling service and requests a reservation only after agreement. If Alex asks for dispatch, it tries the configured transfer and handles a failed connection.

This example uses fictional people, business records and results. Your team supplies the service data and endpoints. Select the sandbox before building, and ask an admin to prepare the business-action secrets. Start with simulated callers and mock tool responses, then test your real endpoints and a controlled carrier call.

Start with the service request

Example service call

Alex needs help at the warehouse.

The loading-bay equipment has stopped working. Acme Equipment Care calls Alex about the open service request.

Cumulus agent
Calling for Acme Equipment Care
Help with the service request
Alex
Site contact
Warehouse · loading bay
Next in Studio: build these routes, connect the booking service, inspect the dispatch result, and test a change.

Alex can choose a technician visit, dispatch or follow-up. Each choice needs a different business result: a confirmed reservation, a connected dispatcher or an accepted follow-up request.

First build those routes. Then open a run where Alex asked for dispatch: the primary dispatcher was busy, so the agent asked permission to try the backup, which connected.

Build the conversation in Studio

Configure the flow in four steps:

  1. Confirm who answered and handle a wrong contact, callback request or language change.
  2. Capture what the contact needs and choose booking, dispatch or review.
  3. Connect your scheduling service to offer slots and reserve an agreed time.
  4. Check the service response before confirming the outcome to Alex.
Design an equipment-service workflow
Download video

The equipment-service agent's full main canvas, including contact, language, authorization, booking, dispatch and follow-up routes

The main flow handles contact checks and the choice of booking, dispatch or follow-up. Open the booking component to edit availability, confirmation and reservation together. Alex can ask for dispatch during booking; a failed reservation or transfer returns to follow-up.

StageWhat happensResult used by the next stage
Answer and contact routingStart with a neutral greeting; identify the requested contact and whether they can talkContinue, explain the purpose, change language, request a callback, or end
Business authorizationCheck the contact's access with the service company's verification procedurescheduling_authorized from the business response
Service discoveryAsk about the service need and technician access without diagnosing equipmentservice_issue, site_access, service_route, preferred_language
Visit bookingRead slots, confirm the selected time and access instructions, then reserveA confirmed visit_id, an exception, or a dispatch request
DispatchAsk permission, try the primary number, then offer the backup after a confirmed failureA confirmed transfer, a failed transfer, or an uncertain result
Follow-upSend the unresolved request to the service systemAn accepted followup_id or an unconfirmed request

Keep booking in its own component so you can change slot selection without editing contact or dispatch routing.

Handle contact changes without exposing site details

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 instead of collecting sensitive answers in the conversation.

The contact node with distinct transitions for confirmation, questions, a wrong contact, a callback, language and dispatch

Route the first answer explicitly. “Why are you calling?” gets a general explanation. “Wrong number” ends without site details. “Call me later” requests a callback through the service system. A dispatch request can reach the public dispatch route before service-record disclosure.

Allow one clarification after explaining the call. End if the contact remains unconfirmed, rather than repeating the opening question.

The language branch routing an explicitly extracted preference to Spanish, English or language assistance

Enable English and Spanish on the agent. Extract the person's requested language, then branch on preferred_language. The Spanish introduction confirms the contact in Spanish; unsupported languages lead to an offer of dispatch assistance. Test language changes in the middle of a conversation as well as at the opening.

The authorization branch allowing service discovery only after the business endpoint returns authorized access

lookup_service_request checks the contact using your verification procedure. Map its authorized response to scheduling_authorized. Only the true branch reaches service discovery; the default route stops disclosure and provides the public service number. Confirming a name is not sufficient authorization by itself.

Extract fields, then route on defined values

Extraction fields for the stated equipment issue, site access, requested route and language

Extract three fields for routing: service_issue records the reported problem; site_access records whether technician access is confirmed; service_route is dispatch, scheduling or review. Keep the agent focused on coordination rather than diagnosis or repair instructions.

The routing branch requiring both a scheduling route and confirmed site access before entering the booking component

Enter booking only when both service_route == scheduling and site_access == confirmed. Route a dispatch request to dispatch and all other values to follow-up. Test that the extraction step produces the intended values as well as checking the branch conditions.

Connect four business actions

Add these four services as named HTTP actions in Settings → Actions, then bind each function node to its action. Your team implements the endpoints; Cumulus calls them and maps their responses into flow variables. Configure the URL, method, input/output schemas, timeout and versioned credential reference; use Wait for result before a decision that needs the response. Follow the action setup steps.

ActionRequired inputExample response and binding
lookup_service_requestRequest ID, known contact reference, verification answer{ "authorized": true, "equipment_summary": "Loading-bay equipment" }; map scheduling_authorized to $.authorized
find_service_slotsAuthorized request ID, IANA time zone{ "state": "available", "slots_text": "SLOT-DEMO-24: 8 October 2026, 1:00 PM America/New_York" }; map slots_state to $.state and available_slots to $.slots_text
reserve_service_visitRequest ID, explicitly confirmed slot ID, agreed site-access notes{ "state": "confirmed", "visit_id": "VISIT-DEMO-24" }; map visit_state to $.state and visit_id to $.visit_id
record_service_followupRequest ID, reason, preferred language, business call reference{ "state": "accepted", "followup_id": "FOLLOWUP-DEMO-24" }; map followup_state to $.state and followup_id to $.followup_id

Response-variable bindings accept strings, numbers and booleans. The template uses response_variable_policy: "replace_available" so omitted or null optional fields clear an earlier value: an unavailable reservation cannot retain a previous visit_id. Return slot IDs and times as slots_text, a string that can be carried into the next node. The slot-selection prompt reads {{available_slots}}; it does not depend on the previous tool response remaining in conversation history. Return state: "unavailable" with empty slots_text when there are no visits to offer.

The business endpoints must enforce authorization and validate their inputs. The reservation endpoint rechecks availability when it commits and honors the effect's idempotency key. Store the run ID with your business reference so an operator can reconcile a timeout or an unclear response.

Use action.put in Edit a draft to set the endpoint, request/response schemas, credential reference and response bindings. Download the authoring request template for the complete flow: 30 main nodes, the 10-node booking component, actions, settings and canvas layout.

To use the template:

  1. Create a new phone agent and retrieve its draft.
  2. Set draft_id and expected_revision, then replace the example URLs and secret reference.
  3. Add node.remove edits for the starter nodes, using their IDs from the draft.
  4. Apply the template once. Its node.create and component.create edits require new IDs.
  5. Validate the draft to check the model, voice, credentials and telephony.
  6. Publish a test version with live: false. Test that version, then publish the reviewed configuration for regular calls.

Applying the template configures the draft. Publishing and placing a call are separate requests.

Confirm a visit before requesting the reservation

The booking component's explicit-confirmation node, with separate routes for agreement, changes and declining

Offer only slots returned by find_service_slots. Read back the selected time, time zone, service and access instructions. The “explicitly agree” transition is the only conversation route to reserve_service_visit. A correction returns to slot selection; a refusal goes to booking review.

The reservation-result branch leading to confirmation only for a confirmed business response

The reservation response determines the next step. confirmed reaches the receipt readback. unavailable and any other unconfirmed value reach review. Initialize visit_state to not_reserved in the draft so a fresh run cannot begin with a success value.

A timeout is not an unavailable slot. Inspect the action's effect state and reconcile an uncertain write with the service system before another reservation attempt. Test the configured failure behavior as well as ordinary non-confirmed responses; an HTTP error or lost response need not look like the example's successful JSON review response.

If the contact asks for dispatch while choosing a time, the component extracts visit_state = dispatch_requested and returns to the main graph's dispatch route. It does not create a reservation first.

Make transfer failures visible in the conversation

The primary transfer node with a configured dispatch destination and a failure route to the backup introduction

Ask permission, then transfer to {{dispatch_primary}}. A confirmed failure reaches the backup introduction. Ask again before trying {{dispatch_backup}}. Each transfer has its own node and receipt, so you can inspect the primary and backup attempts separately.

The spoken fallback node giving the public service number and offering follow-up after dispatch cannot connect

When both transfers fail, say that the handoff did not complete, give the public callback number, and offer a follow-up request. The agent reports a saved follow-up only after the business endpoint returns accepted. The default follow-up result explains that the request remains unconfirmed.

refer_accepted means the carrier accepted the transfer request; inspect the final phone.transfer phase and the call.transfer receipt to determine whether the handoff was confirmed. If the result remains uncertain, give your administrator or Cumulus the run ID, effect ID and call reference to investigate before another attempt. See Investigate a run.

Set answer, screening and voicemail behavior

Call behavior settings for answer timing, interruption, silence, reminders and maximum duration

The example waits for the person to answer, limits the call to ten minutes and ends after thirty seconds of silence. Start with a neutral fixed greeting when hang-up detection is enabled, then ask for the contact after human detection. Test interruptions during the time readback and dispatch permission question.

Studio's voicemail message and phone-menu hang-up policy for the equipment-service example

Voicemail leaves a general service message with a callback number. Phone-menu detection hangs up. The template also configures call screening through agent.settings: a screening assistant receives a short service-purpose line in English or Spanish, followed by a twenty-second wait for the contact.

json
{
  "type": "agent.settings",
  "values": {
    "screener": {
      "action": "play_line",
      "waitMs": 20000,
      "line": {
        "en": "Acme Equipment Care is following up on a requested service visit.",
        "es": "Acme Equipment Care llama sobre una visita de servicio solicitada."
      }
    }
  },
  "clear": []
}

Include this edit in a draft-edit request. Test voicemail, phone menus and screening using the actual audio/carrier path. Phone explains configuration and detection behavior.

Review the dispatch result

Open Calls & runs and select the run to check what happened after Alex asked for dispatch. Compare the two outcomes below: a connected backup dispatcher, or an accepted follow-up after neither dispatcher connected.

First transfer fails; backup is confirmed

Trace a dispatch handoff
Download video

Trace the dispatch request from the conversation through the executed path and both transfer receipts. Check the final result of each attempt before recording the handoff as complete.

Run effects showing a failed primary dispatch transfer and a successful backup transfer with its final SIP receipt

The primary effect is failed, with REFER 202 and final SIP 486. The backup is succeeded, with final SIP 200. Use the final transfer event and settled effect to confirm the connection.

The recorded node path reaching the backup transfer after the failed primary transfer

The path reaches primary_transfer, backup_intro and backup_transfer. Match those nodes to the two effects and check the publication version to identify the exact flow that ran.

Both transfers fail; follow-up is accepted

The transcript explaining both failed transfers and giving the accepted service follow-up reference

The agent explains the failed handoff and asks whether the contact wants follow-up. After the service endpoint accepts the request, it gives FOLLOWUP-DEMO-24. An accepted request still needs the service team's attention; it is not a completed dispatch conversation or a technician appointment.

Run effects with two failed transfer receipts and a separate follow-up HTTP effect

Inspect both transfer effects and the follow-up action separately. An HTTP 200 confirms the response was received; the response's business state and reference determine whether the service system accepted the follow-up.

The failed-dispatch path continuing through fallback, follow-up, accepted-result readback and end

The path continues through fallback, followup, followup_result, followup_saved and bye. If the business result is missing or uncertain, the run should not claim the follow-up was saved.

Test the routes before calling real contacts

ScenarioWhat the test must establish
Wrong contact; repeated questions about the callNo site disclosure; the clarification path ends when contact remains unconfirmed
Contact asks for a callbackA requested window is recorded only when the service system accepts it
Spanish requested at the opening or during discoveryThe correct language route and retained service context
Unsupported languageAssistance is offered without inventing language support
Verification denied or unavailableNo service discovery or booking write
Site access unconfirmedThe scheduling component is not entered
Contact requests urgent help or a dispatcherPermission is requested before the configured transfer
Selected slot changes or is declinedNo reservation of the previously proposed slot
Slot becomes unavailable at commit timeNo appointment confirmation; review receives the proposed slot
Reservation is uncertainReconcile by run/effect/business reference before another write
Primary fails; backup succeedsTwo distinct effects; only the backup has a confirmed transfer result
Both transfers failSpoken fallback; no claim of a connected dispatcher
Transfer result is uncertainNo blind replay or automatic backup transfer
Follow-up accepted, rejected or uncertainThe spoken result matches the business response and effect state
Voicemail, phone menu and call screeningCorrect audio behavior with no request-specific site disclosure

Use regression tests for conversation cases, node/path assertions and action mocks. Validate your business contracts and carrier transfers separately. Start with simulations, then call numbers you own. Keep the tested publication version fixed when comparing outcomes.

Start a test call with service context

After the simulation checks above, configure the carrier trunk and caller ID, wait for the number to become ready and confirm open run admission. Use an admin key or a member key with Can place calls enabled. Confirm that the tested publication's four HTTP actions point at authorized sandbox endpoints and use synthetic service records. If those settings need to change, edit the draft, publish another test version and rerun the cases. Browser tests and test: true phone runs do not mock those endpoints.

Send this body to Start a run with your API key and a retained Idempotency-Key. Replace the agent, version and resource identifiers with yours; use numbers you control for both the contact and dispatch destinations. test: true still places a real phone call and can perform real business actions and transfers.

<!-- operation:runs.create -->
json
{
  "channel": "phone",
  "agent_id": "equipment-service",
  "version": 3,
  "test": true,
  "to": "+14155550124",
  "from": "+14155550100",
  "dynamic_variables": {
    "business_name": "Acme Equipment Care",
    "contact_name": "Alex",
    "service_request_id": "SR-DEMO-24",
    "contact_reference": "CONTACT-DEMO-24",
    "call_reference": "CALL-DEMO-24",
    "timezone": "America/New_York",
    "preferred_language": "en",
    "dispatch_primary": "+14155550130",
    "dispatch_backup": "+14155550131",
    "dispatch_callback_spoken": "four one five, five five five, zero one three two"
  },
  "metadata": { "service_request_id": "SR-DEMO-24", "call_reference": "CALL-DEMO-24" }
}

Pass the request and contact references from your service system. Create call_reference before starting the run and store it with the returned run_id so follow-up can find the original call. Use configured dispatch numbers. Metadata links records; your business endpoint still checks access to the service request.

For the publication and promotion sequence, follow Release and operate an agent. For background processing of an unresolved service request, continue with After-call operations.

Content version 6ffaf7eaCustomer SDKMarkdown source
Build an agent for service calls · Cumulus developer docs