Important: Before running your Hamming test agent using the API, ensure your test agent is properly set up. For a detailed, step-by-step guide on creating a dataset of scenarios and configuring the prompt, scorer, and voice agent, refer to the Voice Agent Tutorial.

​
Before You Get Started

In order to set up and run a Hamming voice agent programmatically, you need to have your Dataset ID and Agent ID ready.

​
Step-by-Step Tutorial

1

Initiate Agent Test Run

This initiates a series of parallel calls, referred to as a Voice Experiment.
POST https://app.hamming.ai/api/rest/voice-agent/{agent_id}/run

Request Body:
{ "to_number": "+12063991234", "dataset_id": "{dataset_id}"} // Use your Dataset ID here for the scenario collection

Response:
{ "voice_experiment_id" }
2

Obtain Voice Experiment Status

This endpoint can be used to check the status of the Voice Experiment.
GET https://app.hamming.ai/api/rest/voice-experiment/{voice_experiment_id}

Response:
{ "id": "voice_experiment_id", "status": "FINISHED" }
3

Obtain Voice Experiment Calls

After the experiment is FINISHED, you can retrieve the score results for the experiment.
GET https://app.hamming.ai/api/rest/voice-experiment/{voice_experiment_id}/calls

Response:
{
    "calls": [
       // Array of calls that were run as part of the voice experiment
       // Each call object will include the scoring status.
    ]
}
4

Direct Agent Connections (Without Telephony)

For direct agent-to-agent connections without traditional telephony integration, you can use the createLivekitRooms API:
POST https://app.hamming.ai/api/rest/test-runs/create-livekit-rooms

Request Body:
{ "datasetId": "{dataset_id}", "datasetItemIds": ["item_id_1", "item_id_2"] }

Response:
{
  "experimentId": "string",
  "rooms": [
    {
      "roomName": "string",
      "url": "string",
      "datasetItemId": "string",
      "token": "string"
    }
  ]
}
For detailed documentation on direct agent connections, see the Direct Agent Connections API guide.