Simulations & Testing
Identifying Simulations
Verify simulation calls and retrieve simulation details from your agent
Overview
When your agent receives calls during simulation testing, you may need to verify whether a call is from a Roark simulation and retrieve details about the specific test being executed. Roark provides a dedicated API endpoint to identify simulations based on phone numbers and call timing.Identifying Simulation Calls
Using the Simulation Job Lookup API
To verify if a call is coming from a simulated Roark agent or to retrieve simulation details, use the Lookup Simulation Job by Phone Numbers API. This API allows you to:- Verify if an incoming or outgoing call is part of a simulation test
- Retrieve the specific simulation job details
- Track which persona and scenario are being tested in the simulation
API Parameters
The API requires specific parameters to identify the simulation:| Parameter | Description | Usage |
|---|---|---|
| roarkAgentPhoneNumber | The Roark agent’s phone number | See direction-specific details below |
| callStartedAt | When the call was initiated | Must be within the simulation’s active window |
Understanding the roarkAgentPhoneNumber parameter
The roarkAgentPhoneNumber parameter depends on the call direction:
For Inbound Calls:
- Roark initiates the call from a dynamically provisioned number
- Your agent receives the call from this number
- In this scenario,
roarkAgentPhoneNumberis the number that dials your agent
- Roark provisions a number for each test case in a simulation
- When a simulation for a test case starts, this number is either sent via an HTTP request for your agent to trigger the outbound call, or manually dialed at runtime based on the number shown on the dashboard. See this page for more information.
- The Roark simulation agent receives this call and starts the simulation
- In this scenario,
roarkAgentPhoneNumberis the number you receive via the HTTP request, or the number displayed on the simulation run page for manual calls
Understanding the callStartedAt parameter
While a phone number is assigned to only one simulation at a time, once the simulation ends it may be reused for other simulations. As such, the callStartedAt timestamp is critical for matching the correct simulation:
- Timing Window: The call must occur within the simulation’s execution timeframe. Any time between the simulation test case starting and the call ending is valid.
- Default Value: Current date. This is useful when calling the endpoint to match a call in real-time (examples 1 and 2 below). For historical calls, you should pass the call creation time to match the correct call.
- Valid examples:
- Using current date as
callStartedAtwhenever you receive an inbound call from Roark in your agent’s inbound webhook (dependent on the provider) - Using current date as
callStartedAtwhenever you receive an HTTP request to trigger an outbound call for a Roark simulation. - Using any time between the above two options and the end time of the call.
- Using current date as
- Format: ISO 8601 timestamp (e.g.,
2024-01-15T14:30:00Z)
The
callStartedAt parameter helps distinguish between multiple simulations
that might use the same phone numbers at different times.Best Practices
Integration Recommendations
Link calls on your platform with Roark's simulation details
Link calls on your platform with Roark's simulation details
Use the data returned by the API to tag calls on your platform as test calls
and link directly to Roark’s test results
Use for Contextual Information
Use for Contextual Information
Leverage persona details to add context to your agent
Separate Test Traffic
Separate Test Traffic
Use simulation identification to segregate test data from production metrics
Add Conditional Logic
Add Conditional Logic
Implement test-specific behaviors when handling identified simulation calls