ドキュメント

5分ではじめる電話システム

以下はすべて、すでにお客さまのアカウントに揃っています。インストール作業も、技術者の訪問も、買い足す機材も必要ありません。

• 番号と内線はすでにあります。 アカウントの開設と同時に、各端末に必要なSIP認証情報とあわせて作られます。内線は人または席、番号は外の人が押すものです。
• 番号の行き先を決めます。 「番号」タブで、その番号にかかってきた通話をどうするか決めます。内線を鳴らす、グループを鳴らす、メニューを開く、待ち行列に入れる、営業時間に従う。
• ブラウザで出ます。 「電話」タブを開いてマイクを許可すれば、そのタブが動く電話機になります。*43のエコー確認にかければ、自分の声が返ってきます。
• そのあとに営業時間と留守番電話を。 夜7時に通話を取りこぼさないための2つであり、新しい電話システムにいちばん足りていない2つでもあります。

お急ぎなら、開始テンプレートが5つあります。診療所、法律事務所、工場、店舗、家庭の回線です。営業時間、着信ルート、時間外の留守番電話を1回のリクエストで作ります。すでに設定済みのものを上書きすることはありません。

管理画面への入り方APIで

管理画面はVOICEのページ上にあり、セッションがあるときだけ表示されます。そのセッションを発行するのはお客さま専用ページで、ここで何かを入力することはありません。

そのボタンを作る方へ。契約はこれだけです：

POST /inquilinos/:inquilino/sesiones     # システム権限：発行できるのはポータルだけ
{ "minutos": 15 }
→ { "clave": "pbx_ses_…", "caduca": "…", "ambito": "sesion", "minutos_max": 60 }

/denwa-koukanki#t=<clave>&exp=<ISO>&v=<inquilino>

認証情報をクエリではなくフラグメントで運ぶのは意図的です。フラグメントはサーバーに送られないため、Refererヘッダーにも、アクセスログにも、途中の中継装置にも残りません。有効期限は数分、上限があり、恒久的な鍵を作ることはできません。

管理画面をタブごとにAPIで

16個のセクションがあり、8言語すべてで同じ16個です。ここにあるものはすべてAPIにもあります。

ブラウザの中の電話機実際の通話

タブがそのまま電話機になります。アプリのインストールも、卓上電話の購入も、番号の移行も要りません。ブラウザから登録する、お客さま自身の電話システムの内線です。

• 本物の内線です。 ブラウザは卓上電話と同じように電話システムへ登録し、音声は暗号化された経路を通ります。番号にかけてきた人はタブに到達でき、タブから外へ発信もできます。
• タブは開いておく必要があります。 閉じたタブは電源の抜けた電話機です。それがブラウザ電話の正直な限界であり、卓上機を置き換えるのではなく補う理由でもあります。
• 誰が通話中かがわかります。実際の通話 同僚のランプが空き・呼び出し中・通話中とリアルタイムに変わるので、転送しようとする前に転送先がいるかどうかがわかります。
• 通話中のまま別の端末へ移せます。未実施 「出かけるのに通話中だ」というとき、切らずに携帯へ移せます。キーパッドのコードではなくボタンにしてあるのは意図的です。通話を移す人の前には画面があります。
• 転送・保留・録音は、ほかの電話機と同じコードです。 押すのではなくダイヤルするので、ブラウザ電話で覚えたことが卓上電話でも携帯でもそのまま使えます。

ブラウザの電話機がお客さまのパソコンに録音することはありません。録音は電話システムの中で行われ、そこで誰を録音してよいか、誰に知らせるべきかの規則が適用されます。「録音と法律」をご覧ください。

電話機から押すコード

慣習があるところは慣習どおりに残しています（*72転送、*78応答拒否、*97留守番電話、*8代理応答、*69直前の着信）。キーパッドのコードの意味はそこにあります。機能はすでに管理画面にあり、コードは20年間*72を押してきた人が管理画面を信用できるようにするためのものです。

受話器を置いた状態で押す

通話中に押す

取り次ぎ転送の相談中に押す

会議室の中で押す

2つの意味を持つコードがありますが、衝突はしません。*1は通常の通話では「いま録音する」、相談中は「転送を完了する」、会議室の中では「部屋を閉じる」です。同じ電話機の別の状態であり、処理するコードも別です。

