README

此库需要至少PHP版本8.1

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

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

安装

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

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

composer require vonage/client

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

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

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

Composer入门页面来自Composer项目的文档。
Composer入门指南来自ScotchBox的好人们。

用法

如果您使用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更改为其他URL。您可以通过在创建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, '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;

由于每个短信消息都可以分成多个消息，因此响应包含每个生成的消息的对象。您可以使用PHP中的标准count()函数检查生成了多少条消息。如果您想获取第一条消息，可以使用响应上的current()方法。

$data = $response->current();
$data->getRemainingBalance();
foreach($response as $index => $data){
    $data->getRemainingBalance();
}

send示例还包括完整的示例。

检测编码类型

您可以使用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密钥。支持的算法包括：

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，请使用传入数据、您的签名密钥和签名方法创建签名对象。然后使用check()方法与实际收到的签名（通常是_GET['sig']）进行验证，以确保它是正确的。

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

// is it valid? Will be true or false
$isValid = $signature->check($_GET['sig']);

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

通过消息API发送消息

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

SMS
MMS
WhatsApp
Messenger
Viber

每个平台都支持发送不同类别的消息（例如，通过WhatsApp您可以发送文本、图片、音频、视频、文件或模板，但对于Viber，您只能发送文本或图片）。您可以在\Vonage\Messages\Channel命名空间下找到所有可发送的消息类型。这样做的原因是平台和消息类型需要不同的API调用参数。

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

以下是一些示例：

发送WhatsApp文本

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

$whatsAppText = new Vonage\Messages\Channel\WhatsApp\WhatsAppText(
    FROM_NUMBER,
    TO_NUMBER,
    'this is a WA text from vonage'
);

消息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',
    'image caption'
);

$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 "Started verification with an id of: " . $response->getRequestId();

用户输入收到的PIN码后，调用check()方法（见下文）并传入请求ID和PIN来确认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码后，调用/check端点并传入请求ID和PIN来确认PIN是否正确。

验证示例（v2）

开始验证

Vonage的Verify v2更依赖于通过webhooks的异步工作流程，并为开发者提供更多可定制的验证工作流程。要开始验证，您需要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对象以使用短信。但是，您可以添加多个具有回退逻辑的工作流程。例如，如果您想创建一个尝试通过短信从用户那里获取PIN码的验证，但在短信发送有问题时希望添加语音回退：您可以添加它。

$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);

这将在原始短信请求中添加语音工作流程。验证请求将按照给出的顺序尝试解决过程（从请求类型的默认值开始）。

基本请求类型如下

SMSRequest
WhatsAppRequest
WhatsAppInterativeRequest
EmailRequest
VoiceRequest
SilentAuthRequest

要添加工作流程，您可以在VerificationWorkflow对象中查看可用的有效工作流程作为常量。为了更好的开发者体验，由于对象上的验证，您不能创建无效的工作流程。

检查提交的代码

由于API的特性，提交代码时需要将方法包裹在try/catch中。如果代码正确，方法将返回一个true布尔值。如果失败，它将抛出API相关的异常，需要捕获。

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

Webhooks

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

VerifyEvent
VerifyStatusUpdate
VerifySilentAuthUpdate

// 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()方法都需要使用包含Keypair凭据的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);

如果您希望系统从与应用程序关联的号码中随机选择一个主叫号码，您可以在 \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"
};

// Finding the swap date
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 动作的全部参数列表可以在 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 将接收到包含用户输入的数据包，其中包含语音输入的相对置信度评分。

向 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 将接收到请求中指定的数据包。

获取通话

您可以使用 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' => 'test application',
 '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);

您还可以向客户端传递应用程序对象

$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);

列出您的号码

您可以列出您账户拥有的号码，并可选择包含过滤。

搜索模式:

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');

默认情况下，这将仅返回前10个结果。您可以添加额外的 \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());

更新接收短信消息和投递收据的默认回调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;

获取号码信息

号码洞察API 允许用户检查号码是否有效，并了解如何使用它。

基本和标准使用

您可以使用 basic() 或 standard() 方法（提供了一个 advanced() 方法，但建议使用异步选项来获取高级信息），如下所示

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

故障排除

检查已弃用功能

随着时间的推移，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要求的包。

有关客户端实现选项，请参阅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

贡献

这个库正在积极开发中，我们很高兴听取您的意见！请随时创建一个问题或发起一个pull request，提供您的问题、评论、建议和反馈。

vonage / client-core

维护者

详细信息

README

安装

用法

示例

通过SMS API发送消息

检测编码类型

接收消息

消息签名

验证入站消息签名

通过消息API发送消息

发送WhatsApp文本

发送Viber图片

验证示例（v1）

开始验证

控制验证

检查验证

搜索验证

支付验证

验证示例（v2）

开始验证

检查提交的代码

Webhooks

取消正在进行的请求

发起通话

使用 SimSwap API

用法

使用号码验证 API

用法

使用 Conversations API

带有筛选器的获取对话列表

创建对话

列出对话中的成员

在对话中创建成员

使用 NCCO 动作构建通话

创建事件

记录通话

发送短信到语音通话

在通话中流式传输音频文件

从通话中收集用户输入

向 webhook URL 发送通知

获取通话

创建应用程序

获取应用程序

更新应用程序

列出您的号码

搜索可用号码

购买号码

更新号码

取消号码

管理密钥

定价

前缀定价

检查您的余额

查看和更改账户配置

使用SimSwap检查手机中SIM的状态和日期

获取号码信息

基本和标准使用

高级使用

子账户示例

获取子账户列表

创建子账户

获取子账户

更新子账户

获取信用转账列表

在账户间转账信用

获取余额转账列表

在账户间转账余额

在账户间转账电话号码

支持的API

故障排除

检查已弃用功能

无法获取本地颁发者证书

传递自定义HTTP客户端

访问响应数据

由于Guzzle适配器，Composer安装失败

启用请求/响应记录

测试套件

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