PHP客户端库

The Vonage logo

此库要求最低的PHP版本为8.1

这是用于使用Vonage API的PHP客户端库。要使用此库，您需要一个Vonage账户。在此注册免费账户。

安装
使用
示例
测试套件
贡献

安装

要使用客户端库，您需要创建一个Vonage账户。

要将PHP客户端库安装到您的项目中，我们建议使用Composer。

composer require vonage/client

请注意，这实际上指向了包含HTTP客户端和此核心库的包装库。如果您愿意，可以直接从Composer安装此库，并有选择项目使用的HTTP客户端的能力。

要在您自己的项目中使用此库，您不需要克隆此仓库。请使用Composer从Packagist安装它。

如果您是Composer的新手，以下资源可能对您有用：

来自Composer项目文档的Composer入门页面。
来自ScotchBox的A Beginner's Guide to 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更改为其他内容。您可以在创建Vonage\Client实例时提供包含base_api_url的数组作为第二个参数来实现此目的。

$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选项来更改这些请求。

示例

通过SMS API发送消息

要使用Vonage的SMS API发送短信消息，请调用$client->sms()->send()方法。

消息对象用于创建短信消息。每种消息类型都可以使用所需参数构建，并且流畅的接口提供了访问可选参数的方法。

$text = new \Vonage\SMS\Message\SMS(VONAGE_TO, VONAGE_FROM, '使用PHP客户端库发送测试消息');
$text->setClientRef('test-message');

将消息对象传递给send方法：

$response = $client->sms()->send($text);

发送后，消息对象可用于访问响应数据。

$data = $response->current();
echo "成功发送消息到 " . $data->getTo() . "。余额现在是 " . $data->getRemainingBalance() . PHP_EOL;

由于每条短信消息都可以拆分为多条消息，响应包含为每条生成的消息提供的对象。您可以使用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', '这是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('无效消息');
}

签名消息

您可能还希望阅读消息签名的文档。

SMS API支持通过使用“签名密钥”而不是您的API密钥生成和添加签名来签名消息。支持的算法有：

md5hash1
md5
sha1
sha256
sha512

您的应用程序和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对象。然后使用check()方法与接收到的实际签名（通常是_GET['sig']）进行比对，确保其正确。

$signature = new \Vonage\Client\Signature($_GET, SIGNATURE_SECRET, 'sha256');

// 是否有效？将返回true或false
$isValid = $signature->check($_GET['sig']);

使用您的签名密钥和其他提供的参数，可以计算签名并与传入的签名值进行比对。

通过Messages API发送消息

Messages API用于发送各种出站消息。当前支持以下平台：

SMS
MMS
WhatsApp
Messenger
Viber

每个平台都有不同类别的可发送消息（例如，使用WhatsApp可以发送文本、图片、音频、视频、文件或模板，但使用Viber只能发送文本或图片）。您可以在命名空间\Vonage\Messages\Channel下找到所有可发送的消息类型。每种类型分别独立，是因为平台和消息类型在API调用中需要不同的参数。

Vonage\Messages\Client的配置方式类似于SMS API客户端。不同之处在于认证可以是JSON Web Token (JWT) 或基本认证。您可以在本ReadMe的“使用”部分找到有关如何设置客户端凭证的更多信息。

以下是一些示例：

发送WhatsApp文本

首先，我们需要创建一个新的WhatsAppText对象，如下所示：

$whatsAppText = new Vonage\Messages\Channel\WhatsApp\WhatsAppText(
    FROM_NUMBER,
    TO_NUMBER,
    '这是来自Vonage的WA文本'
);

Messages API客户端只有一个方法，即send()，您可以使用此方法发送提供的任何消息类型。因此，要发送此消息，可以使用以下代码，假设您已经正确设置了Vonage客户端：

$client->messages()->send($whatsAppText);

如果错误范围在200内，您的响应将是JSON有效负载；如果在400/500范围内，将抛出相关的APIException。

发送Viber图片

