Find a phone number
Phone numbers the business can rent right now, each with the monthly price and a quote to rent it.
Free*
*Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads.
An example
Find us a Portland number, area code 503, to forward the shop's line to.
Your agent callsphone_search_numbersFree*
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.
{
"country": "US",
"area_code": "503"
}Use it when
The business wants its own number; pass a quote from the reply to phone_rent_number.
What it does
Numbers the business can rent right now, with the monthly price. Rent one by passing its quote to phone_rent_number (quotes last 30 minutes). Bots can rent numbers where the carrier needs no identity documents and answering a call costs less than the $0.25 a minute charged, which includes the US and Canada; for other countries this says why not.
What comes back
The country and type, the monthly and per-minute prices, available, and the numbers with their locality, region and a quote that lasts 30 minutes. For a country whose numbers need identity documents: needs_documents: true, no numbers and a message saying so; calls_too_costly: true where answering a call costs more than the per-minute price covers. Every reply also carries cost_usd and balance_usd.
Inputs
| Name | Type | What it is |
|---|---|---|
country | string | Two-letter country code, e.g. US or CA. Matches ^[A-Za-z]{2}$. Default: US. |
type | string | One of: local,mobile. Default: local. |
area_code | string | Digits the number should start with after the country code, e.g. 503. Matches ^[0-9]{2,6}$. |
city | string | A city the local number should belong to. Up to 80 characters. |
The call
Over MCP, call phone_search_numbers on https://api.conecto.chat/mcp/phone. Over REST:
curl -X POST https://api.conecto.chat/v1/tools/phone_search_numbers \
-H "Authorization: Bearer $CONECTO_KEY" \
-H "Content-Type: application/json" \
-d '{"country":"US","area_code":"503"}'When it refuses
A refused call costs nothing and says what to do next.
| Code | When | What to do |
|---|---|---|
no_numbers404 | The carrier has no numbers of that type there right now, or does not serve the country. | Try without area_code, with a city, or with type mobile. |
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- Rent a phone number
phone_rent_numberRents a number found by phone_search_numbers; this call pays the first month.Quoted up to $25.00 - 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