新しい電話機を信用する前に： 卓上電話機やアダプターは自前のスターコードを自分で処理してしまい、こちらへは送りません。コードを押して無音のあとに発信音が戻ったら、それは電話機が飲み込んだのであって、電話システムには何も届いていません。新しい機種を配る前に、現在の一覧と突き合わせる確認をご依頼ください。

どの電話機からでも使える留守番電話テストベンチ

*97を押して暗証番号を入れれば、留守番電話のすべてがそこにあります。アプリもブラウザも要りません。借りた電話からかける経営者のために書かれた仕組みです。

メインメニュー

伝言の再生中

応答メッセージのメニュー

通話そのものを受ける

鳴らすグループができるのは「複数の場所で鳴らす」ことだけです。この一覧にあるものは、いずれもグループにはできないことをします。

• 待ち行列。未実施 待ち行列は前に何人いるか、ふだんどれくらいかかるかを知っているので、それを伝えられます。待ち時間は自社の直近の通話から実測しており、作り出すことはありません。標本が3件未満なら何も言いません。受付中の人が誰もいなければ、誰も待たせません。
• 待ち行列からの折り返し。未実施 しばらく待ったところで提案し、まもなく応答できる見込みなら提案しません。要求は再起動しても残ります。頼んだ人は電話を切るからです。折り返しは列の先頭に入ります。それが約束したことだからです。
• 会議室。未実施 番号と2つの暗証番号を持つ部屋。1つは入室用、もう1つは進行役用です。どこにもアカウントは要りません。入退室は各自が録音した名前で読み上げられます。
• 名前でさがす電話帳。テストベンチ かけた人がキーパッドで名前を打つとつながります。名前は語ごとに別々に索引しています。こちらでは姓が2つあるのが普通で、最初の姓だけで探すと会社の半分が出てきてしまうからです。アクセント記号とñは同一視するので、「Muñoz」は686で見つかります。
• オペレーターへの0。未実施 電話に対するもっとも普遍的な期待は、たぶん「人につながること」です。0はオペレーターから全体の留守番電話へ、さらに音声での案内へと順に降りていきます。黙って切れることはありません。
• 保留と代理応答。未実施 通話を預けると、番号のついた場所で保留音とともに待ちます。その間に別の席まで歩けます。誰でもその番号を押せば取り出せます。隣で鳴っている電話を取るのは*8です。

チャネル：保証・貸出・返却APIで

固定の上限では実現できない部分です。プランを選ぶ前に理解しておく価値があります。

• 保証分。 プランが販売する同時通話数です。電話システムが何をしていても必ず通り、誰にも取り上げられません。
• 貸出分。 保証を超えた分は、電話システムに空きがあればそれを使います。ふだんはここに収まり、追加費用はかかりません。
• 予備。 誰にも貸し出さないチャネルの余裕分です。誰もがいつでも自分の保証分に到達できるようにするためにあります。
• 返却。 電話システムが混み合ったとき、貸出分の通話は他社の保証を守るために返却されることがあります。これを有効にしたアカウントだけが対象で、保証の範囲内の通話は対象外、緊急通報も対象外、そして無言では行いません。手放す前に必ず音声で知らせます。
• 二重に売ることはできません。 すべての保証の合計に予備を足したものが、収まらなければなりません。契約時に検査し、収まらないプランは拒否されます。それが「保証」という言葉に意味を与えています。
• いつ効いたかも見えます。 混雑は月間の合計ではなく、時刻つきの出来事として報告します。「30日で12件の拒否」は雑音にしか読めませんが、「先週の火曜、10時から11時のあいだに5人が話中を聞いた」なら手を打てます。

何かが壊れたときに起きること

電話システムの真価が問われるのは停電した日であって、すべてが動いている日ではありません。

• 出口は1つではありません。 電話システムは複数の独立した回線で外の世界とつながり、そのあいだを自分で選びます。お客さまが設定することも、切り替わるのを目にすることもありません。
• 「動いている」を正しい基準で測ります。 回線が候補になるのは、インターネットと電話網の両方に届いているときだけです。前者だけを見るのが、すべてのランプが緑のまま回線が使えなくなる原因です。
• 停電のあとは自分で復旧します。 電気が戻ると、電話システムとネットワーク機器が同時に起動し、順番は毎回同じとは限りません。その順番を信じるかわりに、実際に持っているものとあるべきものを比べ続け、自分で直します。再試行の回数には上限があり、本当の故障は堂々巡りにせず報告に回します。
• 自分を直すために通話を切ることはありません。 会話を中断してしまう修復は、通話が1件もなくなるまで待ちます。

