Documentation

Your phone system in five minutes

Everything below already exists in your account. Nothing here needs an installer, a technician's visit or a piece of hardware you have to buy.

• You already have numbers and extensions. They are created with your account, together with the SIP credentials each device needs. An extension is a person or a desk; a number is what the outside world dials.
• Point a number somewhere. In the Numbers tab, say what a call arriving on that number should do: ring an extension, ring a group, open a menu, go to a queue, or follow your business hours.
• Answer it from the browser. Open the Phone tab, allow the microphone, and the tab is a working handset. Call the echo test on *43 and you will hear yourself back.
• Then set your hours and your voicemail. Those two are what stop a call being lost at seven in the evening, and they are the two things a new phone system most often lacks.

In a hurry? There are five starter templates — a clinic, a law firm, a workshop, a shop and a home line — that create your business hours, your inbound route and your out-of-hours mailbox in one request. They never overwrite something you have already configured.

Getting into your panelover the API

The panel lives at your VOICE page and only appears with a session. That session is minted by your customer area, not typed in here.

For whoever builds that button, this is the whole contract:

POST /inquilinos/:inquilino/sesiones     # system scope: only the portal can mint one
{ "minutos": 15 }
→ { "clave": "pbx_ses_…", "caduca": "…", "ambito": "sesion", "minutos_max": 60 }

/voice#t=<clave>&exp=<ISO>&v=<inquilino>

The credential travels in the fragment and not in the query on purpose: a fragment is never sent to a server, so it does not end up in a Referer header, in access logs or in a proxy along the way. It expires in minutes, it is capped, and it can never mint a permanent key.

The panel, tab by tabover the API

16 sections, the same 16 in all eight languages. Everything here also exists in the API.

The phone inside your browserreal call

A tab is a handset. No app to install, no desk phone to buy, no number to port — it is an extension of your own phone system, registered from the browser.

• It is a real extension. The browser registers against your phone system the way a desk phone does, and audio runs over an encrypted connection. Someone calling your number can reach the tab, and the tab can call out.
• The tab has to be open. A closed tab is an unplugged phone. That is the honest limit of a browser phone and the reason it complements a desk handset instead of replacing it everywhere.
• You can see who is on a call.real call The lamps next to your colleagues update live — free, ringing, talking — so you know before you transfer whether there is anybody to transfer to.
• You can move a live call to another device.not exercised yet «I have to leave and I am mid-call»: the call moves to your mobile without hanging up. It is a button and not a keypad code on purpose — whoever moves a call has a screen in front of them.
• Transfer, park and record are the same codes as any other handset. They are dialled, not clicked, so what you learn on the browser phone works on the desk phone and on your mobile.

The browser phone never records to your computer. Recording happens in the phone system, where the rules about who may be recorded and who has to be told are applied — see «Recording, and the law».

Codes you dial from a handset

The classics are kept wherever a convention exists (*72 forward, *78 do not disturb, *97 voicemail, *8 pick up, *69 who just called). That is the whole point of a keypad code: the capability is already in the panel, and the code is what lets somebody who has dialled *72 for twenty years believe the panel.

Dialled with the handset idle

Dialled during a conversation

While consulting, in an attended transfer

Inside a conference room

Some codes mean two things and they do not collide: *1 in a normal conversation is «record now», while consulting it is «complete the transfer», and inside a room it is «lock the room». They are different states of the same phone, handled by different code.

Before you trust a new handset: Desk phones and adapters process their own star codes and never send them on. If you dial a code and get silence and then dial tone, the handset ate it and the phone system never saw a thing. Ask us to check a new model against the current list before you roll it out.

Voicemail from any phonetest bench

Dial *97, enter your PIN, and the whole mailbox is there — no app, no browser. It is written for the owner calling in from a borrowed phone.

Main menu

While a message is playing

Greetings menu

Handling the call itself

Ring groups say «make it ring in several places». Everything on this list does something a ring group cannot.

• Queues.not exercised yet A queue knows how many people are ahead and how long it usually takes, so it can say so. The wait is measured from your own recent calls, never invented — with fewer than three samples it says nothing at all. With nobody on shift, nobody is put on hold.
• Call-back from the queue.not exercised yet Offered after a while on hold, and not offered if the call is about to be answered anyway. The request survives a restart, because whoever asks for it hangs up, and the return call goes to the front of the line — which is what was promised.
• Conference rooms.not exercised yet A room with a number and two keys: one to get in, one to run it. Nobody needs an account anywhere. Entries and exits are announced with the name each person recorded themselves.
• The name directory.test bench A caller spells a name on the keypad and gets put through. Every word of a name is indexed separately, because two surnames are normal here and searching only the first one finds half the company. Accents and ñ are folded, so «Muñoz» is found by dialling 686.
• Zero for the operator.not exercised yet Probably the most universal expectation there is about a telephone: being able to reach a person. Zero cascades from your operator to the general mailbox to saying so out loud — never a silent hang-up.
• Park and pick up.not exercised yet Park a call and it waits in a numbered bay with music while you walk to another desk. Anybody can take it back by dialling that bay. Picking up the phone ringing next to you is *8.

