Transfer

transfer Function は、一般的な転送の手順を1つの宣言的な Function にまとめたものです。 これにより、dial/refer、保留音、ブリーフィング、確認ゲート、フォールバックのルーティングを 手動で組み合わせる必要がなくなります。大きく分けて2つのモードがあります。

• blind — 転送先の応答を待たずに、直ちに通話を引き渡します。SIP REFER (blindMethod: 'refer')またはブリッジされた発信通話(blindMethod: 'dial')として実装されます。
• warm — 発信者を接続する前に、アプリケーションが転送先にブリーフィングを行います。発信者はパーク(保留、callerPresent: false)されるか、三者会議に参加(callerPresent: true)します。

転送が正常に完了しなかった場合(無応答、話中、拒否、エラー)、設定可能な disposition によって発信者の扱いが決まります。アプリケーションに戻す、 ボイスメールに送る、または切断するのいずれかです。

{
  "verb": "transfer",
  "mode": "blind",
  "target": [
    { "type": "phone", "number": "+815099990011" }
  ]
}

音声によるブリーフィング、保留音、誰も応答しなかった場合のフォールバックを備えた、パークありの warm 転送:

{
  "verb": "transfer",
  "mode": "warm",
  "callerPresent": false,
  "target": [
    { "type": "phone", "number": "+815099990010" }
  ],
  "brief": {
    "text": "I have a customer on the line who needs help with their account."
  },
  "onHoldHook": "/hold-music",
  "disposition": {
    "onNoAnswer": "return",
    "onBusy": "return"
  },
  "actionHook": "/transfer-complete"
}

パラメータ

blind または warm。blind は転送先の応答を待たずに直ちに通話を引き渡します。 warm は発信者を接続する前に、アプリケーションが転送先にブリーフィングを 行えるようにします。

1つ以上の通話転送先(dial Function の target と同じ構造)。 すべての転送先に同時に発信し、最初に応答したものが選ばれます。

blind のみ。refer はリモート側に SIP REFER を送信します。dial はブリッジされた 発信通話を行います。これは自動検出されません。REFER が適切でない場合(例: 上流のキャリアが REFER を受け付けない PSTN 番号への転送)は、明示的に dial を設定してください。

warm のみ。true の場合、発信者は三者会議に追加され、ブリーフィングを聞くことができます。 false の場合、発信者はパーク(保留)され、アプリケーションと転送先の間の会話を 聞くことはありません。

転送先に提示する発信者番号。

warm + パークの場合のみ(callerPresent: false)。転送先へのブリーフィング中に、 パークされた発信者に対して実行する Function を返す Webhook。例: 保留音を play する。 callerPresent が true の場合は無視されます。

onNoAnswer の disposition を適用するまでに、転送先の応答を待つ秒数。

warm のみ。発信者を接続する前に、転送先(人)に対して音声で伝える 要約の文字どおりの内容。

転送先に対して読み上げるブリーフィングのテキスト。

ブリーフィングに使用する音声/ベンダー(任意。synthesizer オブジェクト)。 デフォルトはセッションの合成エンジンです。

任意の、人側の受け入れゲート。転送先はプロンプトを聞き、転送を受け入れるには 指定された数字を押す必要があります。誤った数字、タイムアウト、または切断は decline として扱われます。

転送先に再生するプロンプトのテキストまたは URL。

転送を受け入れるために転送先が押す必要がある DTMF の1桁の数字。

warm のみ。転送先レグで実行する任意の留守番電話検出 (dial Function と同じ amd 構造)。デフォルトではオフです。machine の結果は decline として扱われます。

転送が正常に完了しなかった場合の、結果ごとのフォールバックアクション。各キーには return、voicemail、または hangup を指定でき、デフォルトは return です。

転送先が timeout 以内に応答しなかった場合のアクション。

転送先が話中を返した場合のアクション。

転送先が拒否した場合のアクション。confirm ゲートの失敗、AMD による留守番電話の検出、 または転送先による明示的な通話の拒否が該当します。

転送先レグでプロトコルレベルのエラーが発生した場合のアクション。

発信者をボイスメールにルーティングするための SIP URI または HTTP URL。いずれかの disposition の値が voicemail である場合は必須です。

転送が確定したときに呼び出されます。通話がブリッジされた、発信者に戻された、 ボイスメールに送られた、失敗した、のいずれの場合も対象です。actionHook のプロパティを参照してください。

進行中の転送ライフサイクルイベントを受け取るための任意のフック。 eventHook のイベントを参照してください。

この Function インスタンスの任意の一意な識別子。

actionHook のプロパティ

転送が確定すると、actionHook は(標準の通話属性に加えて)次の追加パラメータと共に 呼び出されます。

• transfer_result — 次のいずれか:
• bridged — 発信者と転送先が接続され、転送が完了した。
• returned — 転送は接続されず、発信者はアプリケーションに戻された(制御は後続の Function、または actionHook から返された Function に移ります)。
• failed — 転送が hangup の disposition または致命的なエラーで終了した。
• transfer_reason — 根本的な原因:
• completed — 転送先が応答し、通話がブリッジされた。
• no-answer — 転送先が timeout 以内に応答しなかった。
• busy — 転送先が話中を返した。
• declined — confirm ゲートの失敗、AMD による留守番電話の検出、または転送先による拒否。
• caller-abandoned — 転送が完了する前に発信者が切断した。
• error — 転送先レグでのプロトコルレベルのエラー。

eventHook のイベント

eventHook が設定されている場合、Wipple CPaaS は次のライフサイクルイベントを POST します。各ペイロードには 標準の通話属性に加えて、event_type とイベント固有のフィールドが含まれます。

• transfer.initiated — 開始時に発生します。mode と callerPresent を含みます。
• transfer.bridged — 発信者と転送先が接続された。
• transfer.returned — 転送は接続されなかった。transfer_reason を含みます。
• transfer.failed — 転送が失敗で終了した。transfer_reason を含みます。

eventHook の失敗が転送を中断することはありません。

会話型エージェントからの有人転送

音声エージェントからツール呼び出しとして人に引き継ぎたい場合は、transfer Function を 直接使用するのではなく、agent または llm Function に宣言的な handoff ブロックを追加します。ランタイムは transfer_to_human ツールを 注入し、モデルがそれを呼び出したときにこれと同じ転送手順を実行します。

ライブコールコントロール

REST API 経由で transfer ボディを持つ updateCall リクエストを発行することで、 進行中の通話に転送を注入することもできます。これは、発信者をパークしてから 外部のトリガーで転送する場合に便利です。 REST コールコントロールのリファレンスを参照してください。