Dokumentation

Ihre Telefonanlage in fünf Minuten

Alles Folgende gibt es in Ihrem Konto bereits. Nichts davon braucht einen Installateur, den Besuch eines Technikers oder ein Gerät, das Sie kaufen müssten.

• Nummern und Nebenstellen haben Sie bereits. Sie entstehen mit Ihrem Konto, samt der SIP-Zugangsdaten, die jedes Gerät braucht. Eine Nebenstelle ist eine Person oder ein Arbeitsplatz; eine Nummer ist das, was die Außenwelt wählt.
• Richten Sie eine Nummer auf ein Ziel. Im Reiter Nummern legen Sie fest, was ein dort eingehender Anruf tun soll: eine Nebenstelle klingeln lassen, eine Gruppe klingeln lassen, ein Menü öffnen, in eine Warteschlange gehen oder Ihren Öffnungszeiten folgen.
• Nehmen Sie ihn im Browser an. Öffnen Sie den Reiter Telefon, erlauben Sie das Mikrofon, und der Reiter ist ein funktionierender Apparat. Rufen Sie den Echotest mit *43 an, und Sie hören sich selbst zurück.
• Und danach Öffnungszeiten und Mailbox. Diese beiden verhindern, dass um sieben Uhr abends ein Anruf verloren geht — und es sind die zwei Dinge, die einer frisch eingerichteten Anlage am häufigsten fehlen.

Eilig? Es gibt fünf Startvorlagen — eine Praxis, eine Kanzlei, eine Werkstatt, ein Laden und ein Privatanschluss —, die Öffnungszeiten, eingehende Route und Mailbox für außerhalb der Zeiten in einer einzigen Anfrage anlegen. Sie überschreiben nie etwas, das Sie schon eingerichtet haben.

So kommen Sie in Ihr Panelüber die API

Das Panel liegt auf Ihrer VOICE-Seite und erscheint nur mit einer Sitzung. Diese Sitzung stellt Ihr Kundenbereich aus; hier wird nichts eingetippt.

Für alle, die diesen Knopf bauen, hier der ganze Vertrag:

POST /inquilinos/:inquilino/sesiones     # Systembereich: nur das Portal darf eine ausstellen
{ "minutos": 15 }
→ { "clave": "pbx_ses_…", "caduca": "…", "ambito": "sesion", "minutos_max": 60 }

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

Die Zugangsdaten reisen im Fragment und nicht in der Query, und zwar mit Absicht: Ein Fragment wird nie an einen Server geschickt, landet also weder in einem Referer-Header noch in Zugriffsprotokollen noch bei einem Zwischenknoten unterwegs. Sie laufen in Minuten ab, sind gedeckelt und können keinen dauerhaften Schlüssel ausstellen.

Das Panel, Reiter für Reiterüber die API

16 Bereiche, dieselben 16 in allen acht Sprachen. Alles davon gibt es auch in der API.

Das Telefon im Browserechter Anruf

Ein Browser-Tab ist ein Apparat. Nichts zu installieren, kein Tischtelefon zu kaufen, keine Nummer zu portieren: Es ist eine Nebenstelle Ihrer eigenen Anlage, angemeldet aus dem Browser.

• Es ist eine echte Nebenstelle. Der Browser meldet sich an Ihrer Anlage an wie ein Tischtelefon, und der Ton läuft über eine verschlüsselte Verbindung. Wer Ihre Nummer anruft, erreicht den Reiter, und der Reiter kann nach draußen telefonieren.
• Der Reiter muss offen bleiben. Ein geschlossener Reiter ist ein ausgestecktes Telefon. Das ist die ehrliche Grenze eines Browser-Telefons und der Grund, warum es ein Tischgerät ergänzt, statt es überall zu ersetzen.
• Sie sehen, wer telefoniert.echter Anruf Die Lampen Ihrer Kolleginnen und Kollegen laufen live mit — frei, klingelt, im Gespräch —, damit Sie schon vor der Weitergabe wissen, ob überhaupt jemand da ist, an den Sie weitergeben können.
• Sie können ein laufendes Gespräch auf ein anderes Gerät holen.noch ungetestet «Ich muss los und telefoniere gerade»: Das Gespräch wandert auf Ihr Handy, ohne aufzulegen. Es ist mit Absicht ein Knopf und kein Tastencode — wer ein Gespräch verschiebt, hat einen Bildschirm vor sich.
• Weitergeben, Parken und Aufzeichnen sind dieselben Codes wie an jedem Apparat. Sie werden gewählt, nicht geklickt. Was Sie am Browser-Telefon lernen, gilt also auch am Tischtelefon und am Handy.