Channels: guarantee, loan and hand-backover the API

This is the part of the product that a hard ceiling cannot do, and it is worth understanding before you pick a plan.

• Guaranteed. The simultaneous calls your plan sells. They always fit, whatever the switch is doing, and nobody can take them away from you.
• On loan. Above your guarantee you use whatever the switch has spare. Most days you will be here, and it costs nothing extra.
• The reserve. A cushion of channels that is never lent to anybody, so that everyone can reach their own guarantee at any moment.
• Hand-back. When the switch is under pressure, borrowed calls can be handed back to protect somebody else's guarantee. It only applies to accounts that enabled it, never to a call inside a guarantee, never to an emergency call, and never in silence — the switch speaks before it releases.
• It cannot be oversold. The sum of every guarantee plus the reserve has to fit. Provisioning checks it and will refuse a plan that does not, which is what makes the word «guaranteed» mean something.
• And you can see when it bit. Congestion is reported as episodes with their hour, not as a monthly total. «Twelve rejections in thirty days» reads as noise; «last Tuesday between ten and eleven, five people heard engaged» is something you can act on.

What happens when something breaks

A phone system is judged on the day the power goes out, not on the day everything works.

• More than one way out. The switch reaches the outside world over several independent connections and picks between them on its own. You do not configure this and you do not see it happen.
• «Working» is measured against the right thing. A connection is only eligible if it reaches both the internet and the telephone network. Checking only the first one is how a phone system ends up with no line while every light is green.
• It comes back on its own after a power cut. When power returns, the switch and the network equipment start at the same time and not always in the right order. Rather than trusting that order, the switch keeps comparing what it actually has against what it should have, and repairs itself — with a ceiling on how often it may retry, so a real fault gets escalated instead of looping.
• It will not cut a call to fix itself. Any repair that would interrupt conversations waits until there are none.

Recordings and voicemail are stored outside the switch, so they survive the machine itself.

Plans and minutes

5 plans, from $100 to $300 a year, and one number per licence. Incoming minutes on a Costa Rican number are $0.00.

Minutes

Prices in US dollars, taxes included. Mobile calls are metered by the second by our carrier. Each licence includes 1 number; extra numbers share the same switch, flows and panel.

Recording, and the lawover the API

Recorded audio is other people's voices. Costa Rican law 8968 governs it, and the design follows from that rather than from what is convenient.

• You decide what gets recorded.over the API Everything, or only certain extensions, or only calls arriving on a certain number. Or nothing, which is a legitimate answer.
• Retention comes with your plan. Recordings are purged automatically when their time is up. The one exception is a recording attached to a nuisance-call file, which stops expiring until you close the file — and closing it returns a normal deadline, never «delete it now».
• Sharing one does not mean giving access. A signed link plays a single recording, expires on its own and can be revoked. The person you send it to never sees your account.
• Every listen is logged. Who played which recording and when. It is somebody else's voice: knowing who has heard it is part of holding it.
• You can file them. Customer, prospect or internal. There is deliberately no default: unlabelled is honest, and a label the machine guessed cannot be told apart later from one a person chose.

Both parties are always told. Asking the switch to record also returns the obligation to announce it — the two cannot be separated, because separating them is how somebody ends up recorded without knowing. In a conference room the announcement is made to each person as they enter.

Limits, protection and undo

The things that decide how bad a bad day gets: a stolen credential, a mistake in the routing, a number that will not stop calling.