録音と留守番電話の伝言は電話システムの外に保存しているので、機械そのものより長く残ります。

プランと通話料

プランは5種類、年額$100から$300まで。1ライセンスにつき1番号です。コスタリカの番号への着信は1分$0.00です。

通話料

米ドル表示、税込みです。携帯あては提携事業者が秒単位で計測します。1ライセンスにつき1番号を含みます。追加した番号は同じ電話システム、同じ通話フロー、同じ管理画面を共有します。

録音と法律APIで

録音された音声は他人の声です。コスタリカ法8968がこれを規律しており、設計は都合の良さではなくそこから導かれています。

• 何を録音するかはお客さまが決めます。APIで すべて、特定の内線だけ、特定の番号への着信だけ。あるいは何も録音しない。それも正しい答えです。
• 保管期間はプランに含まれます。 録音は期限が来ると自動で消えます。唯一の例外は迷惑電話の記録に紐づいた録音で、記録を閉じるまで期限切れになりません。閉じると通常の期限に戻ります。「いますぐ削除」にはなりません。
• 共有はアクセス権の付与ではありません。 署名つきのリンクは1件の録音だけを再生し、自動で期限切れになり、取り消せます。送った相手がお客さまのアカウントを見ることはありません。
• 再生はすべて記録されます。 誰がどの録音をいつ再生したか。他人の声である以上、誰が聞いたかを知っていることは、預かることの一部です。
• 分類できます。 顧客、見込み客、社内。既定値はあえて置いていません。未分類は正直であり、機械が推測したラベルは、あとから人が選んだラベルと区別がつかなくなるからです。

双方に必ず通知します。 電話システムに録音を頼むと、告知の義務も一緒に返ってきます。この2つは切り離せません。切り離すことこそ、知らないまま録音される人が生まれる仕組みだからです。会議室では、入室する人ごとに告知します。

上限・保護・取り消し

悪い一日がどこまで悪くなるかを決めるもの。盗まれた認証情報、経路の設定ミス、鳴りやまない番号です。

• 1日あたり・1か月あたりの利用上限。テストベンチ 盗まれた認証情報が金額になるのを止めるのがこれです。上限に達すると発信は止まります。
• 内線ごとに、どこへかけられるか。APIで 内線のみ、国内、携帯、あるいはすべて。倉庫の電話が有料ダイヤルにかけられる理由はありません。緊急通報がこれに妨げられることはありません。
• かける前の料金。APIで その番号にかけるといくらかを尋ねると、実際に通話をつなぐのと同じ仕組みが計算して答えます。適用されるとは限らない料金表からではありません。
• ふるまいを見る不正検知。未実施 不自然な速さ、かけたことのない国、誰も働いていない時間帯。知らせはしますが、切りません。ここでの誤検知は煩わしい通知ではなく、成立しなかった通話だからです。何かを言うまでに2つの兆候を必要とします。毎日鳴る警報は無視されるようになるからです。
• しつこい発信元には印を付けます。未実施 同じ番号から2分で5回は、しつこいお客さまではなく自動発信装置です。初期状態では知らせるだけです。自動で拒否するかはお客さまが選びます。誤検知は、二度とかけられなくなったお客さまを1人失うことだからです。
• 迷惑電話の記録。未実施 時刻、経路、音声を通報用にまとめて保管します。記録を作っても相手を拒否はしません。新しい着信は証拠が1つ増えることであり、決めるのはお客さまであってこちらではありません。
• 端末がどれだけつながっていたか。APIで こちらの稼働率ではなく、お客さまのものです。そして期間のうち実際に測れた割合を必ず表示します。誰も見ていなかった時間を黙って除いた百分率は、いつも都合のよい側に外れるからです。
• 何が変わり、誰が変え、どう戻すか。未実施 「昨日は動いていた」は答えのある問いです。設定の変更はすべて記録され、元に戻せます。戻すときは、そのあいだに誰かが同じ項目を触っていないかを確かめます。黙って上書きはしません。