Das Browser-Telefon zeichnet nie auf Ihrem Rechner auf. Aufgezeichnet wird in der Anlage, denn dort greifen die Regeln dazu, wen man aufzeichnen darf und wem man es sagen muss — siehe «Aufzeichnen, und das Gesetz».

Codes, die Sie am Apparat wählen

Wo es eine Konvention gibt, bleibt sie erhalten (*72 Umleitung, *78 Nicht stören, *97 Mailbox, *8 Heranholen, *69 wer gerade angerufen hat). Genau darin liegt der Sinn eines Tastencodes: Die Funktion steckt schon im Panel, und der Code sorgt dafür, dass jemand, der seit zwanzig Jahren *72 wählt, dem Panel glaubt.

Bei aufgelegtem Hörer gewählt

Während eines Gesprächs gewählt

In der Rückfrage einer begleiteten Weitergabe

Im Konferenzraum

Manche Codes bedeuten zwei Dinge, ohne sich in die Quere zu kommen: *1 heißt im normalen Gespräch «jetzt aufzeichnen», in der Rückfrage «Weitergabe abschließen» und im Konferenzraum «Raum schließen». Das sind verschiedene Zustände desselben Telefons, die verschiedener Code bedient.

Bevor Sie einem neuen Apparat trauen: Tischtelefone und Adapter verarbeiten ihre eigenen Sterncodes und geben sie nie weiter. Wenn Sie einen Code wählen und Stille und danach den Wählton hören, hat der Apparat ihn geschluckt und die Anlage hat nichts gesehen. Lassen Sie uns ein neues Modell gegen die heutige Liste prüfen, bevor Sie es ausrollen.

Die Mailbox von jedem Telefon ausPrüfstand

Wählen Sie *97, geben Sie Ihre PIN ein, und die ganze Mailbox ist da — ohne App, ohne Browser. Sie ist für den Inhaber gedacht, der von einem geliehenen Telefon anruft.

Hauptmenü

Während eine Nachricht läuft

Ansagenmenü

Den Anruf selbst annehmen

Eine Rufgruppe sagt «es soll an mehreren Stellen klingeln». Alles auf dieser Liste kann etwas, das eine Rufgruppe nicht kann.

• Warteschlangen.über die API Eine Warteschlange weiß, wie viele Leute davor sind und wie lange es üblicherweise dauert — also kann sie es sagen. Die Wartezeit wird aus Ihren eigenen jüngsten Anrufen gemessen, nie erfunden: Bei weniger als drei Messwerten sagt sie gar nichts. Ist niemand im Dienst, wird auch niemand in die Schleife gestellt.
• Rückruf aus der Warteschlange.über die API Wird nach einer Weile in der Schleife angeboten — und nicht angeboten, wenn der Anruf ohnehin gleich angenommen wird. Der Wunsch übersteht einen Neustart, denn wer ihn äußert, legt auf, und der Rückruf kommt vorn in die Reihe. Genau das war versprochen.
• Konferenzräume.über die API Ein Raum mit einer Nummer und zwei Schlüsseln: einer zum Hineinkommen, einer zum Leiten. Niemand braucht irgendwo ein Konto. Kommen und Gehen wird mit dem Namen angesagt, den jede Person selbst aufgenommen hat.
• Das Namensverzeichnis.Prüfstand Anrufer buchstabieren einen Namen auf der Tastatur und werden durchgestellt. Jedes Wort eines Namens wird einzeln erfasst, denn hier sind zwei Nachnamen normal, und wer nur den ersten durchsucht, findet die halbe Firma. Akzente und ñ werden angeglichen, «Muñoz» findet man also über 686.
• Die Null für die Vermittlung.über die API Vermutlich die allgemeinste Erwartung, die es an ein Telefon gibt: eine Person erreichen zu können. Die Null fällt in Stufen von Ihrer Vermittlung über die allgemeine Mailbox bis zu einer gesprochenen Auskunft — nie ein stummes Auflegen.
• Parken und Heranholen.über die API Parken Sie ein Gespräch, und es wartet mit Musik auf einem nummerierten Platz, während Sie an einen anderen Arbeitsplatz gehen. Jeder holt es zurück, indem er diesen Platz wählt. Das Telefon, das neben Ihnen klingelt, holen Sie mit *8 heran.

