はじめに (Getting started)

このページでは、空のプロジェクトから動作する音声アプリケーションまでを 5 つのステップで説明します。最後まで進めると、着信通話を受信し、Function で応答し、REST API を通じて発信通話を実行できるようになります。

前提条件

API キーを持つ Wipple CPaaS アカウント。
アカウントにプロビジョニングされた電話番号。
アカウント上のアプリケーション。電話番号がそのアプリケーションにルーティングされていること。
お客様のコードに対して公開されており到達可能な HTTPS エンドポイント。開発中は、ローカルポートを HTTPS で公開するトンネリングツールで十分です。

このページ全体を通して、{API_ENDPOINT} はお客様に割り当てられた API ホスト名、{yourserver} はお客様のアプリケーションの公開ホスト名を表します。

ステップ 1: コールフックを作成する

コールフックは、新規通話が着信したときに Wipple CPaaS がリクエストする URL です。Function の JSON 配列で応答する必要があります。

Node.js (Express)

import express from 'express';

const app = express();
app.use(express.json());

app.post('/call', (req, res) => {
  const { from, to, call_sid } = req.body;
  console.log(`incoming call ${call_sid} from ${from} to ${to}`);

  res.json([
    {
      verb: 'say',
      text: 'Thank you for calling Miraicom. Please leave a message after the tone.'
    },
    {
      verb: 'listen',
      actionHook: '/voicemail',
      url: 'wss://{yourserver}/audio',
      playBeep: true,
      timeout: 30,
      finishOnKey: '#'
    },
    {
      verb: 'say',
      text: 'Thank you. Goodbye.'
    }
  ]);
});

app.post('/voicemail', (req, res) => {
  console.log('recording finished', req.body);
  res.json([]);
});

app.listen(3000);

Python (Flask)

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.post("/call")
def call_hook():
    body = request.get_json()
    print("incoming call", body["call_sid"], body["from"], body["to"])
    return jsonify([
        {
            "verb": "say",
            "text": "Thank you for calling Miraicom. Please leave a message after the tone."
        },
        {
            "verb": "listen",
            "actionHook": "/voicemail",
            "url": "wss://{yourserver}/audio",
            "playBeep": True,
            "timeout": 30,
            "finishOnKey": "#"
        },
        {"verb": "say", "text": "Thank you. Goodbye."}
    ])

@app.post("/voicemail")
def voicemail():
    print("recording finished", request.get_json())
    return jsonify([])

actionHook の値 /voicemail は相対 URL です。Wipple CPaaS は相対フック URL をコールフックの URL を基準に解決するため、https://{yourserver}/voicemail に POST します。

ステップ 2: アプリケーションを設定する

アプリケーションのコールフック URL を https://{yourserver}/call に設定し、ステータスイベントが必要な場合はコールステータスフックを https://{yourserver}/status のような URL に設定します。デフォルトの音声合成ベンダー、言語、音声を選択してください。say などの Function は、上書きしない限りこれらのデフォルト値を使用します。

ステップ 3: 通話を受信する

アプリケーションに紐付けた電話番号に電話をかけます。Wipple CPaaS は https://{yourserver}/call に対して、次のようなボディを持つリクエストを送信します。

{
  "call_sid": "d2515c3b-b79a-41a2-971a-445e769c823c",
  "application_sid": "72c5c38f-9bba-40ce-aa83-aaa6be55e1b5",
  "account_sid": "bad98250-b34d-459d-9e90-f97dfb9bc519",
  "direction": "inbound",
  "from": "+815099990001",
  "to": "+815099990002",
  "caller_name": "Miraicom Taro",
  "call_status": "trying",
  "sip_status": 100
}

プロパティの完全な一覧は新規通話 (POST) に記載されています。お客様のアプリケーションがステップ 1 の Function を返すと、発信者には挨拶とビープ音が聞こえ、録音はお客様の WebSocket エンドポイントにストリーミングされます。

ステップ 4: 発信通話を実行する

REST API を使って通話を発信します。call_hook は、着信側が応答した後に Wipple CPaaS がリクエストする URL を指定します。

curl -X POST "https://{API_ENDPOINT}/v1/Accounts/{AccountSid}/Calls" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+815099990001",
    "to": { "type": "phone", "number": "+815099990002" },
    "call_hook": { "url": "https://{yourserver}/outbound", "method": "POST" },
    "call_status_hook": { "url": "https://{yourserver}/status", "method": "POST" }
  }'

レスポンスには新しい通話の sid が含まれます。

{
  "sid": "2531329f-fb09-4ef7-887e-84e648214436"
}

通話が応答されると、Wipple CPaaS は https://{yourserver}/outbound をリクエストし、お客様のアプリケーションは着信通話の場合とまったく同じ方法で Function を返します。留守番電話検出や SIP ターゲットを含むすべてのオプションについては、通話の作成を参照してください。

ステップ 5: 通話ステータスを追跡する

コールステータスフックは、通話の状態が変化するたびに (trying、ringing、in-progress、completed など) リクエストを受け取ります。ハンドラーは HTTP 200 と空のボディで応答してください。Function を返す必要はありません。

app.post('/status', (req, res) => {
  const { call_sid, call_status, duration } = req.body;
  console.log(`call ${call_sid} is now ${call_status}`, duration ?? '');
  res.sendStatus(200);
});

次のステップ

Functions 概要を読み、続いて say、gather、dial から始めて個々の Function を参照してください。
進行中の通話をミュート、保留、録音、またはリダイレクトするには、通話の更新を使用します。
agent または llm Function を使って音声 AI エージェントを構築します。