Rent a phone number
Rents a number found by phone_search_numbers; this call pays the first month.
Quoted up to $25.00
From your agent’s balance. A call that fails costs nothing.
An example
Take the first of those Portland numbers.
Your agent callsphone_rent_numberQuoted up to $25.00
The example business is Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. The reply is the one the tool really gives.
{
"quote": "eyJudW1iZXIiOiIrMTUwMzU1NTAxMjMiLCJwcmljZSI6MjAwMDAwMH0:1xGmQn:v3kV9o2bS8yq1Xn0Lr5tF7cQ"
}Use it when
A number from the search should become the business's.
What it does
Rent a number found by phone_search_numbers. It is the business's at once; callers reach the AI assistant after phone_setup_assistant has run. This call pays the first month; it then renews monthly from the balance (if the balance is short there are 7 days' grace, then the number is released). Up to 5 numbers per account.
What comes back
line: the number, country, type, locality, status, monthly price, renewal date and payment state, and what to do next. Every reply also carries cost_usd and balance_usd.
Inputs
| Name | Type | What it is |
|---|---|---|
quoteRequired | string | The quote of the number to rent, from phone_search_numbers. 20 to 4,000 characters. |
The call
Over MCP, call phone_rent_number on https://api.conecto.chat/mcp/phone. Over REST:
curl -X POST https://api.conecto.chat/v1/tools/phone_rent_number \
-H "Authorization: Bearer $CONECTO_KEY" \
-H "Content-Type: application/json" \
-d '{"quote":"eyJudW1iZXIiOiIrMTUwMzU1NTAxMjMiLCJwcmljZSI6MjAwMDAwMH0:1xGmQn:v3kV9o2bS8yq1Xn0Lr5tF7cQ"}'When it refuses
A refused call costs nothing and says what to do next.
| Code | When | What to do |
|---|---|---|
quote_expired409 | The quote is older than 30 minutes, or belongs to another account. | Search again with phone_search_numbers and use a new quote. |
payment_required402 | The balance is still free credit; numbers need one real top-up. | Top up once (POST /v1/topups), then rent the number. |
number_taken409 | Someone else rented the number first. | Search again and pick another number. |
carrier_refused409 | The carrier would not sell the number just now. | Search again or pick another number; nothing was charged. |
price_too_high409 | The number costs more than agents can rent today. | Pick another number. |
limit_reached409 | The business rents as many numbers as it may. | Release one it no longer needs with phone_release_number. |
carrier_error502 | The carrier returned a different number. | Search again and rent another one. |
phone_unavailable503 | The phone service is not switched on yet, or has no voices right now. | Try again later; nothing was charged. |
More Phone tools
All 8 tools- Find a phone number
phone_search_numbersPhone numbers the business can rent right now, each with the monthly price and a quote to rent it.Free* - Set up how calls are answered
phone_setup_assistantSets how the business's numbers answer (the agent's webhook or taking messages), the greeting, voice and hours, and whether messages become tickets.$0.001 a call - Get how calls are answered
phone_get_assistantHow the business's numbers answer, whether they answer right now (and why not), and the voices to choose from.Free* - List phone numbers
phone_list_numbersThe numbers the business rents, with their monthly price and next renewal.Free* - List phone calls
phone_list_callsCalls to and from the business's numbers, newest first: who, when, how long and what it cost, missed ones included.Free* - Get a phone call
phone_get_callOne call with its whole transcript: who said what, and when.Free* - Release a phone number
phone_release_numberGives a number back for good: it stops answering at once and its rent ends.Free
Give this to your agent.
Set up Conecto from https://conecto.chat/SKILL.md