Skip to main content
An agent changes its behavior for two distinct reasons: because of what you say to it, and because of what its own system tells it about you. Authentication is the gate to that second axis — until the agent verifies who’s calling, it can’t look you up, so it can’t adapt to your account state, your tier, or your history. Many agents won’t do anything at all until they’ve authenticated the user: they ask for a phone number, a PIN, an account number, or a date of birth and verify it before continuing. To test that agent, your simulated user has to clear the same gate. This cookbook shows how to authenticate the simulated user — starting from a single fixed user, then varying the user (and therefore the backend state the agent sees) across test cases. There are two mechanisms for authenticating the simulated user:
  • In the conversation — the persona supplies the credentials when the agent asks for them, entering them on the keypad (DTMF) or saying them aloud. Works for every agent type.
  • Through the connection — you pass the user’s identity to the agent out of band, in a request header or payload, so your backend resolves the account before the first turn. Agent-type-specific; see Passing the user through the connection.
Whichever approach you use, the user you authenticate as must actually exist in your system, set up in the state your test needs. You’re impersonating a real record your agent can look up — not inventing one.

​
The simplest case: one QA user

If every test runs as the same user, you don’t need attributes or per-test-case setup. Put the credentials in a persona and use that persona for every simulation. This requires a QA user that already exists in your database with the right setup — a real record the agent can authenticate against. Create that account first (a real phone number and PIN the agent will accept), in whatever state your test needs. In the persona’s Persona Characteristics prompt, describe the credentials and exactly when to enter them. For a voice agent, the persona enters digits as DTMF tones with the dtmf tool rather than speaking them — spoken digits are prone to speech-to-text errors, and most IVRs expect keypad input anyway. Give it explicit, structured instructions:
Then launch all your simulations with this persona. Every run authenticates as the same user before the real test begins.

​
Varying the user per test case

To exercise that second axis — what the agent’s system tells it about you — authenticate as a different user in each test case, so the agent looks up different backend state each time. The first axis you drive through the conversation; this one you drive through which authenticated user you present as. For example, suppose your agent behaves differently depending on whether the caller already has an appointment. You’d want:
  • one test case that authenticates as a user who has already booked an appointment (the agent checks and sees it), and
  • one that authenticates as a user who has not — the same thing said, two different agent behaviors.
You don’t need a separate persona for each. Keep one persona and substitute the credentials with test-case attributes, so each test case supplies its own user:
Then each test case carries its own values. Test case — existing appointment:
Test case — no appointment:
Coval substitutes each test case’s values into the persona prompt before the call, so the same persona authenticates as a different real user on every run — and you observe how the agent’s behavior changes based on what its system knows about that user. Both of these users, again, must exist in your system in the state you’re testing for.

​
Passing the user through the connection

Sometimes you don’t want the user to authenticate in the conversation at all — you want the agent to already know who’s calling when the conversation starts. Most agent types let you pass the user’s identity (a user_id, account ID, or user token) directly through the connection, so your backend resolves the right account before the first turn. This is different from your agent authenticating Coval (API keys, bearer tokens on your webhook) — that’s covered in each connection type’s own page. The table below is only about passing the user. Two things to take away from the table:
  • Per-test-case identity works on Chat, Inbound SIP, Outbound, Chat WebSocket, and WebSocket voice. These connection fields substitute {{test_case.*}}, so one test set can drive many different users out of band — the same way the persona prompt does in the conversation. On the other connection types the connection config is fixed per agent, so to vary the user per test case you authenticate in-conversation.
  • Inbound SIP can also receive per-run identity. Put the value in the launch request’s metadata.customer object and reference it from a custom SIP header with {{run_metadata.<key>}}. This is useful when an external job or temporary account is created immediately before each run.
  • For voice-to-voice and plain PSTN, in-conversation is the only option. OpenAI Realtime, Gemini Live, and Pipecat connect Coval straight to the model or platform, and a PSTN phone number strips custom headers — there’s no transport to carry the user’s identity, so the persona/DTMF approach from the sections above is how you authenticate.