停止しているものと、その理由

動くところだけを書いた手引きは、残りをご自分で見つけさせることになり、それはいつも最悪のタイミングで見つかります。この一覧はスイッチそのものから生成しているので、すでに有効になったものを停止中と書くことはできません。

APIAPIで

管理画面はこのAPIの利用者の一つにすぎません。手で変えられることはすべてプログラムからも変えられます。鍵はお客さまのアカウントのものです。

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

権限の範囲

うまくいかなかったとき

現在、レート制限はほとんどありません。 唯一あるのは、ブラウザの電話機を開こうとする試行のあいだに置く数秒の待ち時間です。全体的な上限はありません。推測の上に作ってから気づかれるより、先に申し上げます。常識の範囲でお使いください。重い処理をお考えなら、事前にお知らせください。あとからではなく、ご一緒に測ります。

到達できる範囲

合計267件のエンドポイント。2026-08-17に電話システム自身から読み取りました。

この表は要約です。古くならない一覧は、電話システムが自分自身について生成するものです： GET /api.

セッション：ブラウザは恒久的な鍵を持ちません

上限60分の短命な認証情報で、恒久的な鍵を作ることはできません。ボタンを作る側にとっては、これが契約のすべてです。

• 発行できるのはポータルだけです。 セッションの発行には運用管理用の鍵が必要です。リクエストの背後にログイン済みのお客さまがいると言えるのはポータルだけだからです。VOICEはお客さまのパスワードを知りませんし、知る必要もありません。
• 期限なしで生まれることはありません。 期間の指定がなければ、こちらで付けます。期限切れになるために存在する権限が永遠に生まれうるなら、持たないほうがましです。人はそれを信用してしまうからです。
• 長く要求しても通りません。 上限は固定です。呼び出し側が8時間と頼んでも、認証情報が安全になるわけではありません。
• 自分を昇格させることはできません。 鍵の管理はすべて運用管理の権限の内側にあるので、セッションが恒久的な鍵を作ることはできません。これはハンドラーが動く前、ルーターの段階で適用されます。
• 早めに終わらせられます。 発行時に識別子が返るのは、まさに期限前に取り消せるようにするためです。

WebhookAPIで

数秒おきに問い合わせるのではなく、起きたことをお客さまのシステムにお知らせします。28種類のイベント、署名つき、再試行あり、黙って落とすことはありません。

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

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

配信にはすべて署名が付きます。署名はタイムスタンプと受け取った本文そのものを対象にしているので、再度シリアライズしたものではなく生のバイト列に対して検証してください。秘密鍵は購読を作るときに一度だけ表示され、配信を止めずに入れ替えられます。

失敗した配信は10 · 30 · 60 · 300 · 900 · 3600秒後に再試行し、1回の試行に10秒を与えます。失敗が続く購読は20回連続で一時停止します。黙って捨てることはありません。すべての試行は確認できます。

イベント一覧

ライブチャネル実際の通話

Webhookはまとめて送られ、数秒で届きます。ただし、いま画面に出ていなければ意味のないものもあります。同僚が通話中だと示すランプが15秒遅れては役に立ちません。

• 何が流れるか。 起きたままの通話、新しい伝言、そして各内線のランプの状態。画面上の在席ランプが本当に生きているのはこれのおかげです。
• 読み取り専用です。未実施 電話機を渡さずにチャネルの利用券を発行できます。何が起きているかを見るために、変更もできてしまう認証情報が必要であってはなりません。
• Webhookの代わりにはなりません。 ライブチャネルは誰かが見ている画面のためのものです。お客さまのシステムが確実に知る必要があるならWebhookを使ってください。再試行があり、ソケットが開いていることに依存しません。

バッジの読み方

このページの機能にはすべて、どのように確認したかを示すバッジが付いています。まだ実行していないものも、そう明記したうえで掲載します。お客さまがご自分で気づくほうが悪いからです。

112件の機能。2026-08-19に電話システムから数えました。

バッジは機能単位のもので、1行単位ではありません。1つの機能が複数のコードにまたがる場合、そのすべてにグループの水準を表示します。つまりバッジは実際に試した範囲より控えめに出ることはあっても、大きく出ることはありません。約束として読まれるページで間違えてよいのは、その方向だけです。

用語集

電話システムだけが使う言葉。