This guide puts one of your agents on a phone number, so that anyone who calls the number talks to it. It uses the Call Center API with curl; the dashboard can do the same steps without code.
Before you start
- An agent created in the dashboard. Its prompt, voice, language and tools are what callers get.
- An API key in
LOKUTOR_API_KEY (Authentication).
- A first top-up on the account. Phone numbers and outbound calls are not paid by the welcome credit: before the first top-up these endpoints answer
402 billing.topup_required.
A number costs $5 a month from your balance, charged when you buy it and then monthly. Calls are billed as agent time and language-model tokens plus the phone line per started minute, by country (Pricing and billing).
1. Find your agent’s id
2. Search for a number
Only local numbers are offered, in the US (US), Spain (ES), the UK (UK), Germany (DE), France (FR), Italy (IT) and Portugal (PT). Narrow the search with region_code or locality; results come 15 per page (page=2 for more).
Pick a phone_number from the results. The monthly_cost shown there is the carrier’s figure, not your price.
3. Buy it, bound to the agent
This rents the number and charges the first month immediately. There is no confirmation step.
200 means the number is yours and already routed to the agent. 202 means the order was placed and the number appears in GET /callcenter/numbers shortly.
4. Call it
Call the number from any phone. The agent answers with its first message and holds the conversation. The call appears in the dashboard with its transcript.
A call to your number is not answered while the account balance is under $0.25.
5. Route it to another agent later
{id} is the number’s id from GET /callcenter/numbers, not the phone number itself.
Outbound calls
The same number can call out. consent_confirmed: true is required and records that you have a lawful basis to call this person.
The response’s call_id lets you follow the call and hang it up. Which destinations can be dialled is listed under /callcenter/dial.
These endpoints spend money and call real people. Do not let an AI agent or an automated job call them without a person approving each call.