Kanäle: Garantie, Leihe und Rückgabeüber die API

Das ist der Teil des Produkts, den eine harte Obergrenze nicht kann, und es lohnt sich, ihn vor der Tarifwahl zu verstehen.

• Garantiert. Die gleichzeitigen Gespräche, die Ihr Tarif verkauft. Sie passen immer, egal was in der Anlage los ist, und niemand kann sie Ihnen wegnehmen.
• Geliehen. Über Ihrer Garantie nutzen Sie, was die Anlage frei hat. An den meisten Tagen sind Sie hier, und es kostet nichts extra.
• Die Reserve. Ein Polster an Kanälen, das niemandem geliehen wird, damit jeder jederzeit seine eigene Garantie erreichen kann.
• Die Rückgabe. Wenn die Anlage unter Druck steht, können geliehene Gespräche zurückgegeben werden, um die Garantie eines anderen zu schützen. Das gilt nur für Konten, die es erlaubt haben, nie für ein Gespräch innerhalb einer Garantie, nie für einen Notruf und nie stillschweigend: Die Anlage spricht, bevor sie freigibt.
• Sie lässt sich nicht überbuchen. Die Summe aller Garantien plus Reserve muss hineinpassen. Die Einrichtung prüft das und lehnt einen Tarif ab, der nicht hineinpasst — genau das gibt dem Wort «garantiert» seine Bedeutung.
• Und man sieht, wann es gezwickt hat. Überlast wird als einzelne Vorfälle mit Uhrzeit gemeldet, nicht als Monatssumme. «Zwölf Abweisungen in dreißig Tagen» liest sich wie Rauschen; «letzten Dienstag zwischen zehn und elf hörten fünf Leute besetzt» ist etwas, worauf man reagieren kann.

Was passiert, wenn etwas kaputtgeht

Eine Telefonanlage wird an dem Tag beurteilt, an dem der Strom ausfällt, nicht an dem Tag, an dem alles läuft.

• Mehr als ein Weg nach draußen. Die Anlage erreicht die Außenwelt über mehrere unabhängige Verbindungen und wählt selbst zwischen ihnen. Sie richten das nicht ein und sehen es nicht passieren.
• «Funktioniert» wird am Richtigen gemessen. Eine Verbindung kommt nur infrage, wenn sie sowohl das Internet als auch das Telefonnetz erreicht. Nur das Erste zu prüfen ist der Weg, auf dem eine Anlage ohne Leitung dasteht, während alle Lampen grün sind.
• Sie kommt nach einem Stromausfall von allein zurück. Wenn der Strom zurückkehrt, starten Anlage und Netzwerktechnik gleichzeitig und nicht immer in der richtigen Reihenfolge. Statt sich auf diese Reihenfolge zu verlassen, vergleicht die Anlage laufend, was sie tatsächlich hat, mit dem, was sie haben sollte, und repariert sich selbst — mit einer Obergrenze für die Versuche, damit eine echte Störung gemeldet wird, statt in einer Schleife zu enden.
• Sie trennt kein Gespräch, um sich zu reparieren. Jede Reparatur, die Gespräche unterbrechen würde, wartet, bis keines mehr läuft.

Aufzeichnungen und Mailbox-Nachrichten liegen außerhalb der Anlage und überleben damit die Maschine selbst.

Tarife und Minuten

5 Tarife, von $100 bis $300 im Jahr, und eine Nummer je Lizenz. Die eingehende Minute auf einer costa-ricanischen Nummer kostet $0.00.

Minuten

Preise in US-Dollar, Steuern inklusive. Mobilfunkgespräche rechnet unser Netzbetreiber sekundengenau ab. Jede Lizenz enthält 1 Nummer; zusätzliche Nummern teilen sich dieselbe Anlage, dieselben Abläufe und dasselbe Panel.

Aufzeichnen, und das Gesetzüber die API

Aufgezeichneter Ton ist die Stimme anderer Menschen. Das costa-ricanische Gesetz 8968 regelt das, und der Entwurf folgt daraus — nicht dem, was bequem wäre.

