Zenn
KWCPLUSPublicationへの投稿
🔰

Vonage 電話番号のアカウント内移動

小原聖健
2024/10/07に公開
voice
Vonage
tech

こんにちは。KDDI ウェブコミュニケーションズ（KWC）の小原です。

このガイドでは、Vonage の Subaccounts API を利用してアカウント内の電話番号移動（Transfer number）を行う方法についてご案内します。

対象

  • Vonage で所有する電話番号をサブアカウントもしくは親アカウントに移動したい方

注意点

電話番号移動には KWC 契約と Vonage 契約で異なる部分があるため、契約内容に応じて対応方法が異なります。以下の表をご参照ください。

KWC 契約 Vonage 契約
ダッシュボードの URL https://kwc.dashboard.vonage.com/ https://dashboard.nexmo.com/
ダッシュボードのメッセージ KWC API Dashboard Vonage API Dashboard
Subaccounts API の利用 アップグレード後は申請不要で利用可能 要申請
同一親アカウント内の移動 API で可能 API で可能
別アカウントへの移動 要申請（申請項目はこちら） 要申請
申請／問い合わせ先 お問い合わせ お問い合わせ
  • Vonage で契約したお客様は Subaccounts API と Number transfer の有効化を Vonage にご依頼ください
    • KWC で契約したお客様は、アップグレード後は依頼不要でご利用いただけます。トライアル中は Subaccounts API はご利用できません
  • API による電話番号の移動ができるのはひとつの親アカウント内のみです。別の親アカウントへの移動についてはお問い合わせください（下図）
    • KWC で契約したアカウントと、Vonage で契約したアカウント間の電話番号の移動は現在できません
  • ダッシュボードから GUI での移動はできません

移動可能なアカウント

Transfer number

電話番号の移動は Subaccounts API の Transfer number を利用します。

以下は、利用するための認証や API Endpoint、パラメータ情報です。

認証

ダッシュボードの「API設定」から確認できる「API Key」と「API Secret」を利用します。常に親アカウントの API Key を利用します。

API Key と API Secret を : で連結し、Base64 したトークンで Basic 認証します。

Authorization: Basic base64(API_KEY:API_SECRET)

API Endpoint

:api_key は親アカウントの API Key を常に指定します。

POST https://api.nexmo.com/accounts/:api_key/transfer-number

パラメータ

API Endpoint に渡すパラメータは 4 つです。

キー 概要
from 移動元の API Key
to 移動先の API Key
number 移動する電話番号。E.164 形式。Ex. 8150XXXXYYYY
country 電話番号の国。日本番号なら JP。アメリカ番号なら US

cURL サンプル

Vonage は REST API のため curl でも実行可能です。環境変数は次とします。

環境変数 概要
API_KEY 親カウントの API Key
API_SECRET 親アカウントの API Secret
PARENT_API_KEY 親アカウントの API KEY
SUBACCOUNT_API_KEY サブアカウントの API Key
NUMBER 移動する電話番号。E.164 形式。Ex. 8150XXXXYYYY
COUNTRY 電話番号の国。日本番号なら JP。アメリカ番号なら US

親アカウント $PARENT_API_KEY からサブアカウント $SUBACCOUNT_API_KEY への番号移動の例です。

curl -X POST \
  -u "$API_KEY:$API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "'"$PARENT_API_KEY"'",
    "to": "'"$SUBACCOUNT_API_KEY"'",
    "number": "'"$NUMBER"'",
    "country": "'"$COUNTRY"'"
  }' \
  "https://api.nexmo.com/accounts/$API_KEY/transfer-number"

移動した番号を戻す（$SUBACCOUNT_API_KEYから$PARENT_API_KEY）のであれば from と to の指定を逆にします。

curl -X POST \
  -u "$API_KEY:$API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "'"$SUBACCOUNT_API_KEY"'",
    "to": "'"$PARENT_API_KEY"'",
    "number": "'"$NUMBER"'",
    "country": "'"$COUNTRY"'"
  }' \
  "https://api.nexmo.com/accounts/$API_KEY/transfer-number"

HTTPie であれば下記です。

http -a "$API_KEY:$API_SECRET" \
  POST "https://api.nexmo.com/accounts/$API_KEY/transfer-number" \
  from="$PARENT_API_KEY" \
  to="$SUBACCOUNT_API_KEY" \
  number="$NUMBER" \
  country="$COUNTRY"

SDK

Transfer number はサンプルコードがある言語と、ない言語があります。

サンプルコードあり

サンプルコードなし

サンプルコードはありませんが、GitHub には参考になるコードとテストが公開されています。

参考として Node.js と Ruby のサンプルを紹介します。

Node.js サンプル

最新 LTS の Node.js をインストールし、必要なライブラリを npm でインストールします。

npm install @vonage/auth
npm install @vonage/subaccounts

app.js としてファイルを保存します。

app.js
const { Auth } = require('@vonage/auth')
const { SubAccounts } = require('@vonage/subaccounts')

const credentials = new Auth({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
})

const subAccountClient = new SubAccounts(credentials)

const params = {
  from: process.env.PARENT_API_KEY,
  to: process.env.SUBACCOUNT_API_KEY,
  number: process.env.NUMBER,
  country: process.env.COUNTRY
}
subAccountClient.transferNumber(params)
  .then((response) => console.log(response))
  .catch((error) => console.error(error))

実行が成功をすると、実行結果が返ります。

$ node app.js
{
  from: '1111111',
  to: '2222222',
  number: '8150XXXXYYYY',
  country: 'JP',
  masterAccountId: '1111111'
}

参考資料

Ruby サンプル

安定版の最新 Ruby をインストールし、必要なライブラリを gem でインストールします。

gem install vonage

app.rb としてファイルを保存します。

app.rb
# frozen_string_literal: true

require 'vonage'

api_key    = ENV.fetch('API_KEY', nil)
api_secret = ENV.fetch('API_SECRET', nil)
client = Vonage::Client.new(api_key:, api_secret:)

from    = ENV.fetch('PARENT_API_KEY', nil)
to      = ENV.fetch('SUBACCOUNT_API_KEY', nil)
number  = ENV.fetch('NUMBER', nil)
country = ENV.fetch('COUNTRY', nil)
pp client.subaccounts.transfer_number(from:, to:, number:, country:)

実行が成功をすると、実行結果が返ります。

$ ruby app.rb
#<Vonage::Response:0x0000000000000000
 @entity=
  #<Vonage::Entity:0x0000000000000000
   @attributes={:from=>"1111111", :to=>"2222222", :number=>"8150XXXXYYYY", :country=>"JP", :master_account_id=>"1111111"}>,
 @http_response=#<Net::HTTPOK 200 OK readbody=true>>

おわりに

親アカウントは API を利用して電話番号の移動が可能です。これにより、親アカウントで取得した電話番号をサブアカウントに移動する一元的な管理が行えます。Vonage 開発の運用にお役立てください。

参考資料

KWCPLUS
KWCPLUSPublication

株式会社KDDIウェブコミュニケーションズ Tech Blog

Discussion