某些Channel对象需要更多的参数来创建。您可以通过比较构造函数参数与API文档来查看这些要求的粗略映射。有些消息需要自定义可重复使用的对象（在命名空间\Vonage\Messages\MessageObjects下）。其中一个是图像 - 下面是如何发送Viber图像的示例：

$imageObject = Vonage\Messages\MessageObjects\ImageObject(
    'https://picsum.photos/200/300',
    '图像说明'
);

$viberImage = new Vonage\Messages\Channel\Viber\ViberImage(
    FROM_NUMBER,
    TO_NUMBER,
    $imageObject
);

$client->messages()->send($viberImage);

验证示例（v1）

启动验证

Vonage的Verify API使您可以轻松证明用户在注册时提供了自己的电话号码，或在登录时实现二次身份验证。

您可以使用以下代码启动验证过程：

$request = new \Vonage\Verify\Request('14845551212', 'My App');
$response = $client->verify()->start($request);
echo "已启动验证，ID为：" . $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 支持 SCA（安全客户认证），这是 PSD2（支付服务指令）所要求的，适用于需要客户支付确认的应用程序。它在消息中包含收款人和金额。

像这样开始付款验证：

$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 正确。

验证示例（v2）

启动验证

Vonage 的 Verify v2 更依赖于通过 Webhook 的异步工作流程，并为开发人员提供更多可定制的验证工作流程。要启动验证，您需要 API 客户端，它位于 verify2 命名空间下。

发起验证请求需要一个“基本”通信渠道来传递验证模式。您可以通过添加不同的“工作流程”来自定义这些交互。对于每种类型的工作流程，有一个 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 对象将为您解析默认值，并将创建默认的 workflow 对象以使用 SMS。您还可以添加多个具有后备逻辑的工作流程。例如，如果您希望创建一个通过 SMS 获取用户 PIN 代码的验证，但如果 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 请求中。验证请求将尝试按给定顺序解析流程（从请求类型的默认值开始）。

基本请求类型如下：

SMSRequest
WhatsAppRequest
WhatsAppInterativeRequest
EmailRequest
VoiceRequest
SilentAuthRequest

要添加工作流程，您可以在 VerificationWorkflow 对象内作为常量看到可用的有效工作流程。为了提供更好的开发人员体验，由于对象上的验证，无法创建无效的工作流程。

检查提交的代码

要提交代码，您需要将方法包围在 try/catch 中，这与 API 的性质有关。如果代码正确，该方法将返回一个 true 布尔值。如果失败，它将抛出需要捕获的相关异常。

$code = '1234';
try {
    $client->verify2()->check($code);
} catch (\Exception $e) {
    var_dump($e->getMessage())
}

Webhook

在验证工作流程期间发生事件时，事件和更新将作为 Webhook 触发。符合 PSR-7 标准的传入服务器请求可以被水合到 Webhook 值对象中以进行更好的交互。您还可以从原始数组中对它们进行水合。如果成功，您将收到一个值对象，用于该类型的事件/更新。可能的 Webhook 有：

VerifyEvent
VerifyStatusUpdate
VerifySilentAuthUpdate

// 从请求对象
$verificationEvent = \Vonage\Verify2\Webhook\Factory::createFromRequest($request);
var_dump($verificationEvent->getStatus());
// 从数组中
$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() 方法都需要使用 Vonage\Client\Credentials\Keypair 构建的客户端，或者包含 Keypair 凭证的 Vonage\Client\Credentials\Container：

$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 号码，您可以省略 \Vonage\Voice\OutboundCall 构造函数的第二个参数，系统将为您随机选择一个号码。

使用 SimSwap API

SimSwap 使用 CAMARA 标准来确定 SIM 卡在手机设备中的时间。因此，身份验证机制比其他 API 略复杂。您将需要：

拥有已在 Vonage 全球网络平台上注册的 订户号码。您的控制面板应用程序 ID。您的私钥。

使用方法

该 API 有两种可用方法：checkSimSwap 和 checkSimSwapDate。