• Sie entscheiden, was aufgezeichnet wird.über die API Alles, oder nur bestimmte Nebenstellen, oder nur Anrufe auf einer bestimmten Nummer. Oder nichts, was eine legitime Antwort ist.
• Die Aufbewahrung kommt mit Ihrem Tarif. Aufzeichnungen werden automatisch gelöscht, wenn ihre Zeit um ist: nach der Frist des Tarifs, oder nach 90 Tagen bei denen, die während eines Anrufs angefordert wurden (mit *1), und denen aus einem Konferenzraum. Die einzige Ausnahme ist eine Aufzeichnung, die an einer Akte über einen belästigenden Anruf hängt: Sie läuft nicht mehr ab, bis Sie die Akte schließen — und das Schließen setzt eine normale Frist, nie ein «jetzt sofort löschen».
• Eine zu teilen heißt nicht, Zugang zu geben. Ein signierter Link spielt genau eine Aufzeichnung ab, läuft von selbst ab und lässt sich widerrufen. Die Person, der Sie ihn schicken, sieht Ihr Konto nie.
• Jedes Abhören wird protokolliert. Wer welche Aufzeichnung wann abgespielt hat. Es ist die Stimme eines anderen Menschen: zu wissen, wer sie gehört hat, gehört zum Aufbewahren dazu.
• Sie lassen sich einordnen. Kunde, Interessent oder intern. Es gibt mit Absicht keine Voreinstellung: nicht eingeordnet ist ehrlich, und eine Einordnung, die die Maschine geraten hat, lässt sich später nicht mehr von einer unterscheiden, die ein Mensch gewählt hat.

Beide Seiten werden immer informiert. Wer die Anlage bittet aufzuzeichnen, bekommt die Ansagepflicht gleich mit — die beiden lassen sich nicht trennen, denn genau beim Trennen wird jemand aufgezeichnet, ohne es zu wissen. Im Konferenzraum wird die Ansage jeder Person beim Eintreten gemacht.

Grenzen, Schutz und Rückgängig

Das, was entscheidet, wie schlimm ein schlechter Tag wird: gestohlene Zugangsdaten, ein Fehler in der Wegeführung, eine Nummer, die nicht aufhört anzurufen.

• Eine Ausgabengrenze, täglich und monatlich.Prüfstand Das ist es, was gestohlene Zugangsdaten daran hindert, Geld zu kosten. Ist die Grenze erreicht, hören die Gespräche auf.
• Was jede Nebenstelle wählen darf.über die API Nur intern, national, Mobilfunk oder alles. Das Telefon im Lager hat keinen Grund, eine Mehrwertnummer anrufen zu können. Notrufe sind davon nie betroffen.
• Der Preis, bevor Sie wählen.über die API Fragen Sie, was eine bestimmte Nummer kosten würde, und die Antwort berechnet dieselbe Maschinerie, die das Gespräch später auch führt — nicht eine Preisliste, die vielleicht gar nicht die angewandte ist.
• Ein Betrugsalarm, der auf Verhalten schaut.noch ungetestet Ungewöhnliches Tempo, ein Land, in das Sie nie telefonieren, eine Uhrzeit, zu der niemand arbeitet. Er warnt und trennt nicht: Ein Fehlalarm ist hier kein lästiger Hinweis, sondern ein Gespräch, das nicht stattgefunden hat. Er braucht zwei Signale, bevor er etwas sagt, denn einen Alarm, der täglich losgeht, lernt man zu ignorieren.
• Wer zu hartnäckig anruft, wird markiert.noch ungetestet Dieselbe Nummer fünfmal in zwei Minuten ist kein hartnäckiger Kunde, sondern ein Automat. Ab Werk wird nur gewarnt; automatisch sperren ist ein Häkchen, das Sie setzen — denn ein Fehlalarm kostet Sie einen Kunden, der nie wieder anrufen kann.
• Eine Akte für einen belästigenden Anruf.noch ungetestet Uhrzeit, Weg und Ton, zusammen aufbewahrt für eine Anzeige. Eine Akte zu eröffnen sperrt den Anrufer nicht: Jeder neue Anruf ist ein weiterer Beleg, und das entscheiden Sie, nicht wir.
• Wie erreichbar Ihre Apparate waren.über die API Nicht unsere Verfügbarkeit — Ihre. Und es wird immer mit ausgewiesen, wie viel des Zeitraums tatsächlich gemessen wurde, denn ein Prozentwert, der die unbeobachteten Stunden stillschweigend weglässt, irrt sich immer in die bequeme Richtung.
• Was sich geändert hat, wer es geändert hat, und Rückgängig.über die API «Gestern ging es noch» ist eine Frage mit Antwort. Jede Änderung an der Konfiguration wird festgehalten und lässt sich zurücknehmen, und das Zurücknehmen prüft, ob inzwischen jemand anderes diese Felder angefasst hat, statt sie stillschweigend zu überschreiben.

