Quickstart

In the first ten minutes you place a test call and read what happened. In the next ten you receive its webhooks on your laptop and make a test call to an agent that asks your own server who is calling. Nothing here rings a phone or spends credit.

1. Make a test key

In the console, open API keys and choose New API key. Pick Test and the Outbound calling preset, then Create key. The key is shown once: keep it in your environment.

export AIGENTLY_API_KEY=ag_test_...

2. Make an agent

Make an agent from a template — Appointment reminder places calls, Receptionist answers them — and Publish it. Its id is on Connect → Server API, with the fields a request can fill in. Or ask the API for your agents:

#!/bin/sh
# List agents
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents?limit=20" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

3. Place a test call

A test key calls only test numbers. +12025550100 answers, talks for a few seconds and hangs up — with the agent's real greeting and your values in it.

#!/bin/sh
# Place a call. With a test key this calls a test number and rings nobody.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/calls" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  -H "Idempotency-Key: lead-20931" \
  --json '{
  "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c",
  "to_number": "+12025550100",
  "variables": {
    "first_name": "Sara"
  },
  "metadata": {
    "crm_lead_id": "L-20931"
  },
  "external_id": "lead-20931"
}'

Send a value for each field your agent needs: its variables_schema lists them, and the agent's Server API tab shows this request with its own fields already filled in. The answer is the conversation, pending until the test number answers. The Idempotency-Key is your own id for this call: send the same request again and you get the same conversation back instead of a second call.

4. Read what happened

About ten seconds later the call has ended. Read it with its transcript:

#!/bin/sh
# Read a conversation with its transcript
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

status is completed, disposition is answered, and transcript.entries holds what was said. Where the agent analyses its calls, analysis carries the outcome and the checks. A test call also has a short sample recording:

#!/bin/sh
# Get a link to a recording. The link works for five minutes, so download the audio straight away.
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

5. Receive its webhooks on your laptop

The platform cannot reach localhost, so aigently listen keeps a connection open with your test key and passes each test event to a server on your machine. It needs only Node.js 22.

curl -O https://developers.aigently.ai/aigently.mjs
node aigently.mjs listen --forward-to localhost:3000/hooks

It prints a signing secret. Place another test call and your server receives conversation.started, conversation.ended, conversation.analyzed and conversation.recording_ready, signed with that secret. Check each one with the webhook helper before you trust it.

6. Make a test call to your agent

Give your inbound agent a lookup address under Connect → Phone → Look up who is calling, then forward test lookups to your own server too:

node aigently.mjs listen --forward-to localhost:3000/hooks --forward-lookups-to localhost:3000/lookup

Your /lookup answers with values for the agent's fields:

{"variables": {"first_name": "Sara"}, "metadata": {"crm_id": "C-1042"}}

Now call the agent from a test number:

#!/bin/sh
# Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/test/inbound-calls" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  --json '{
  "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f",
  "from_number": "+12025550100"
}'

The answer says where the values came from (listen, here) and the greeting they produced. See Inbound calls for everything the lookup is sent and may answer.

Next

• Going live — what changes with a live key.
• Variables — how an agent's fields are filled, checked and kept safe.
• Chat and streaming — the same agents, from your app.