Skip to main content

AI Agents

Overview​

Use Piopiy to create, map, list, and delete AI agents for telephony voice flows.

You can manage AI agents in two ways:

  • Dashboard UI for manual setup
  • REST API for backend automation

Prerequisites​

  • Piopiy dashboard account
  • API credentials enabled for your workspace
  • At least one purchased phone number (for mapping)

Option 1. Manage AI Agents in Dashboard (UI)​

Use this when your team wants a quick manual workflow.

  1. Open the Piopiy Dashboard.
  2. Go to Voice AI -> Agents.
  3. Create your agent.
  4. Open Numbers and choose a purchased number.
  5. Configure routing and map that number to the AI agent.
  6. View agents list, edit settings, or remove unused agents.

For full dashboard setup flow, see Dashboard Setup.

Option 2. Manage AI Agents with REST API​

Use this for automation, CI workflows, and backend provisioning.

Set these variables before running requests:

export PIOPIY_API_KEY="your_api_key"
export PIOPIY_API_BASE="https://api.piopiy.com/v1"

1. Create AI Agent​

Create a new agent for your Voice AI runtime.

curl --request POST \
  --url "$PIOPIY_API_BASE/ai-agents" \
  --header "Authorization: Bearer $PIOPIY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Support Agent",
    "language": "en-US"
  }'

Example response:

{
  "id": "agent_9x2d",
  "name": "Support Agent",
  "status": "active",
  "agent_token": "agt_live_xxxxx"
}

2. Map Number to AI Agent​

Attach a purchased number to the target AI agent.

curl --request POST \
  --url "$PIOPIY_API_BASE/phone-number-routing" \
  --header "Authorization: Bearer $PIOPIY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone_number": "+19499800001",
    "route_type": "ai_agent",
    "agent_id": "agent_9x2d"
  }'

API note: keep "route_type": "ai_agent" as shown, because this is the expected routing value.

Example response:

{
  "phone_number": "+19499800001",
  "route_type": "ai_agent",
  "agent_id": "agent_9x2d",
  "status": "connected"
}

3. List AI Agents​

Get all agents in your workspace.

curl --request GET \
  --url "$PIOPIY_API_BASE/ai-agents" \
  --header "Authorization: Bearer $PIOPIY_API_KEY"

Example response:

{
  "data": [
    {
      "id": "agent_9x2d",
      "name": "Support Agent",
      "status": "active"
    }
  ]
}

4. Delete AI Agent​

Delete an unused AI agent.

curl --request DELETE \
  --url "$PIOPIY_API_BASE/ai-agents/agent_9x2d" \
  --header "Authorization: Bearer $PIOPIY_API_KEY"

Example response:

{
  "id": "agent_9x2d",
  "status": "deleted"
}

Production Checklist​

  • Use clear naming for agents per environment and use case.
  • Keep mapping changes in backend automation or controlled UI workflows.
  • Restrict and rotate agent credentials/tokens regularly.
  • Keep an audit trail for create/map/delete operations.

Reference​