以下是使用这两种方法的示例：


$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";
}

// 找到交换日期
echo $client->simswap()->checkSimSwapDate('07999999999');

使用号码验证 API

号码验证使用 CAMARA API 标准，用于确定请求是否有效。与其他 SDK 不同，SDK 被分为过程的开始和结束。

您将需要：

拥有已在 Vonage 全球网络平台上注册的 订户号码。您的控制面板应用程序 ID。从 Vonage 控制面板下载的私钥。

使用方法

您的后端需要提供一个自定义 URL 以触发验证请求。为此，使用客户端的 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
    ]);
}

您的后端然后需要能够配置以消费传入的 Webhook。提取 code 后，SDK 将处理所需的身份验证方法。该方法返回一个布尔值。以下是一个示例：

$code = $request->get('code');

$result = $client->numberVerification()->verifyNumber(
    '09947777777',
    $code
);

if ($result) {
    Auth::login($request->user());
}

return redirect('login');
}

使用 Conversations API

此 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操作构建通话

创建一个事件

NCCO操作的完整参数列表可以在语音API文档中找到。

每个示例都使用以下结构将操作添加到通话中：

$outboundCall = new \Vonage\Voice\OutboundCall(
    new \Vonage\Voice\Endpoint\Phone('14843331234'),
    new \Vonage\Voice\Endpoint\Phone('14843335555')
);
$ncco = new NCCO();

// 在这里向NCCO对象添加操作

$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网址将收到如下所示的有效负载：

{
  "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('这是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('请输入您的名字。',[
  '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将会收到包含用户输入的有效负载，包括语音输入的相对置信度评分。

向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('我们正在测试通知功能，您不需要做任何事情。'));
$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将会收到请求中指定的有效负载。

获取一个通话