Was abgeschaltet ist, und warum

Ein Handbuch, das nur beschreibt, was funktioniert, zwingt Sie, den Rest allein herauszufinden — und man findet ihn immer im schlechtesten Moment. Diese Liste erzeugt der Schalter selbst; sie kann also nichts als abgeschaltet beschreiben, das längst eingeschaltet ist.

Die APIüber die API

Das Panel ist einer der Clients dieser API. Alles, was Sie von Hand ändern, lässt sich auch per Programm ändern — mit einem Schlüssel, der Ihrem Konto gehört.

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

Geltungsbereiche

Wenn etwas schiefgeht

Alles, was die API antworten kann, wenn sie ablehnt

Das sind die genauen Zeichenketten, die die API im Feld error zurückgibt, gelesen aus dem Quelltext der Anlage. Sie kommen auf Spanisch heraus und stehen hier absichtlich unverändert: Erkennen müssen Sie, was ankommt, nicht eine Übersetzung davon. Ein … markiert die Stelle, an der ein Wert eingesetzt wird.

Jeder Fehler trägt einen stabilen Code. Werten Sie codigo aus, nicht die Meldung. Er ist immer da: Was keinen eigenen deklariert, bekommt den seiner Klasse, abgeleitet aus dem HTTP-Status. Der Text in error ist für Menschen gedacht und kann umformuliert werden; der Code nicht.

{ "error": "…", "codigo": "de_otra_cuenta" }

336 verschiedene Meldungen an 407 Stellen im Quelltext der Anlage. Bei jedem Build abgeleitet: Was sich dort ändert, ändert sich hier.

Heute gibt es fast keine Ratenbegrenzung. Die einzige ist eine Wartezeit von ein paar Sekunden zwischen zwei Versuchen, das Telefon im Browser zu öffnen. Ein allgemeines Kontingent gibt es nicht, und das sagen wir lieber, als Sie es entdecken zu lassen, nachdem Sie auf einer Annahme gebaut haben. Bleiben Sie vernünftig, und wenn Sie etwas Schweres planen, sagen Sie uns vorher Bescheid — dann messen wir es mit Ihnen und nicht hinter Ihnen her.

Was erreichbar ist

304 Endpunkte insgesamt, am 2026-10-21 aus der Anlage selbst gelesen.

Diese Tabelle ist eine Zusammenfassung. Die Liste, die nicht veralten kann, ist die, die die Anlage über sich selbst erzeugt: GET /api.

Jeder Endpunkt, einzeln

Aus dem Router der Anlage selbst gelesen: Er kann also weder eine Route beschreiben, die es nicht gibt, noch eine vergessen, die es gibt. Hier steht nur der Bereich Ihres Kontos; die Bereitstellungsrouten gehören dem Portal, und einen Schlüssel, der dorthin reicht, erhalten Sie nicht.

Aufgezeichnete Beispiele

Sie sind nicht getippt, sondern bei einem echten Lauf gegen diese API aufgezeichnet worden — in einem Wegwerfkonto, das danach gelöscht wurde. Anfrage, Status und Antwort, genau so, wie sie über die Leitung gingen. Konto- und Objektkennungen sind durch Platzhalter ersetzt, sonst nichts. Ein geschriebenes Beispiel belegt, was sein Autor glaubte; ein aufgezeichnetes belegt, was die Anlage getan hat.

24 von 226 Routen haben ein aufgezeichnetes Beispiel, aus dem Lauf vom 2026-10-16. Die übrigen stehen oben, sind aber noch nicht auf diese Weise erprobt — wir zeigen Ihnen lieber die Zahl, als Sie annehmen zu lassen, es seien alle.

{
  "plazas": []
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "cancelada",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.942Z"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "pendiente",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.732Z"
}

{
  "numero": "50688889999",
  "cuando": "2026-10-16T22:44:57.219Z",
  "texto": "ensayo"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "pendiente",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.732Z"
}

[]

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Soporte",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:57.230Z",
  "actualizado": "2026-10-16T21:44:57.230Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

{
  "nombre": "Ya editada"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Ya editada",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:59.058Z",
  "actualizado": "2026-10-16T21:44:59.287Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Soporte",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:57.230Z",
    "actualizado": "2026-10-16T21:44:57.230Z",
    "version": "\"v1-73d179cfb86c534a9bfccc\""
  }
]

