vonage php sdk core
4.10.7
このライブラリには PHP バージョン 8.1 以上が必要です
VonageのAPIを利用するためのPHPクライアントライブラリです。これを使用するには、Vonage アカウントが必要です。ここから無料でサインアップしてください。
クライアント ライブラリを使用するには、Vonage アカウントを作成しておく必要があります。
PHP クライアント ライブラリをプロジェクトにインストールするには、Composer の使用をお勧めします。
composer require vonage/clientこれは実際には、HTTP クライアントとこのコア ライブラリを含むラッパー ライブラリを指していることに注意してください。必要に応じて、プロジェクトで使用する HTTP クライアントを選択して、このライブラリを Composer から直接インストールできます。
このライブラリを独自のプロジェクトで使用するために、このリポジトリのクローンを作成する必要はありません。 Composer を使用して Packagist からインストールします。
Composer を初めて使用する場合は、役立つと思われるリソースを以下に示します。
Composer を使用している場合は、オートローダーがプロジェクトのブートストラップ ファイルに含まれていることを確認してください。
require_once " vendor/autoload.php " ;API キーとシークレットを使用してクライアントを作成します。
$ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET )); テスト目的で、 vonage/clientリクエストを行う URL をapi.vonage.comから別のものに変更することができます。これを行うには、 VonageClientインスタンスを作成するときに、 base_api_urlを含む配列を 2 番目のパラメーターとして指定します。
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
[
' base_api_url ' => ' https://example.com '
]
);通常、 rest.nexmo.comにヒットする API の場合、コンストラクターにオプションとしてbase_rest_urlを指定すると、それらのリクエストが変更されます。
Vonage の SMS API を使用して SMS メッセージを送信するには、 $client->sms()->send()メソッドを呼び出します。
メッセージ オブジェクトは、 SMS メッセージの作成に使用されます。各メッセージ タイプは必要なパラメータを使用して構築でき、流暢なインターフェイスによりオプションのパラメータへのアクセスが提供されます。
$ text = new Vonage SMS Message SMS ( VONAGE_TO , VONAGE_FROM , ' Test message using PHP client library ' );
$ text -> setClientRef ( ' test-message ' );メッセージ オブジェクトはsendメソッドに渡されます。
$ response = $ client -> sms ()-> send ( $ text );送信後、メッセージ オブジェクトを使用して応答データにアクセスできます。
$ data = $ response -> current ();
echo " Sent message to " . $ data -> getTo () . " . Balance is now " . $ data -> getRemainingBalance () . PHP_EOL ;各 SMS メッセージは複数のメッセージに分割できるため、応答には生成された各メッセージのオブジェクトが含まれます。 PHP の標準count()関数を使用して、生成されたメッセージの数を確認できます。最初のメッセージを取得したい場合は、応答に対してcurrent()メソッドを使用できます。
$ data = $ response -> current ();
$ data -> getRemainingBalance ();
foreach ( $ response as $ index => $ data ){
$ data -> getRemainingBalance ();
}送信例には完全な動作例も含まれています。
SMS クライアント コード内で静的なisGsm7()メソッドを使用して、GSM-7 エンコードと Unicode のどちらを使用してメッセージを送信するかを決定できます。以下に例を示します。
$ sms = new Vonage SMS Message SMS ( ' 123 ' , ' 456 ' , ' is this gsm7? ' );
if ( Vonage SMS Message SMS :: isGsm7 ( $ text )) {
$ sms -> setType ( ' text ' );
} else {
$ sms -> setType ( ' unicode ' );
}受信メッセージは Webhook としてアプリケーションに送信されます。クライアント ライブラリは、Webhook から受信メッセージ オブジェクトを作成する方法を提供します。
try {
$ inbound = Vonage SMS Webhook Factory:: createFromGlobals ();
error_log ( $ inbound -> getText ());
} catch ( InvalidArgumentException $ e ) {
error_log ( ' invalid message ' );
}メッセージ署名に関するドキュメントもお読みください。
SMS API は、API シークレットではなく「署名シークレット」を使用して署名を生成および追加することにより、メッセージに署名する機能をサポートしています。サポートされているアルゴリズムは次のとおりです。
md5hash1md5sha1sha256sha512アプリケーションと Vonage の両方が、どのアルゴリズムが使用されるかについて合意する必要があります。ダッシュボードでアカウント設定ページにアクセスし、「API 設定」で使用するアルゴリズムを選択できます。これは、「署名シークレット」を見つける場所でもあります (API シークレットとは異なります)。
これらの資格情報と使用するアルゴリズムを使用してクライアントを作成します。たとえば、次のようになります。
$ client = new Vonage Client ( new Vonage Client Credentials SignatureSecret ( API_KEY , SIGNATURE_SECRET , ' sha256 ' ));このクライアントを使用すると、SMS API メッセージが署名付きメッセージとして送信されます。
メッセージ署名に関するドキュメントもお読みください。
受信メッセージに対してメッセージ署名を有効にしている場合、SMS Webhook にはフィールドsig 、 nonce 、およびtimestampが含まれます。署名が Vonage からのものであることを確認するには、受信データ、署名シークレット、および署名メソッドを使用して Signature オブジェクトを作成します。次に、受信した実際の署名 (通常は_GET['sig'] ) を指定してcheck()メソッドを使用して、署名が正しいことを確認します。
$ signature = new Vonage Client Signature ( $ _GET , SIGNATURE_SECRET , ' sha256 ' );
// is it valid? Will be true or false
$ isValid = $ signature -> check ( $ _GET [ ' sig ' ]);署名シークレットとその他の指定されたパラメーターを使用して、署名を計算し、受信した署名値と照合することができます。
Messages API は、さまざまなアウトバウンド メッセージを送信するために使用されます。現在、次のプラットフォームがサポートされています。
これらのプラットフォームにはそれぞれ、送信できるメッセージのカテゴリが異なります（たとえば、WhatsApp ではテキスト、画像、オーディオ、ビデオ、ファイル、またはテンプレートを送信できますが、Viber ではテキストまたは画像のみを送信できます）。 。送信可能なすべてのメッセージ タイプは、名前空間VonageMessagesChannelの下にあります。このように各タイプが分離されている理由は、プラットフォームとメッセージ タイプでは API 呼び出しに異なるパラメーターが必要であるためです。
VonageMessagesClient SMS API クライアントと同様の方法で構成されます。違いは、認証が JSON Web Token (JWT) または Basic 認証のいずれかであることです。クライアントの資格情報の設定方法の詳細については、この ReadMe の「使用法」セクションを参照してください。
以下にいくつかの例を示します。
まず、次のように新しい WhatsAppText オブジェクトを作成する必要があります。
$ whatsAppText = new Vonage Messages Channel WhatsApp WhatsAppText (
FROM_NUMBER ,
TO_NUMBER ,
' this is a WA text from vonage '
); Messages API クライアントには、提供されたメッセージ タイプのいずれかを送信できるメソッドsend()が 1 つあります。したがって、Vonage クライアントがすでに正しく設定されていると仮定すると、このメッセージを送信するには、次のコードが実行されます。
$ client -> messages ()-> send ( $ whatsAppText );エラー範囲が 200 以内の場合、応答は JSON ペイロードになり、400/500 以内の場合は関連するAPIExceptionがスローされます。
一部のChannelオブジェクトでは、作成するためにさらに多くの引数が必要です。コンストラクターの引数と API ドキュメントを比較することで、これらの要件の大まかなマッピングを確認できます。これらのメッセージの一部は、カスタムの再利用可能なオブジェクト ( VonageMessagesMessageObjects名前空間の下にあります) を受け取ります。これらの 1 つは画像です。Viber 画像を送信する方法の例を次に示します。
$ imageObject = Vonage Messages MessageObjects ImageObject (
' https://picsum.photos/200/300 ' ,
' image caption '
);
$ viberImage = new Vonage Messages Channel Viber ViberImage (
FROM_NUMBER ,
TO_NUMBER ,
$ imageObject
);
$ client -> messages ()-> send ( $ viberImage );Vonage の Verify API を使用すると、ユーザーがサインアップ時に自分の電話番号を提供したことを証明したり、サインイン時に第 2 要素認証を実装したりすることが簡単になります。
次のようなコードを使用して検証プロセスを開始できます。
$ request = new Vonage Verify Request ( ' 14845551212 ' , ' My App ' );
$ response = $ client -> verify ()-> start ( $ request );
echo " Started verification with an id of: " . $ response -> getRequestId ();ユーザーが受け取った PIN コードを入力したら、リクエスト ID と PIN を使用してcheck()メソッド (以下を参照) を呼び出し、PIN が正しいことを確認します。
進行中の検証をキャンセルするか、次の確認コードの送信試行をトリガーするには、既存の検証オブジェクトをクライアント ライブラリに渡すか、単純にリクエスト ID を使用します。
$ client -> verify ()-> trigger ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );
$ client -> verify ()-> cancel ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );同様に、検証を確認するには、ユーザーが指定した PIN とリクエスト ID が必要です。
try {
$ client -> verify ()-> check ( ' 00e6c3377e5348cdaf567e1417c707a5 ' , ' 1234 ' );
echo " Verification was successful (status: " . $ verification -> getStatus () . " ) n" ;
} catch ( Exception $ e ) {
echo " Verification failed with status " . $ e -> getCode ()
. " and error text "" . $ e -> getMessage () . ""n" ;
}リクエスト ID を使用して、検証のステータスを確認したり、過去の検証結果にアクセスしたりできます。検証オブジェクトは豊富なインターフェイスを提供します。
$ client -> verify ()-> search ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );
echo " Codes checked for verification: " . $ verification -> getRequestId () . PHP_EOL ;
foreach ( $ verification -> getChecks () as $ check ){
echo $ check -> getDate ()-> format ( ' d-m-y ' ) . ' ' . $ check -> getStatus () . PHP_EOL ;
}Vonage の Verify API は、PSD2 (Payment Services Directive) で要求され、支払いのために顧客から確認を得る必要があるアプリケーションで使用される SCA (Secure Customer Authentication) サポートを備えています。メッセージには受取人および金額が含まれます。
次のように支払いの検証を開始します。
$ request = new Vonage Verify RequestPSD2 ( ' 14845551212 ' , ' My App ' );
$ response = $ client -> verify ()-> requestPSD2 ( $ request );
echo " Started verification with an id of: " . $ response [ ' request_id ' ];ユーザーが受け取った PIN コードを入力したら、リクエスト ID と PIN を使用して/checkエンドポイントを呼び出し、PIN が正しいことを確認します。
Vonage の Verify v2 は、非同期ワークフローにさらに依存しています。 Webhook と、よりカスタマイズ可能な検証ワークフローを開発者に提供します。検証を開始するには、名前空間verify2の下にある API クライアントが必要です。
Verify リクエストを行うには、検証モードを提供するための通信の「ベース」チャネルが必要です。さまざまな「ワークフロー」を追加することで、これらの対話をカスタマイズできます。ワークフローの種類ごとに、最初のワークフローを処理する Verify2 クラスを作成できます。例えば：
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
);
$ smsRequest = new Vonage Verify2 Request SMSRequest ( ' TO_NUMBER ' );
$ client -> verify2 ()-> startVerification ( $ smsRequest ); SMSRequestオブジェクトはデフォルトを解決し、SMS を使用するデフォルトのworkflowオブジェクトを作成します。ただし、フォールバック ロジックで動作する複数のワークフローを追加することはできます。たとえば、ユーザーから PIN コードを取得しようとする検証を作成したい場合、 SMS ですが、SMS 配信に問題が発生した場合に備えて、音声フォールバックを追加できます。
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
);
$ smsRequest = new Vonage Verify2 Request SMSRequest ( ' TO_NUMBER ' , ' my-verification ' );
$ voiceWorkflow = new Vonage Verify2 VerifyObjects VerificationWorkflow ( Vonage Verify2 VerifyObjects VerificationWorkflow:: WORKFLOW_VOICE , ' TO_NUMBER ' );
$ smsRequest -> addWorkflow ( $ voiceWorkflow );
$ client -> verify2 ()-> startVerification ( $ smsRequest );これにより、元の SMS リクエストに音声ワークフローが追加されます。検証リクエストは、指定された順序でプロセスの解決を試みます (リクエストのタイプのデフォルトから開始します)。
基本的なリクエストのタイプは次のとおりです。
SMSRequestWhatsAppRequestWhatsAppInterativeRequestEmailRequestVoiceRequestSilentAuthRequestワークフローを追加する場合、利用可能な有効なワークフローをVerificationWorkflowオブジェクト内の定数として確認できます。開発者のエクスペリエンスを向上させるために、オブジェクトで行われる検証のため、無効なワークフローを作成することはできません。
コードを送信するには、API の性質上、メソッドを try/catch で囲む必要があります。コードが正しい場合、メソッドはtrueブール値を返します。失敗した場合は、キャッチする必要がある関連する例外が API からスローされます。
$ code = ' 1234 ' ;
try {
$ client -> verify2 ()-> check ( $ code );
} catch ( Exception $ e ) {
var_dump ( $ e -> getMessage ())
}検証ワークフロー中にイベントが発生すると、イベントと更新が Webhook として起動されます。 PSR-7 標準に準拠する受信サーバー要求は、より適切な対話のために Webhook 値オブジェクトに組み込むことができます。生の配列からそれらをハイドレートすることもできます。成功すると、イベント/更新のタイプに応じた値オブジェクトが返されます。考えられる Webhook は次のとおりです。
VerifyEventVerifyStatusUpdateVerifySilentAuthUpdate // From a request object
$ verificationEvent = Vonage Verify2 Webhook Factory:: createFromRequest ( $ request );
var_dump ( $ verificationEvent -> getStatus ());
// From an array
$ payload = $ request -> getBody ()-> getContents ()
$ verificationEvent = Vonage Verify2 Webhook Factory:: createFromArray ( $ payload );
var_dump ( $ verificationEvent -> getStatus ());必要に応じて、エンド ユーザーがアクションを実行する前にリクエストをキャンセルできます。
$ requestId = ' c11236f4-00bf-4b89-84ba-88b25df97315 ' ;
$ client -> verify2 ()-> cancel ( $ requestId );すべての$client->voice()メソッドでは、 VonageClientCredentialsKeypair 、またはKeypair認証情報を含むVonageClientCredentialsContainerを使用してクライアントを構築する必要があります。
$ basic = new Vonage Client Credentials Basic ( VONAGE_API_KEY , VONAGE_API_SECRET );
$ keypair = new Vonage Client Credentials Keypair (
file_get_contents ( VONAGE_APPLICATION_PRIVATE_KEY_PATH ),
VONAGE_APPLICATION_ID
);
$ client = new Vonage Client ( new Vonage Client Credentials Container ( $ basic , $ keypair )); OutboundCallオブジェクトを使用して通話を開始できます。
$ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ outboundCall
-> setAnswerWebhook (
new Vonage Voice Webhook ( ' https://example.com/webhooks/answer ' )
)
-> setEventWebhook (
new Vonage Voice Webhook ( ' https://example.com/webhooks/event ' )
)
;
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall );アプリケーションにリンクされている番号から FROM 番号をシステムにランダムに選択させたい場合は、 VonageVoiceOutboundCallのコンストラクターの 2 番目のパラメーターを省略すると、システムが番号をランダムに選択します。 。
SimSwap は、SIM が携帯端末内にどれくらいの期間入っているかを判断するために CAMARA 標準を使用します。これは、認証メカニズムが他の API よりもわずかに複雑であることを意味します。必要なものは次のとおりです。
Vonage Global Network Platformに登録された独自の加入者番号を持つこと。ダッシュボード アプリケーション ID 秘密キー
この API には、 checkSimSwapとcheckSimSwapDateという 2 つのメソッドが使用できます。
両方を使用する例を次に示します。
$ credentials = new Vonage Client Credentials Gnp (
' 0777888888 ' ,
file_get_contents ( ' ./private.key ' ),
' 0dadaeb4-7c79-4d39-b4b0-5a6cc08bf537 '
);
$ client = new Vonage Client ( $ credentials );
$ swapResult = $ client -> simswap ()-> checkSimSwap ( ' 07999999999 ' , 500 );
if ( $ swapResult ) {
echo " Warning: SIM Swapped recently "
} else {
echo " SIM OK "
};
// Finding the swap date
echo $ client -> simswap ()-> checkSimSwapDate ( ' 07999999999 ' );番号検証は CAMARA API 標準を使用し、リクエストが有効かどうかを判断するために使用されます。他の SDK とは異なり、SDK はプロセスの開始とプロセスの終了の間で分割されます。
必要なものは次のとおりです。
Vonage Global Network Platformに登録された独自の加入者番号を持つこと。ダッシュボード アプリケーション ID Vonage ダッシュボードからダウンロードした秘密キー
buildFrontEndUrl()メソッドを使用します。これを呼び出すときは、アプリケーションが固有のcode含むコールバックを受信すると予想されるルートを指定する必要があります。これを機能させるには、許可された地域で許可された電話番号を持っている必要があります。ダミーの例を次に示します。 class VerificationController extends MyFrameworkAbsractController
{
$ credentials = new Vonage Client Credentials Gnp(
' 077380777111 ' ,
file_get_contents ( ' ../private.key ' ),
' 0dadaeb4-7c79-4d39-b4b0-5a6cc08bf537 '
)
$ client = new Vonage Client ( $ credentials );
$ verifyUrl = $ client -> numberVerification ()-> buildFrontEndUrl (
' 07777777777 ' ,
' https://myapp.com/auth/numberVerify '
);
return $ this -> render ( ' verify.html.twig ' , [
' verifyLink ' => $ verifyUrl
]);
}code抽出すると、SDK がこれを行うために必要な Auth メソッドの処理を処理します。このメソッドは API からブール値を返します。以下に例を示します。 $ code = $ request -> get ( ' code ' );
$ result = $ client -> numberVerification ()-> verifyNumber (
' 09947777777 ' ,
$ code
);
if ( $ result ) {
Auth:: login ( $ request -> user ())
}
return redirect ( ' login ' );
}この API はアプリ内メッセージングに使用され、幅広い機能と概念が含まれています。詳細については、API ドキュメントを参照してください。
$ credentials = new Vonage Client Credentials Keypair ( file_get_contents ( ' ./path-to-my-key.key ' , ' my-app-id ' ));
$ client = new Vonage Client ( $ credentials );
$ filter = new Vonage Conversation Filter ListConversationFilter ();
$ filter -> setStartDate ( ' 2018-01-01 10:00:00 ' );
$ filter -> setEndDate ( ' 2019-01-01 10:00:00 ' )
$ conversations = $ client -> conversations ()-> listConversations ( $ filter )
var_dump ( $ conversations ); $ credentials = new Vonage Client Credentials Keypair ( file_get_contents ( ' ./path-to-my-key.key ' , ' my-app-id ' ));
$ client = new Vonage Client ( $ credentials );
$ conversation = new CreateConversationRequest ( ' customer_chat ' , ' Customer Chat ' , ' https://example.com/image.png ' );
$ conversation -> setTtl ( 60 );
$ conversationNumber = new ConversationNumber ( ' 447700900000 ' );
$ conversationCallback = new ConversationCallback ( ' https://example.com/eventcallback ' );
$ conversationCallback -> setEventMask ( ' member:invited, member:joined ' );
$ conversationCallback -> setApplicationId ( ' afa393df-2c46-475b-b2d6-92da4ea05481 ' );
$ conversationCallback -> setNccoUrl ( ' https://example.com/ncco ' );
$ conversation -> setNumber ( $ conversationNumber );
$ conversation -> setConversationCallback ( $ conversationCallback );
$ response = $ this -> conversationsClient -> createConversation ( $ conversation );
var_dump ( $ response ); $ credentials = new Vonage Client Credentials Keypair ( file_get_contents ( ' ./path-to-my-key.key ' , ' my-app-id ' ));
$ client = new Vonage Client ( $ credentials );
$ filter = new ListUserConversationsFilter ();
$ filter -> setState ( ' INVITED ' );
$ filter -> setIncludeCustomData ( true );
$ filter -> setOrderBy ( ' created ' );
$ filter -> setStartDate ( ' 2018-01-01 10:00:00 ' );
$ filter -> setEndDate ( ' 2018-01-01 12:00:00 ' );
$ filter -> setPageSize ( 5 );
$ filter -> setOrder ( ' asc ' );
$ response = $ this -> conversationsClient -> listUserConversationsByUserId ( ' CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a ' );
foreach ( $ response as $ member ) {
$ members [] = $ member ;
}
var_dump ( $ members ); $ channel = Channel:: createChannel (Channel:: CHANNEL_TYPE_APP );
$ channel -> addUserFromTypes ([
' sms ' ,
' phone '
]);
$ channel -> addUserToField ( ' USR-82e028d9-9999-4f1e-8188-604b2d3471ec ' );
$ createMemberRequest = new CreateMemberRequest (
' invited ' ,
$ channel ,
' USR-82e028d9-5201-4f1e-8188-604b2d3471ec ' ,
' my_user_name ' ,
);
$ createMemberRequest -> setAudioPossible ( true );
$ createMemberRequest -> setAudioEnabled ( true );
$ createMemberRequest -> setAudioEarmuffed ( false );
$ createMemberRequest -> setAudioMuted ( false );
$ createMemberRequest -> setKnockingId ( ' 4f1e-8188 ' );
$ createMemberRequest -> setMemberIdInviting ( ' MEM-63f61863-4a51-4f6b-86e1-46edebio0391 ' );
$ createMemberRequest -> setFrom ( ' value ' );
$ response = $ this -> conversationsClient -> createMember (
$ createMemberRequest ,
' CON-63f61863-4a51-4f6b-86e1-46edebio0391 '
);
var_dump ( $ response );NCCO アクションの完全なパラメータ リストは、Voice API ドキュメントに記載されています。
これらの各例では、次の構造を使用して呼び出しにアクションを追加します。
$ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ ncco = new NCCO ();
// ADD ACTIONS TO THE NCCO OBJECT HERE
$ outboundCall -> setNCCO ( $ ncco );
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall ); $ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ ncco = new NCCO ();
$ ncco -> addAction ( Vonage Voice NCCO Action Record:: factory ([
' eventUrl ' => ' https://example.com/webhooks/event '
]);
$ outboundCall -> setNCCO ( $ ncco );
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall );Webhook URL は次のようなペイロードを受け取ります。
{
"start_time": "2020-10-29T14:30:24Z",
"recording_url": "https://api.nexmo.com/v1/files/<recording-id>",
"size": 27918,
"recording_uuid": "<recording-id>",
"end_time": "2020-10-29T14:30:31Z",
"conversation_uuid": "<conversation-id>",
"timestamp": "2020-10-29T14:30:31.619Z"
}
次に、次のように録音を取得して保存できます。
$recordingId = '<recording-id>';
$recordingUrl = 'https://api.nexmo.com/v1/files/' . $recordingId;
$data = $client->get($recordingUrl);
file_put_contents($recordingId.'.mp3', $data->getBody());
$ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ ncco = new NCCO ();
$ ncco -> addAction ( new Vonage Voice NCCO Action Talk ( ' This is a text to speech call from Vonage ' ));
$ outboundCall -> setNCCO ( $ ncco );
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall ); $ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ ncco = new NCCO ();
$ ncco -> addAction ( new Vonage Voice NCCO Action Stream ( ' https://example.com/sounds/my-audio.mp3 ' ));
$ outboundCall -> setNCCO ( $ ncco );
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall );音声だけでなくキーパッド入力もサポートします。注意。入力アクションは、 bargeInがtrueに設定されたアクションの後に続く必要があります。
$ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ ncco = new NCCO ();
$ ncco -> addAction ( Vonage Voice NCCO Action Talk:: factory ( ' Please record your name. ' ,[
' bargeIn ' => true ,
]));
$ ncco -> addAction ( Vonage Voice NCCO Action Input:: factory ([
' eventUrl ' => ' https://example.com/webhooks/event ' ,
' type ' => [
' speech ' ,
],
' speech ' => [
' endOnSilence ' => true ,
],
]));
$ outboundCall -> setNCCO ( $ ncco );
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall );Webhook URL は、音声入力に対する相対信頼度評価を含むユーザーからの入力を含むペイロードを受け取ります。
$ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ ncco = new NCCO ();
$ ncco -> addAction ( new Vonage Voice NCCO Action Talk ( ' We are just testing the notify function, you do not need to do anything. ' ));
$ ncco -> addAction ( new Vonage Voice NCCO Action Notify ([
' foo ' => ' bar ' ,
], new Vonage Voice Webhook ( ' https://example.com/webhooks/notify ' )));
$ outboundCall -> setNCCO ( $ ncco );
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall );Webhook URL は、リクエストで指定されたペイロードを受け取ります。
VonageCallCallオブジェクトを使用するか、文字列として通話の UUID を使用して通話をフェッチできます。
$ call = $ client -> voice ()-> get ( ' 3fd4d839-493e-4485-b2a5-ace527aacff3 ' );
echo $ call -> getDirection ();フィルタを使用して通話を検索することもできます。
$ filter = new Vonage Voice Filter VoiceFilter ();
$ filter -> setStatus ( ' completed ' );
foreach ( $ client -> search ( $ filter ) as $ call ){
echo $ call -> getDirection ();
}アプリケーションは構成コンテナーです。配列構造を使用して作成できます。
$ application = new Vonage Application Application ();
$ application -> fromArray ([
' name ' => ' test application ' ,
' keys ' => [
' public_key ' => ' -----BEGIN PUBLIC KEY-----nMIIBIjANBgkqhkiG9w0BAQEFAAOCAnKOxjsU4pf/sMFi9N0jqcSLcjxu33Gnd/vynKnlw9SENi+UZR44GdjGdmfm1ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3n0kYWekeIZawIwe/g9faFgkev+1xsOnOUNhPx2LhuLmgwWSRS4L5W851Xe3fnUQIDAQABn-----END PUBLIC KEY-----n '
],
' capabilities ' => [
' voice ' => [
' webhooks ' => [
' answer_url ' => [
' address ' => ' https://example.com/webhooks/answer ' ,
' http_method ' => ' GET ' ,
],
' event_url ' => [
' address ' => ' https://example.com/webhooks/event ' ,
' http_method ' => ' POST ' ,
],
]
],
' messages ' => [
' webhooks ' => [
' inbound_url ' => [
' address ' => ' https://example.com/webhooks/inbound ' ,
' http_method ' => ' POST '
],
' status_url ' => [
' address ' => ' https://example.com/webhooks/status ' ,
' http_method ' => ' POST '
]
]
],
' rtc ' => [
' webhooks ' => [
' event_url ' => [
' address ' => ' https://example.com/webhooks/event ' ,
' http_method ' => ' POST ' ,
],
]
],
' vbc ' => []
]
]);
$ client -> applications ()-> create ( $ application );クライアントにアプリケーション オブジェクトを渡すこともできます。
$ a = new Vonage Application Application ();
$ a -> setName ( ' PHP Client Example ' );
$ a -> getVoiceConfig ()-> setWebhook ( ' answer_url ' , ' https://example.com/webhooks/answer ' , ' GET ' );
$ a -> getVoiceConfig ()-> setWebhook ( ' event_url ' , ' https://example.com/webhooks/event ' , ' POST ' );
$ a -> getMessagesConfig ()-> setWebhook ( ' status_url ' , ' https://example.com/webhooks/status ' , ' POST ' );
$ a -> getMessagesConfig ()-> setWebhook ( ' inbound_url ' , ' https://example.com/webhooks/inbound ' , ' POST ' );
$ a -> getRtcConfig ()-> setWebhook ( ' event_url ' , ' https://example.com/webhooks/event ' , ' POST ' );
$ a -> disableVbc ();
$ client -> applications ()-> create ( $ a );すべてのアプリケーションを反復処理できます。
foreach ( $ client -> applications ()-> getAll () as $ application ){
echo $ application -> getName () . PHP_EOL ;
}または、文字列 UUID またはアプリケーション オブジェクトを使用してアプリケーションをフェッチすることもできます。
$ application = $ client -> applications ()-> get ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' );アプリケーション オブジェクトを取得したら、それを変更して保存できます。
$ application = $ client -> applications ()-> get ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' );
$ application -> setName ( ' Updated Application ' );
$ client -> applications ()-> update ( $ application );アカウントが所有する番号をリストし、オプションでフィルタリングを含めることができます。
search_pattern :
0 - 番号はpatternで始まります1 - 番号にはpatternが含まれます2 - 数字はpatternで終わります $ filter = new Vonage Numbers Filter OwnedNumbers ();
$ filter
-> setPattern ( 234 )
-> setSearchPattern ( Vonage Numbers Filter OwnedNumbers:: SEARCH_PATTERN_CONTAINS )
;
$ response = $ client -> numbers ()-> searchOwned ( null , $ filter ); has_application :
true - 番号はアプリケーションに付加されますfalse - 番号はアプリケーションに付加されていません $ filter = new Vonage Numbers Filter OwnedNumbers ();
$ filter -> setHasApplication ( true );
$ response = $ client -> numbers ()-> searchOwned ( $ filter ); application_id :
$ filter = new Vonage Numbers Filter OwnedNumbers ();
$ filter -> setApplicationId ( " 66c04cea-68b2-45e4-9061-3fd847d627b8 " );
$ response = $ client -> numbers ()-> searchOwned ( $ filter );特定の国で購入できる番号を検索できます。
$ numbers = $ client -> numbers ()-> searchAvailable ( ' US ' );デフォルトでは、最初の 10 件の結果のみが返されます。 VonageNumbersFilterAvailableNumbersフィルターを追加して、検索を絞り込むことができます。
番号を購入するには、番号検索から返された値を渡すことができます。
$ numbers = $ client -> numbers ()-> searchAvailable ( ' US ' );
$ number = $ numbers -> current ();
$ client -> numbers ()-> purchase ( $ number -> getMsisdn (), $ number -> getCountry ());または、番号と国を手動で指定することもできます。
$ client -> numbers ()-> purchase ( ' 14155550100 ' , ' US ' );数値を更新するには、 numbers()->updateを使用し、変更する構成オプションを渡します。設定をクリアするには、空の値を渡します。
$ number = $ client -> numbers ()-> get ( VONAGE_NUMBER );
$ number
-> setAppId ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' )
-> setVoiceDestination ( ' 447700900002 ' , ' tel ' )
-> setWebhook (
Vonage Number Number:: WEBHOOK_VOICE_STATUS ,
' https://example.com/webhooks/status '
)
-> setWebhook (
Vonage Number Number:: WEBHOOK_MESSAGE ,
' https://example.com/webhooks/inbound-sms '
)
;
$ client -> numbers ()-> update ( $ number );
echo " Number updated " . PHP_EOL ;番号をキャンセルするには、 msisdn指定します。
$ client -> numbers ()-> cancel ( ' 447700900002 ' );API シークレットをローテーションできるようにする API が提供されています。新しいシークレット (最大 2 つのシークレット) を作成し、すべてのアプリケーションが更新されたら既存のシークレットを削除できます。
シークレットのリストを取得するには:
$ secretsCollection = $ client -> account ()-> listSecrets ( API_KEY );
/** @var VonageAccountSecret $secret */
foreach ( $ secretsCollection -> getSecrets () as $ secret ) {
echo " ID: " . $ secret -> getId () . " (created " . $ secret -> getCreatedAt () . " ) n" ;
}新しいシークレットを作成できます (作成された日付は、どれがどれであるかを知るのに役立ちます)。
$ client -> account ()-> createSecret ( API_KEY , ' awes0meNewSekret!!; ' );そして、古いシークレットを削除します (これらの資格情報をまだ使用しているアプリケーションは動作を停止します)。
try {
$ response = $ client -> account ()-> deleteSecret ( API_KEY , ' d0f40c7e-91f2-4fe0-8bc6-8942587b622c ' );
} catch ( Vonage Client Exception Request $ e ) {
echo $ e -> getMessage ();
}電話をかけたい国のプレフィックスがわかっている場合は、 prefix-pricingエンドポイントを使用して、その番号に通話するためのコストを調べることができます。各プレフィックスは複数の国を返すことができます (例: 1 US 、 CA 、およびUM返します)。
$ results = $ client -> account ()-> getPrefixPricing ( ' 1 ' );
foreach ( $ results as $ price ) {
echo $ price -> getCountryCode (). PHP_EOL ;
echo $ price -> getCountryName (). PHP_EOL ;
foreach ( $ price -> getNetworks () as $ network ) {
echo $ network -> getName () . ' :: ' . $ network -> getCode (). ' :: ' . $ network -> getPrefixPrice (). PHP_EOL ;
}
echo " ---------------- " . PHP_EOL ;
}アカウントに残っているクレジットを確認します。
$ response = $ client -> account ()-> getBalance ();
echo round ( $ response -> getBalance (), 2 ) . " EUR n" ;アカウントの現在の設定を確認します。
$ response = $ client -> account ()-> getConfig ();
print_r ( $ response -> toArray ());受信 SMS メッセージと配信確認のデフォルトのコールバック URL を更新します。
$ response = $ client -> account ()-> updateConfig ([
" sms_callback_url " => " http://example.com/webhooks/incoming-sms " ,
" dr_callback_url " => " http://example.com/webhooks/delivery-receipt "
]);
print_r ( $ response -> toArray ());Vonage のネットワーク API を使用するには、Vonage ネットワーク レジストリ内で有効にする必要があります。
MSNDIN を登録すると、SimSwap を使用できるようになります。
SimSwap は Global Network Platform 認証メカニズムを使用するため、認証フローは他の API クライアントとは少し異なります。内部では、SDK は CAMARA 標準アクセス トークンを構成するための複数の呼び出しを処理します。
SIM が最近交換されたかどうかを確認する例を次に示します。
$ credentials = new Vonage Client Credentials Gnp (
' tel:+447700900000 ' ,
fopen ( ' ./my-private-key ' ),
' my-application-id '
);
$ client = new Vonage Client ( $ credentials );
if ( $ client -> simswap ()-> checkSimSwap ( ' 07700009999 ' , 240 )) {
echo ' Warning: SIM Swap Check Failed '
} else {
echo ' SIM Swap Check Pass '
}スワップ日を取得する方法は次のとおりです。
$ credentials = new Vonage Client Credentials Gnp (
' tel:+447700900000 ' ,
fopen ( ' ./my-private-key ' ),
' my-application-id '
);
$ client = new Vonage Client ( $ credentials );
$ date = $ client -> simswap ()-> checkSimSwapDate ( ' 07700009999 ' )
echo $ date;Number Insights API を使用すると、ユーザーは番号が有効であることを確認し、その使用方法について詳しく知ることができます。
次のように、 basic()またはstandard()メソッドのいずれかを使用できます ( advanced()メソッドも使用できますが、高度な情報を取得するには async オプションを使用することをお勧めします)。
try {
$ insights = $ client -> insights ()-> basic ( PHONE_NUMBER );
echo $ insights -> getNationalFormatNumber ();
} catch ( Exception $ e ) {
// for the Vonage-specific exceptions, try the `getEntity()` method for more diagnostic information
}上の例では、データは$insights変数に返されます。
高度な分析情報を取得するには、非同期機能を使用し、Webhook の送信先の URL を指定します。
try {
$ client -> insights ()-> advancedAsync ( PHONE_NUMBER , ' http://example.com/webhooks/number-insights ' );
} catch ( Exception $ e ) {
// for the Vonage-specific exceptions, try the `getEntity()` method for more diagnostic information
}リクエストしたデータを含む受信 Webhook で何が期待されるかについては、ドキュメントを確認してください。
この API は、プライマリ アカウントに関連するサブアカウントを作成および構成し、アカウント間でクレジット、残高、購入した番号を転送するために使用されます。サブアカウント API はデフォルトでは無効になっています。サブアカウントを使用する場合は、サポートに問い合わせて、アカウントで API を有効にしてください。
$ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' 34kokdf ' ;
$ subaccounts = $ client -> subaccount ()-> getSubaccounts ( $ apiKey );
var_dump ( $ subaccounts ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ payload = [
' name ' => ' sub name ' ,
' secret ' => ' s5r3fds ' ,
' use_primary_account_balance ' => false
];
$ account = new Account ();
$ account -> fromArray ( $ payload );
$ response = $ client -> subaccount ()-> createSubaccount ( $ apiKey , $ account );
var_dump ( $ response ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ subaccountKey = ' bbe6222f ' ;
$ response = $ client -> subaccount ()-> getSubaccount ( $ apiKey , $ subaccountKey );
var_dump ( $ response ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ subaccountKey = ' bbe6222f ' ;
$ payload = [
' suspended ' => true ,
' use_primary_account_balance ' => false ,
' name ' => ' Subaccount department B '
];
$ account = new Account ();
$ account -> fromArray ( $ payload );
$ response = $ client -> subaccount ()-> updateSubaccount ( $ apiKey , $ subaccountKey , $ account )
var_dump ( $ response ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ filter = new Vonage Subaccount Filter Subaccount([ ' subaccount ' => ' 35wsf5 ' ])
$ transfers = $ client -> subaccount ()-> getCreditTransfers ( $ apiKey );
var_dump ( $ transfers ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ transferRequest = ( new TransferCreditRequest ( $ apiKey ))
-> setFrom ( ' acc6111f ' )
-> setTo ( ' s5r3fds ' )
-> setAmount ( ' 123.45 ' )
-> setReference ( ' this is a credit transfer ' );
$ response = $ this -> subaccountClient -> makeCreditTransfer ( $ transferRequest ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ filter = new Vonage Subaccount Filter Subaccount ([ ' end_date ' => ' 2022-10-02 ' ]);
$ transfers = $ client -> subaccount ()-> getBalanceTransfers ( $ apiKey , $ filter ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ transferRequest = ( new TransferBalanceRequest ( $ apiKey ))
-> setFrom ( ' acc6111f ' )
-> setTo ( ' s5r3fds ' )
-> setAmount ( ' 123.45 ' )
-> setReference ( ' this is a credit transfer ' );
$ response = $ client -> subaccount ()-> makeBalanceTransfer ( $ transferRequest );
var_dump ( $ response ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ numberTransferRequest = ( new NumberTransferRequest ( $ apiKey ))
-> setFrom ( ' acc6111f ' )
-> setTo ( ' s5r3fds ' )
-> setNumber ( ' 4477705478484 ' )
-> setCountry ( ' GB ' );
$ response = $ client -> subaccount ()-> makeNumberTransfer ( $ numberTransferRequest );
var_dump ( $ response );| API | APIリリースステータス | サポートされていますか? |
|---|---|---|
| アカウントAPI | 一般提供 | |
| アラートAPI | 一般提供 | |
| アプリケーションAPI | 一般提供 | |
| 監査API | ベータ | |
| 会話API | ベータ | |
| ディスパッチAPI | ベータ | |
| 外部アカウント API | ベータ | |
| メディアAPI | ベータ | |
| ミーティングAPI | 一般提供 | |
| メッセージAPI | 一般提供 | |
| Number Insight API | 一般提供 | |
| 番号管理API | 一般提供 | |
| 価格設定API | 一般提供 | |
| プロアクティブ接続 API | ベータ | |
| リダクトAPI | 一般提供 | |
| レポートAPI | ベータ | |
| SMS API | 一般提供 | |
| サブアカウントAPI | 一般提供 | |
| APIの検証 | 一般提供 | |
| API の検証 (バージョン 2) | 一般提供 | |
| 音声API | 一般提供 |
時間の経過とともに、Vonage API は進化して新しい機能が追加され、既存の機能の動作方法が変更され、古いメソッドと機能が廃止されて削除されます。非推奨の変更がいつ行われるかを開発者が把握できるように、SDK はE_USER_DEPRECATION警告をトリガーします。これらの警告はコードの実行を停止しませんが、運用環境では迷惑になる可能性があります。
これを解決するために、デフォルトでは、これらの通知は抑制されています。開発時は、 show_deprecationsという追加の構成オプションをVonageClientコンストラクターに渡すことで、これらの警告を有効にできます。このオプションを有効にすると、すべての非推奨通知が表示されます。
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
[
' show_deprecations ' => true
]
);運用環境で非推奨の通知が過剰に多いことに気付いた場合は、構成オプションが存在しないことを確認するか、少なくともfalseに設定されていることを確認してください。
unable to get local issuer certificate一部のユーザーは、次のエラーが原因でリクエストを行う際に問題が発生します。
Fatal error: Uncaught exception 'GuzzleHttpExceptionRequestException' with message 'cURL error 60: SSL certificate problem: unable to get local issuer certificate (see http://curl.haxx.se/libcurl/c/libcurl-errors.html)'
これは、一部の PHP インストールに信頼できる CA 証明書のリストが同梱されていないことが原因です。これはシステム構成の問題であり、cURL または Vonage に固有のものではありません。
重要: 次の段落では、CA 証明書バンドルへのリンクを提供します。 Vonage はこのバンドルの安全性を保証しません。マシンに CA バンドルをインストールする前に、ご自身で確認する必要があります。
この問題を解決するには、信頼できる CA 証明書のリスト (curl バンドルなど) をダウンロードし、それをマシンにコピーします。これが完了したら、 php.ini編集して、 curl.cainfoパラメータを設定します。
# Linux/MacOS
curl.cainfo = "/etc/pki/tls/cacert.pem"
# Windows
curl.cainfo = "C:phpextrassslcacert.pem"
HTTPlug アダプターまたは PSR-18 互換の HTTP クライアントの使用が許可されているため、必要に応じて、たとえばローカル プロキシを考慮したり、セットアップに固有の何かを処理したりするために、別の構成でクライアントを作成できます。
以下は、サーバーへのルートがない場合に長時間の遅延を避けるために、デフォルトのタイムアウトを 5 秒に短縮する例です。
$ adapter_client = new Http Adapter Guzzle6 Client ( new GuzzleHttp Client ([ ' timeout ' => 5 ]));
$ vonage_client = new Vonage Client ( new Vonage Client Credentials Basic ( $ api_key , $ api_secret ), [], $ adapter_client );問題が発生すると、 Exception返されます。 Vonage 例外クラスVonageClientExceptionRequestおよびVonageClientExceptionServer getCode()およびgetMessage()に加えて使用できる追加のgetEntity()メソッドをサポートしており、問題の原因を詳しく知ることができます。返されるエンティティは通常、操作に関連するオブジェクト、または API 呼び出しからの応答オブジェクトです。
推奨されるguzzlehttp/guzzleパッケージと共存できない競合するパッケージのインストールがある場合は、 php-http/client-implementation要件を満たすパッケージとともにvonage/client-coreパッケージをインストールできます。
オプションのクライアント実装については、Packagist ページを参照してください。
当社のクライアント ライブラリは、PSR-3 互換のログ メカニズムを介したデバッグのためのリクエストとレスポンスのログ記録をサポートしています。 debugオプションがクライアントに渡され、PSR-3 互換ロガーがクライアントのサービス ファクトリに設定されている場合、デバッグ目的でそのロガーが使用されます。
$ client = new Vonage Client ( new Vonage Client Credentials Basic ( ' abcd1234 ' , ' s3cr3tk3y ' ), [ ' debug ' => true ]);
$ logger = new Monolog Logger ( ' test ' );
$ logger -> pushHandler ( new Monolog Handler StreamHandler ( __DIR__ . ' /log.txt ' , Monolog Logger:: DEBUG ));
$ client -> getFactory ()-> set ( PSR Log LoggerInterface::class, $ logger );デバッグログを有効にすると、機密情報がログに記録される可能性があります。運用環境では有効にしないでください。
このライブラリには、PHPUnit で実行するように設計された完全なテスト スイートが含まれています。
実行するには、composer を使用します。
composer test
注意: このテスト スイートはサイズが大きいため、実行するにはかなりの量のメモリが必要になる場合があります。 MacOS または Linux で「開いているファイルが多すぎます」エラーが発生した場合は、許可されるファイル ポインターの量を増やすハックがあります。コマンドラインに次のように入力して、開くことができるファイルの量を増やします (10240 は、MacOS が現在開くポインターの最大量です)。
ulimit -n 10240
このライブラリは積極的に開発されており、皆様からのご意見をお待ちしております。ご自由に問題を作成するか、質問、コメント、提案、フィードバックを含むプル リクエストを開いてください。