您可以使用Vonage\Call\Call对象或通话的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' => '测试应用程序',
 'keys' => [
     'public_key' => '-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----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);

你还可以传递一个 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($filter);

has_application:

true - 号码已附加到应用程序
false - 号码未附加到应用程序

$filter = new \Vonage\Numbers\Filter\OwnedNumbers();
$filter->setHasApplication(true);
$response = $client->numbers()->searchOwned($filter);

application_id:

提供一个应用程序 ID 来获取与请求应用程序相关的所有号码

$filter = new \Vonage\Numbers\Filter\OwnedNumbers();
$filter->setApplicationId("66c04cea-68b2-45e4-9061-3fd847d627b8");
$response = $client->numbers()->searchOwned($filter);

搜索可用号码

你可以搜索在特定国家/地区中可供购买的号码：

$numbers = $client->numbers()->searchAvailable('US');

默认情况下，这将只返回前十个结果。你可以添加一个额外的 \Vonage\Numbers\Filter\AvailableNumbers 过滤器来缩小搜寻范围。

购买号码

要购买号码，你可以传递一个从号码搜索中返回的值：

$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 密钥。你可以创建一个新的密钥（最多两个密钥）并在所有应用程序更新后删除现有的密钥。

要获取密钥列表：

$secretsCollection = $client->account()->listSecrets(API_KEY);
/** @var \Vonage\Account\Secret $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());

使用 SimSwap 检查 SIM 卡状态和日期

为了使用 Vonage 的网络 API，你需要在 Vonage 网络注册中启用。

一旦你注册了 MSNDIN，你将能够使用 SimSwap。

SimSwap 使用全球网络平台认证机制，因此授权流程看起来与其他 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() 方法，但建议使用异步选项获取高级信息），如下所示：


try {
  $insights = $client->insights()->basic(PHONE_NUMBER);

  echo $insights->getNationalFormatNumber();
} catch (Exception $e) {
  // 对于 Vonage 专用异常，可以尝试 `getEntity()` 方法以获取更多诊断信息
}

数据在上面的示例中返回到 $insights 变量中。

高级用法

要获得高级信息，使用异步功能并提供一个 URL 来捕获 webhook：

try {
  $client->insights()->advancedAsync(PHONE_NUMBER, 'http://example.com/webhooks/number-insights');
} catch (Exception $e) {
  // 对于 Vonage 专用异常，可以尝试 `getEntity()` 方法以获取更多诊断信息
}

查看文档以了解预期的包含你请求数据的入站 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' => '子账户部门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('这是一个信用转账');

$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('这是一个信用转账');

$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	一般可用性	✅
消息API	一般可用性	✅
号码洞察API	一般可用性	✅
号码管理API	一般可用性	✅
定价API	一般可用性	✅
主动连接API	测试版	❌
修订API	一般可用性	✅
报告API	测试版	❌
SMS API	一般可用性	✅
子账户API	一般可用性	✅
验证API	一般可用性	✅
验证API (版本2)	一般可用性	✅
语音API	一般可用性	✅

疑难解答

检查已弃用的功能

随着时间的推移，Vonage的API会不断发展，添加新功能，改变现有功能的工作方式，并弃用和删除旧的方法和功能。为了帮助开发者了解何时进行弃用更改，SDK会触发一个E_USER_DEPRECATION警告。这些警告不会停止代码的执行，但可能会在生产环境中引起烦扰。

为了解决这个问题，默认情况下这些通知是被禁用的。在开发中，可以通过向\Vonage\Client构造函数传递一个名为show_deprecations的附加配置选项来启用这些警告。启用此选项将显示所有弃用通知。

$client = new Vonage\Client(
    new Vonage\Client\Credentials\Basic(API_KEY, API_SECRET),
    [
        'show_deprecations' => true
    ]
);

如果您在生产环境中发现大量弃用通知，确保配置选项不存在，或至少设置为false。

`无法获取本地颁发者证书`

一些用户由于以下错误而无法发出请求：

Fatal error: Uncaught exception 'GuzzleHttp\Exception\RequestException' 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:\php\extras\ssl\cacert.pem"

传递自定义HTTP客户端

我们允许使用任何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异常类Vonage\Client\Exception\Request和Vonage\Client\Exception\Server支持一个附加的getEntity()方法，您可以使用该方法来寻找更多关于问题的详细信息，除了使用getCode()和getMessage()。返回的实体通常是与操作相关的对象或API调用的响应对象。

由于Guzzle适配器导致Composer安装失败

如果您有一个无法与我们的推荐包guzzlehttp/guzzle共存的冲突包安装，您可以安装vonage/client-core包以及任何满足php-http/client-implementation要求的包。

请参阅client-implementation的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

贡献

该库正在积极开发中，我们很乐意听取您的意见！请随时创建一个问题或打开一个拉取请求，提出您的问题、意见、建议和反馈。

vonage-php-sdk-core

PHP客户端库

安装

使用

示例

通过SMS API发送消息

检测编码类型

接收消息

签名消息

验证传入消息签名

通过Messages API发送消息

发送WhatsApp文本

发送Viber图片

验证示例（v1）

启动验证

创建一个对话

列出对话中的成员

在对话中创建一个成员

使用NCCO操作构建通话

创建一个事件

录音

发送文本到语音通话

在通话中播放音频文件

从通话中收集用户输入

向webhook url发送通知

获取一个通话

创建一个应用程序

获取应用程序

更新应用程序

列出你的号码

搜索可用号码

购买号码

更新号码

取消号码

管理密钥

定价

前缀定价

查询余额

查看并更改账户配置

使用 SimSwap 检查 SIM 卡状态和日期

获取号码信息

基本和标准用法

高级用法

子账户示例

获取子账户列表

创建子账户

获取子账户

更新子账户

获取信用转账列表

在账户之间转账信用

获取余额转账列表

在账户之间转账余额

在账户之间转移电话号码

支持的API

疑难解答

检查已弃用的功能

无法获取本地颁发者证书

传递自定义HTTP客户端

访问响应数据

由于Guzzle适配器导致Composer安装失败

启用请求/响应日志记录

测试套件

贡献

`无法获取本地颁发者证书`