{
  "nombre": "Soporte",
  "estrategia": "todos"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Soporte",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:57.230Z",
  "actualizado": "2026-10-16T21:44:57.230Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Sala 1",
  "numero": null,
  "max_personas": 10,
  "esperar_organizador": 0,
  "anunciar_entradas": 1,
  "pedir_nombre": 1,
  "bloqueada": 0,
  "grabar": 0,
  "musica": "default",
  "activa": 1,
  "creado": "2026-10-16T21:44:57.733Z",
  "actualizado": "2026-10-16T21:44:57.733Z",
  "tiene_pin": false,
  "tiene_pin_organizador": false,
  "dentro": 0,
  "grabando": false
}

{
  "nombre": "Sala 1",
  "clave": "<secreto>"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Sala 1",
  "numero": null,
  "max_personas": 10,
  "esperar_organizador": 0,
  "anunciar_entradas": 1,
  "pedir_nombre": 1,
  "bloqueada": 0,
  "grabar": 0,
  "musica": "default",
  "activa": 1,
  "creado": "2026-10-16T21:44:57.733Z",
  "actualizado": "2026-10-16T21:44:57.733Z",
  "tiene_pin": false,
  "tiene_pin_organizador": false
}

{}

{
  "ticket": "<secreto>",
  "eventos": [
    "wss://<puerta>:<puerto>/eventos",
    "wss://<puerta>:<puerto>/eventos",
    "wss://<puerta>:<puerto>/eventos"
  ],
  "inquilino": "<cuenta>"
}

{
  "instalacion": "ejercicio-api-ventana-tranquila"
}

{
  "id": "<id>",
  "clave": "<secreto>",
  "caduca": "2026-10-16T22:00:02.449Z",
  "segundos": 900,
  "ambito": "dispositivo",
  "vinculo": {
    "inquilino": "<cuenta>",
    "extension": "<id>",
    "dispositivo": "<id>"
  },
  "extension": {
    "id": "<id>",
    "numero": "100",
    "nombre": "Ejercicio API"
  },
  "dispositivo_nuevo": true,
  "minutos_max": 60,
  "resumen": "credencial de UN aparato de UNA extensión, que caduca; para la app móvil"
}

{
  "numero": "100"
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "numero": "100",
    "nombre": "Ejercicio API",
    "correo": null,
    "cid_saliente": null,
    "timbrado_s": 25,
    "estado": "activa",
    "creado": "2026-10-16T21:45:00.167Z",
    "actualizado": "2026-10-16T21:45:00.167Z",
    "nombre_audio": null,
    "en_directorio": 1,
    "departamento": null,
    "version": "\"v1-a1a25e330e8bc32c8289ab\""
  }
]

{
  "nombre": "Ejercicio API",
  "numero": "100"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "100",
  "nombre": "Ejercicio API",
  "correo": null,
  "cid_saliente": null,
  "timbrado_s": 25,
  "estado": "activa",
  "creado": "2026-10-16T21:45:00.167Z",
  "actualizado": "2026-10-16T21:45:00.167Z",
  "nombre_audio": null,
  "en_directorio": 1,
  "departamento": null,
  "reglas": {
    "extension_id": "<id>",
    "dnd": 0,
    "dnd_hasta": null,
    "sigueme": 0,
    "sigueme_numeros": [],
    "sigueme_modo": "tras",
    "sigueme_confirmar": 1,
    "sigueme_s": 20,
    "desvio_siempre": null,
    "desvio_ocupado": null,
    "desvio_nocontesta": null,
    "fallo_tipo": "buzon",
    "fallo_id": "<id>",
    "actualizado": "2026-10-16T21:45:00.168Z",
    "desvio_confirmar": 1,
    "screening": 0,
    "clase_servicio": "todo",
    "supervisar": 0,
    "transferencia_retorno": 0
  },
  "dispositivos": [
    {
      "id": "<id>",
      "etiqueta": "principal",
      "usuario_sip": "tf3zfmm96cfq100",
      "transporte": "udp",
      "estado": "activo",
      "ultimo_registro": null,
      "ultima_ip": null,
      "creado": "2026-10-16T21:45:00.168Z",
      "rotado": null,
      "instalacion": null
    }
  ],
  "buzon": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "extension_id": "<id>",
    "nombre": "Buzón de Ejercicio API",
    "saludo_texto": "Ha llamado a Ejercicio API. Deje su mensaje después del tono.",
    "saludo_audio": null,
    "correo": null,
    "enviar_correo": 1,
    "adjuntar": 1,
    "transcribir": 1,
    "max_s": 120,
    "creado": "2026-10-16T21:45:00.168Z",
    "actualizado": "2026-10-16T21:45:00.168Z",
    "max_mensajes": 50,
    "aviso_activo": 0,
    "aviso_numero": null,
    "revisar": 0,
    "ofrecer_operadora": 1,
    "guion": null,
    "aviso_numeros": null,
    "aviso_modo": "tras",
    "reintentar": 0,
    "reintentos_max": 2,
    "compartido": 0,
    "extensiones_acceso": null,
    "abrir_caso": 1,
    "tiene_pin": false
  },
  "credencial": {
    "id": "<id>",
    "usuario_sip": "tf3zfmm96cfq100",
    "clave": "<secreto>",
    "realm": "pbx.forhosting.com",
    "transporte": "udp"
  }
}

