懂AI
vonage-php-sdk-core

vonage-php-sdk-core

PHP开发者的Vonage API集成核心库

Vonage PHP客户库为开发者提供简便易用的接口，支持Vonage API的集成。通过安装和配置，该库支持发送SMS、WhatsApp等消息，并支持消息验证和签名。此库需要PHP 8.1或更高版本，通过Composer进行安装和管理。无论新手还是经验丰富的开发者，都能快速实现通信功能。

VonagePHPAPISMSComposerGithub开源项目
访问官网GitHub论文文档

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，请确保在项目的引导文件中包含自动加载器：

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 控制面板下载的私钥。

使用方法

  1. 您的后端需要提供一个自定义 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
    ]);
}
  1. 您的后端然后需要能够配置以消费传入的 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

APIAPI发布状态是否支持？
账户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

贡献

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

编辑推荐精选

Trae

Trae

字节跳动发布的AI编程神器IDE

Trae是一种自适应的集成开发环境（IDE），通过自动化和多元协作改变开发流程。利用Trae，团队能够更快速、精确地编写和部署代码，从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能，是提升开发效率的理想工具。

热门AI工具生产力协作转型TraeAI IDE
问小白

问小白

全能AI智能助手，随时解答生活与工作的多样问题

问小白，由元石科技研发的AI智能助手，快速准确地解答各种生活和工作问题，包括但不限于搜索、规划和社交互动，帮助用户在日常生活中提高效率，轻松管理个人事务。

聊天机器人AI助手热门AI工具AI对话
Transly

Transly

实时语音翻译/同声传译工具

Transly是一个多场景的AI大语言模型驱动的同声传译、专业翻译助手，它拥有超精准的音频识别翻译能力，几乎零延迟的使用体验和支持多国语言可以让你带它走遍全球，无论你是留学生、商务人士、韩剧美剧爱好者，还是出国游玩、多国会议、跨国追星等等，都可以满足你所有需要同传的场景需求，线上线下通用，扫除语言障碍，让全世界的语言交流不再有国界。

讯飞智文

讯飞智文

一键生成PPT和Word，让学习生活更轻松

讯飞智文是一个利用 AI 技术的项目，能够帮助用户生成 PPT 以及各类文档。无论是商业领域的市场分析报告、年度目标制定，还是学生群体的职业生涯规划、实习避坑指南，亦或是活动策划、旅游攻略等内容，它都能提供支持，帮助用户精准表达，轻松呈现各种信息。

热门AI工具AI办公办公工具讯飞智文AI在线生成PPTAI撰写助手多语种文档生成AI自动配图
讯飞星火

讯飞星火

深度推理能力全新升级，全面对标OpenAI o1

科大讯飞的星火大模型，支持语言理解、知识问答和文本创作等多功能，适用于多种文件和业务场景，提升办公和日常生活的效率。讯飞星火是一个提供丰富智能服务的平台，涵盖科技资讯、图像创作、写作辅助、编程解答、科研文献解读等功能，能为不同需求的用户提供便捷高效的帮助，助力用户轻松获取信息、解决问题，满足多样化使用场景。

模型训练热门AI工具内容创作智能问答AI开发讯飞星火大模型多语种支持智慧生活
Spark-TTS

Spark-TTS

一种基于大语言模型的高效单流解耦语音令牌文本到语音合成模型

Spark-TTS 是一个基于 PyTorch 的开源文本到语音合成项目，由多个知名机构联合参与。该项目提供了高效的 LLM（大语言模型）驱动的语音合成方案，支持语音克隆和语音创建功能，可通过命令行界面（CLI）和 Web UI 两种方式使用。用户可以根据需求调整语音的性别、音高、速度等参数，生成高质量的语音。该项目适用于多种场景，如有声读物制作、智能语音助手开发等。

咔片PPT

咔片PPT

AI助力，做PPT更简单！

咔片是一款轻量化在线演示设计工具，借助 AI 技术，实现从内容生成到智能设计的一站式 PPT 制作服务。支持多种文档格式导入生成 PPT，提供海量模板、智能美化、素材替换等功能，适用于销售、教师、学生等各类人群，能高效制作出高品质 PPT，满足不同场景演示需求。

讯飞绘文

讯飞绘文

选题、配图、成文，一站式创作，让内容运营更高效

讯飞绘文，一个AI集成平台，支持写作、选题、配图、排版和发布。高效生成适用于各类媒体的定制内容，加速品牌传播，提升内容营销效果。

AI助手热门AI工具AI创作AI辅助写作讯飞绘文内容运营个性化文章多平台分发
材料星

材料星

专业的AI公文写作平台，公文写作神器

AI 材料星，专业的 AI 公文写作辅助平台，为体制内工作人员提供高效的公文写作解决方案。拥有海量公文文库、9 大核心 AI 功能，支持 30 + 文稿类型生成，助力快速完成领导讲话、工作总结、述职报告等材料，提升办公效率，是体制打工人的得力写作神器。

openai-agents-python

openai-agents-python

OpenAI Agents SDK，助力开发者便捷使用 OpenAI 相关功能。

openai-agents-python 是 OpenAI 推出的一款强大 Python SDK，它为开发者提供了与 OpenAI 模型交互的高效工具，支持工具调用、结果处理、追踪等功能，涵盖多种应用场景，如研究助手、财务研究等，能显著提升开发效率，让开发者更轻松地利用 OpenAI 的技术优势。

下拉加载更多