REST Client Reference

Overview

The RestClient is the primary interface for interacting with the Piopiy Server API. It provides a structured way to manage calls, recordings, and account settings.

Initialization

from piopiy_voice import RestClient

client = RestClient(token="your_api_token")

Voice Methods

All voice-related methods are accessed via client.voice.

client.ai.call(caller_id, to_number, agent_id, ...)

Initiates an outbound AI agent call.

Parameter	Type	Required	Description
caller_id	str	Yes	Your registered Piopiy number in E.164 format.
to_number	str	Yes	The destination number to dial.
agent_id	str	Yes	The unique ID of the AI agent created in the dashboard.
variables	dict	No	Custom key-value pairs (sent as metadata to create_session).
options	dict	No	Advanced settings: record, ring_timeout_sec, max_duration_sec.
failover	dict	No	Backup routing triggers and targets.

client.voice.transfer(call_id, pipeline)

Re-routes an active call or injects new actions via a PCMO pipeline.

Parameter	Type	Required	Description
call_id	str	Yes	The unique identifier for the active call session.
pipeline	list	Yes	A list of actions or a PipelineBuilder instance.

client.voice.hangup(call_id, cause=None)

Terminates an active call.

Parameter	Type	Required	Description
call_id	str	Yes	The unique identifier for the active call session.
cause	str	No	SIP hangup cause (e.g. NORMAL_CLEARING, BUSY).

Account Methods

get_balance()

Retrieves the current remaining balance on your account.

Best Practices

• Token Security: Always load your API token from environment variables (e.g., os.getenv("PIOPIY_TOKEN")).
• Error Handling: Wrap API calls in try/except blocks to handle network timeouts or invalid parameters.
• Rate Limiting: Be mindful of API rate limits when placing bulk outbound calls.

Example Usage

import os
from piopiy_voice import RestClient

client = RestClient(token=os.getenv("PIOPIY_TOKEN"))

# Trigger an Outbound AI Agent Call
response = client.ai.call(
    caller_id="+15551234567",
    to_number="+15557654321",
    agent_id="your_agent_id",
    variables={"campaign": "spring_sale", "customer_name": "John Doe"}
)
print(response)