{}

{
  "revertido": "<id>",
  "tabla": "colas",
  "fila_id": "<id>",
  "columnas": [
    "nombre"
  ],
  "fila": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Para editar",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.671Z"
  }
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "tabla": "colas",
  "fila_id": "<id>",
  "columna_clave": "id",
  "antes": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Para editar",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.058Z"
  },
  "despues": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Ya editada",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.287Z"
  },
  "actor": "apikey:<id> primera clave de sistema (sistema)",
  "origen": "api",
  "revertido_de": null,
  "creado": "2026-10-16T21:44:59.287Z",
  "cambios": {
    "nombre": {
      "antes": "Para editar",
      "despues": "Ya editada"
    }
  }
}

{
  "inquilino": "<cuenta>",
  "cambios": [
    {
      "id": "<id>",
      "tabla": "colas",
      "fila_id": "<id>",
      "actor": "apikey:<id> primera clave de sistema (sistema)",
      "origen": "api",
      "revertido_de": null,
      "creado": "2026-10-16T21:44:59.287Z",
      "cambios": {
        "nombre": {
          "antes": "Para editar",
          "despues": "Ya editada"
        }
      }
    }
  ]
}

{
  "activas": []
}

{}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "motivo": "ensayo",
  "desde": "2026-10-16T21:44:58.365Z",
  "hasta": "2026-10-16T21:44:58.588Z",
  "avisar": 1,
  "activo": 0,
  "creado": "2026-10-16T21:44:58.365Z"
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "motivo": "ensayo",
    "desde": "2026-10-16T21:44:58.365Z",
    "hasta": null,
    "avisar": 1,
    "activo": 1,
    "creado": "2026-10-16T21:44:58.365Z"
  }
]

{
  "motivo": "ensayo",
  "minutos": 5
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "motivo": "ensayo",
  "desde": "2026-10-16T21:44:58.365Z",
  "hasta": null,
  "avisar": 1,
  "activo": 1,
  "creado": "2026-10-16T21:44:58.365Z"
}

[]

{
  "destino": "buzon"
}

{
  "operadora": null
}

{
  "borrado": "<cuenta>"
}

{
  "nombre": "Ejercicio API 2026-10-16T21:44:54"
}

{
  "id": "<cuenta>",
  "nombre": "Ejercicio API 2026-10-16T21:44:54",
  "cuenta_portal": null,
  "cedula": null,
  "correo": null,
  "telefono": null,
  "plan": "zero",
  "zona": "America/Costa_Rica",
  "idioma": "es",
  "estado": "activo",
  "canales_max": 4,
  "notas": null,
  "creado": "2026-10-16T21:44:56.852Z",
  "actualizado": "2026-10-16T21:44:56.852Z",
  "canales_garantizados": 2,
  "modo_presion": "firme",
  "presion_canales": 1,
  "duracion_max_s": null,
  "operadora_tipo": null,
  "operadora_id": null,
  "filtro_anonimas": 0,
  "cdr_retencion_dias": null,
  "codigo_asunto_digitos": 0,
  "supervision_activa": 0,
  "canales_troncal": null,
  "limites": {
    "canales": 2,
    "canales_max": 4,
    "extensiones": 3,
    "retencion": 30,
    "tope_diario": 3,
    "tope_mensual": 25
  },
  "canales": {
    "existe": true,
    "garantizados": 2,
    "max": 4,
    "modo": "firme",
    "presion_canales": 1,
    "por_troncal": null
  }
}