• A spend ceiling, daily and monthly.test bench This is what stops a stolen credential from costing money. When the ceiling is reached, calls stop.
• What each extension may dial.over the API Internal only, national, mobile, or everything. The warehouse phone has no reason to be able to call a premium line. Emergency calls are never affected by this.
• The price before you dial.over the API Ask what a given number would cost and the answer is calculated by the same machinery that will actually place the call — not by a rate card that might not be the one applied.
• A fraud alarm that watches behaviour.not exercised yet Unusual speed, a country you have never called, an hour nobody works. It warns and does not cut: a false positive here is not an annoying alert, it is a call that did not happen. It takes two signals before it says anything, because an alarm that goes off daily gets ignored.
• A repeat caller is flagged.not exercised yet The same number five times in two minutes is a dialler, not an insistent customer. Out of the box it only warns; blocking automatically is a box you tick, because a false positive costs you a customer who can never call again.
• A file for a nuisance call.not exercised yet The time, the route and the audio, kept together for a complaint. Opening one does not block the caller: each new call is one more piece of evidence, and that is your decision, not ours.
• How reachable your handsets have been.over the API Not our uptime — yours. And it always shows how much of the period was actually measured, because a percentage that quietly drops the hours nobody looked at always errs in the comfortable direction.
• What changed, who changed it, and undo.not exercised yet «It worked yesterday» is a question with an answer. Every configuration change is recorded and can be reverted, and reverting checks that nobody else has touched those fields in the meantime instead of quietly overwriting them.

What is switched off, and why

A manual that only describes what works forces you to discover the rest on your own, and you always discover it at the worst moment. This list is generated from the switch itself, so it cannot describe something as off after it has been turned on.

The APIover the API

The panel is one client of this API. Anything you change by hand can be changed by program, with a key that belongs to your account.

curl -H "authorization: Bearer <clave>" \
  https://api.voice.forhosting.com/inquilinos/<cuenta>/numeros

Scopes

When something goes wrong

There is almost no rate limiting today. The only one is a few seconds' cooldown between attempts to open the browser phone. There is no general quota, and we would rather say so than let you build on an assumption. Be reasonable, and if you are planning something heavy, tell us first so we can measure it with you rather than after you.

What you can reach

267 endpoints in total, read from the switch itself on 2026-08-17.

This table is a summary. The list that cannot go stale is the one the switch generates about itself: GET /api.

Sessions: the browser never holds a permanent key

A short-lived credential, capped at 60 minutes, that cannot mint a permanent one. This is the contract if you are the one building the button.

• Only the portal can mint one. Minting a session needs a provisioning key, because only the portal can state that there is a signed-in customer behind the request. VOICE does not know about customer passwords and has no reason to.
• It never gets born without an expiry. If nobody asks for a duration, one is applied. A scope that exists in order to expire and that could be born eternal is worse than not having it, because people trust it.
• Asking for longer does not work. There is a hard ceiling. A caller asking for eight hours does not make the credential safe.
• It cannot promote itself. Key management lives entirely behind provisioning scope, so a session cannot mint a permanent key. That is enforced in the router, before any handler runs.
• You can end one early. The identifier comes back when you mint it, precisely so that you can revoke it before its time.

Webhooksover the API

Your systems get told what happened instead of asking every few seconds. 28 events, signed, retried, and never dropped in silence.

x-pbx-evento: llamada.entrante
x-pbx-marca:  1755300000
x-pbx-firma:  <hex>

{ "evento": "llamada.entrante", "inquilino": "…", "cuando": "…", "datos": { … } }

Every delivery is signed: the signature covers the timestamp and the exact body you received, so verify it against the raw bytes rather than against a re-serialised copy. The secret is shown once when you create the subscription, and it can be rotated without stopping deliveries.

A delivery that fails is retried after 10 · 30 · 60 · 300 · 900 · 3600 seconds, and each attempt is given 10 seconds. A subscription that keeps failing is paused after 20 consecutive failures rather than dropped in silence — and you can see every attempt.

The events

The live channelreal call

Webhooks travel in batches and arrive within seconds. Some things need to be on screen now — a lamp that shows a colleague is on a call cannot be fifteen seconds late.

• What it carries. Calls as they happen, new messages, and the lamp state of every extension — which is what makes a busy-lamp field on a screen actually live.
• It is read-only.not exercised yet You can open a ticket for the channel without handing out a phone: watching what happens should not require a credential that can also change things.
• It is not a replacement for webhooks. The live channel is for a screen somebody is looking at. If it matters that your system finds out, use a webhook: it retries, and it does not depend on a socket being open.

How the badges work

Every capability on this page carries a badge saying how it has been verified. We publish the ones that have not been exercised yet, labelled as such, because you finding out on your own is worse.

112 capabilities, counted from the switch on 2026-08-19.

The badge belongs to a capability, not to a single row: where one capability covers several codes, all of them show the level of the group. That means a badge can understate what has actually been tested — never overstate it, which is the only direction we are willing to be wrong in on a page you read as a promise.

Glossary

The words a phone system uses that nothing else does.