API Reference

Test Sessions

Simulate a text conversation with your AI agent without making a real phone call. Useful for integration tests, CI pipelines, and rapid prompt iteration.

What is and isn't active in test mode

✓Knowledge bases are searched normally
✓Language and first_message are inherited from the agent by default
⚠The agent's stored system_prompt is NOT loaded automatically in test sessions. Pass system_prompt in the request body to supply one.
✓LLM config inherited from agent, then project, then org (same fallback hierarchy as real calls)
✗Tool calls to server_url are NOT invoked (AI responses only)
✗Recording is always disabled
✗No real audio or phone call is initiated

All test sessions expire after 3 minutes of inactivity regardless of the agent's end_call_enabled setting. Always call DELETE to free memory immediately after testing.

POST/v1/test/voice

Start a new test session with an agent. Returns a session_id and the agent's greeting.

Request body

Name	Type	Required	Description
agent_id	string	required	Agent public_id (agent_*) or numeric id
system_prompt	string	optional	Override the agent's system prompt for this session
first_message	string	optional	Override the agent's greeting message
language	string	optional	Override the agent's language (e.g. "en-US")

curl -X POST https://api.staffifyai.com/v1/test/voice \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agent_28c51f81" }'

Response

{
  "session_id": "test_3_1748900000000_1748900000600",
  "greeting": "Hi! How can I help you today?"
}

The session_id format is test_<orgNumericId>_<ms>_<ms>. Use it verbatim in the subsequent message and delete endpoints. Returns 404 "Agent not found" if the agent_id does not exist in your project.

POST/v1/test/voice/:sessionId/message

Send a message and receive the agent's response.

curl -X POST https://api.staffifyai.com/v1/test/voice/test_3_1748900000000_1748900000600/message \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "I need to file a claim" }'

Response

{
  "response": "I can help with that. Could you provide your policy number?",
  "session_ended": false
}

session_ended: true means the agent triggered end-call logic. Sending a message to an already-ended session returns 200 with an empty response and session_ended: true (not 404).

Returns 400 "text required" if the request body is missing or empty. Returns 400 "Not a test session" if the session ID belongs to a real call rather than a test session. Returns 404 "Session not found or expired" if the session no longer exists (already deleted or timed out).

DELETE/v1/test/voice/:sessionId

End the test session and free server memory. Always clean up explicitly.

curl -X DELETE https://api.staffifyai.com/v1/test/voice/test_3_1748900000000_1748900000600 \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Response
{ "message": "Test session ended" }

Returns 404 "Session not found" if the session has already expired or been deleted. Returns 400 "Not a test session" if the ID resolves to a live call session rather than a test session.

Complete Node.js example

const BASE = 'https://api.staffifyai.com/v1';
const KEY  = process.env.STAFFIFY_API_KEY;

async function testAgent(agentId, conversation) {
  // Start session
  const { session_id, greeting } = await fetch(`${BASE}/test/voice`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ agent_id: agentId }),
  }).then(r => r.json());

  console.log('Agent:', greeting);

  // Run through conversation turns
  for (const message of conversation) {
    const { response, session_ended } = await fetch(
      `${BASE}/test/voice/${session_id}/message`,
      {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ text: message }),
      }
    ).then(r => r.json());

    console.log('User: ', message);
    console.log('Agent:', response);
    if (session_ended) break;
  }

  // Always clean up
  await fetch(`${BASE}/test/voice/${session_id}`, {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${KEY}` },
  });
}

// Run it (session_id will look like "test_3_1748900000000_1748900000600"):
testAgent('agent_28c51f81', [
  'I need to file a claim',
  'My policy number is 123456',
  'Yes, the accident happened yesterday',
]);

← Agents server_url Guide →