Sitzungen: Der Browser hält nie einen dauerhaften Schlüssel

Kurzlebige Zugangsdaten, gedeckelt bei 60 Minuten, die keine dauerhaften ausstellen können. Das ist der Vertrag, wenn Sie den Knopf bauen.

• Nur das Portal darf eine ausstellen. Eine Sitzung auszustellen braucht einen Einrichtungsschlüssel, denn nur das Portal kann behaupten, dass hinter der Anfrage ein angemeldeter Kunde steht. VOICE weiß nichts von Kundenpasswörtern und muss es auch nicht.
• Sie entsteht nie ohne Ablauf. Fragt niemand nach einer Dauer, wird eine gesetzt. Ein Bereich, der zum Ablaufen da ist und ewig geboren werden könnte, ist schlimmer als gar keiner — weil man ihm vertraut.
• Mehr Zeit zu verlangen bringt nichts. Es gibt eine harte Obergrenze. Dass jemand acht Stunden verlangt, macht die Zugangsdaten nicht sicher.
• Sie kann sich nicht selbst befördern. Die Schlüsselverwaltung liegt vollständig hinter dem Einrichtungsbereich, eine Sitzung kann sich also keinen dauerhaften Schlüssel ausstellen. Das wird im Router erzwungen, bevor irgendein Handler läuft.
• Sie lässt sich vorzeitig beenden. Die Kennung kommt beim Ausstellen zurück — genau damit Sie sie vor der Zeit widerrufen können.

Webhooksüber die API

Ihre Systeme erfahren, was passiert ist, statt alle paar Sekunden nachzufragen. 31 Ereignisse, signiert, mit Wiederholung, und keines fällt still unter den Tisch.

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

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

Jede Zustellung ist signiert: Die Signatur deckt den Zeitstempel und genau den Rumpf ab, den Sie erhalten haben — prüfen Sie sie also gegen die rohen Bytes und nicht gegen eine neu serialisierte Kopie. Das Geheimnis wird beim Anlegen des Abonnements einmal angezeigt und lässt sich wechseln, ohne die Zustellungen anzuhalten.

Eine fehlgeschlagene Zustellung wird nach 10 · 30 · 60 · 300 · 900 · 3600 Sekunden erneut versucht, und jeder Versuch bekommt 10 Sekunden. Ein Abonnement, das weiterhin fehlschlägt, wird nach 20 Fehlschlägen in Folge pausiert, statt stillschweigend verworfen zu werden — und Sie sehen jeden Versuch.

Die Ereignisse

Der Live-Kanalechter Anruf

Webhooks reisen in Bündeln und kommen binnen Sekunden an. Manches muss jetzt auf dem Bildschirm stehen: Eine Lampe, die zeigt, dass ein Kollege telefoniert, darf nicht fünfzehn Sekunden zu spät sein.

• Was er transportiert. Anrufe, während sie passieren, neue Nachrichten und den Lampenzustand jeder Nebenstelle — das ist es, was ein Besetztlampenfeld auf einem Bildschirm überhaupt erst lebendig macht.
• Er ist nur lesend.über die API Sie können einen Zugang zum Kanal öffnen, ohne ein Telefon herauszugeben: zuzusehen, was passiert, sollte keine Zugangsdaten erfordern, die auch etwas ändern können.
• Er ersetzt keine Webhooks. Der Live-Kanal ist für einen Bildschirm, auf den jemand schaut. Wenn es darauf ankommt, dass Ihr System es erfährt, nehmen Sie einen Webhook: Er wiederholt, und er hängt nicht an einem offenen Socket.

Wie die Nachweise zu lesen sind

Jede Funktion auf dieser Seite trägt einen Nachweis, wie sie geprüft wurde. Wir veröffentlichen auch die, die noch niemand ausgeführt hat — so gekennzeichnet, denn dass Sie es selbst herausfinden, wäre schlimmer.

114 Funktionen, am 2026-09-19 aus der Anlage gezählt.

Der Nachweis gehört zu einer Funktion, nicht zu einer einzelnen Zeile: Wo eine Funktion mehrere Codes abdeckt, zeigen alle die Stufe der Gruppe. Ein Nachweis kann also untertreiben, was tatsächlich geprüft wurde — nie übertreiben. Das ist die einzige Richtung, in die wir auf einer Seite, die Sie als Versprechen lesen, falsch liegen wollen.

Glossar

Die Wörter, die eine Telefonanlage benutzt und sonst nichts.