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
Alex needs help at the warehouse.
The loading-bay equipment has stopped working. Acme Equipment Care calls Alex about the open service request.
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:
- Confirm who answered and handle a wrong contact, callback request or language change.
- Capture what the contact needs and choose booking, dispatch or review.
- Connect your scheduling service to offer slots and reserve an agreed time.
- Check the service response before confirming the outcome to Alex.
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.
| Stage | What happens | Result used by the next stage |
|---|---|---|
| Answer and contact routing | Start with a neutral greeting; identify the requested contact and whether they can talk | Continue, explain the purpose, change language, request a callback, or end |
| Business authorization | Check the contact's access with the service company's verification procedure | scheduling_authorized from the business response |
| Service discovery | Ask about the service need and technician access without diagnosing equipment | service_issue, site_access, service_route, preferred_language |
| Visit booking | Read slots, confirm the selected time and access instructions, then reserve | A confirmed visit_id, an exception, or a dispatch request |
| Dispatch | Ask permission, try the primary number, then offer the backup after a confirmed failure | A confirmed transfer, a failed transfer, or an uncertain result |
| Follow-up | Send the unresolved request to the service system | An 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.
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.
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.
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
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.
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.
| Action | Required input | Example response and binding |
|---|---|---|
lookup_service_request | Request ID, known contact reference, verification answer | { "authorized": true, "equipment_summary": "Loading-bay equipment" }; map scheduling_authorized to $.authorized |
find_service_slots | Authorized 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_visit | Request 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_followup | Request 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:
- Create a new phone agent and retrieve its draft.
- Set
draft_idandexpected_revision, then replace the example URLs and secret reference. - Add
node.removeedits for the starter nodes, using their IDs from the draft. - Apply the template once. Its
node.createandcomponent.createedits require new IDs. - Validate the draft to check the model, voice, credentials and telephony.
- 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
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 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
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.
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
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.
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.
{
"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 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.
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 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 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.
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 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
| Scenario | What the test must establish |
|---|---|
| Wrong contact; repeated questions about the call | No site disclosure; the clarification path ends when contact remains unconfirmed |
| Contact asks for a callback | A requested window is recorded only when the service system accepts it |
| Spanish requested at the opening or during discovery | The correct language route and retained service context |
| Unsupported language | Assistance is offered without inventing language support |
| Verification denied or unavailable | No service discovery or booking write |
| Site access unconfirmed | The scheduling component is not entered |
| Contact requests urgent help or a dispatcher | Permission is requested before the configured transfer |
| Selected slot changes or is declined | No reservation of the previously proposed slot |
| Slot becomes unavailable at commit time | No appointment confirmation; review receives the proposed slot |
| Reservation is uncertain | Reconcile by run/effect/business reference before another write |
| Primary fails; backup succeeds | Two distinct effects; only the backup has a confirmed transfer result |
| Both transfers fail | Spoken fallback; no claim of a connected dispatcher |
| Transfer result is uncertain | No blind replay or automatic backup transfer |
| Follow-up accepted, rejected or uncertain | The spoken result matches the business response and effect state |
| Voicemail, phone menu and call screening | Correct 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.
{
"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.
















