Tools Reference

Note: Country and service catalogs are cached server-side and auto-resolved from human-readable names. The agent never receives the full catalog — only resolved IDs or disambiguation hints.

get_balance#

Returns the current Platfone account balance: total funds, reserved by active orders, and available (total − reserved). All values are in USD cents. Use this after a 402 error to inform the user how much they need to top up.

Parameters: none

check_price#

Check pricing and availability for a country + service pair before ordering. Returns min, max, and suggested price, average quality score, and number of available phone numbers. Accepts country and service as human-readable names or IDs.

order_number#

Rent a virtual phone number for the given country and service. Returns a phone number, activation_id, resolved country & service names, price, expiry time, retriable flag, and cancelability. Accepts human-readable names (“Israel”, “Telegram”) — auto-resolved server-side.

Use check_price first to verify cost and availability, then check_sms to poll for the SMS.

check_sms#

Retrieve the current state of an activation — SMS text, parsed code, status, and expiration.

retry_activation#

Request an additional SMS on the same phone number. Free of charge. Only possible when is_retriable is true and activation is still active.

Use check_sms to poll for the new SMS or check once on demand.

cancel_activation#

Cancel an active activation and release the phone number. The reserved amount is refunded. Only possible before SMS is received and after the cancelable_after timestamp has passed.