vonage php sdk core
4.10.7
Для этой библиотеки требуется минимальная версия PHP 8.1.
Это клиентская библиотека PHP для использования API Vonage. Чтобы использовать это, вам понадобится учетная запись 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 )); В целях тестирования вы можете изменить URL-адрес, к которому vonage/client отправляет запросы, с api.vonage.com на что-то другое. Вы можете сделать это, предоставив массив, содержащий base_api_url в качестве второго параметра при создании экземпляра VonageClient .
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
[
' base_api_url ' => ' https://example.com '
]
); Для API, которые обычно обращаются к rest.nexmo.com , предоставление base_rest_url в качестве опции конструктора изменит эти запросы.
Чтобы использовать SMS API Vonage для отправки SMS-сообщения, вызовите метод $client->sms()->send() .
Объект сообщения используется для создания SMS-сообщений. Каждый тип сообщения может быть создан с необходимыми параметрами, а гибкий интерфейс обеспечивает доступ к дополнительным параметрам.
$ text = new Vonage SMS Message SMS ( VONAGE_TO , VONAGE_FROM , ' Test message using PHP client library ' );
$ text -> setClientRef ( ' test-message ' ); Объект сообщения передается методу send :
$ response = $ client -> sms ()-> send ( $ text );После отправки объект сообщения можно использовать для доступа к данным ответа.
$ data = $ response -> current ();
echo " Sent message to " . $ data -> getTo () . " . Balance is now " . $ data -> getRemainingBalance () . PHP_EOL ; Поскольку каждое SMS-сообщение можно разделить на несколько сообщений, ответ содержит объект для каждого сгенерированного сообщения. Вы можете проверить, сколько сообщений было сгенерировано, используя стандартную функцию count() в PHP. Если вы хотите получить первое сообщение, вы можете использовать метод current() для ответа.
$ data = $ response -> current ();
$ data -> getRemainingBalance ();
foreach ( $ response as $ index => $ data ){
$ data -> getRemainingBalance ();
}Пример отправки также содержит полные рабочие примеры.
Вы можете использовать статический метод isGsm7() в коде SMS-клиента, чтобы определить, следует ли отправлять сообщение с использованием кодировки 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 ' );
}Входящие сообщения отправляются в ваше приложение в виде веб-перехватчика. Клиентская библиотека предоставляет способ создания объекта входящего сообщения из веб-перехватчика:
try {
$ inbound = Vonage SMS Webhook Factory:: createFromGlobals ();
error_log ( $ inbound -> getText ());
} catch ( InvalidArgumentException $ e ) {
error_log ( ' invalid message ' );
}Вы также можете прочитать документацию о подписании сообщений.
SMS API поддерживает возможность подписывать сообщения путем создания и добавления подписи с использованием «секрета подписи», а не вашего секрета API. Поддерживаются следующие алгоритмы:
md5hash1md5sha1sha256sha512И ваше приложение, и Vonage должны договориться о том, какой алгоритм будет использоваться. На панели управления посетите страницу настроек своей учетной записи и в разделе «Настройки API» вы можете выбрать используемый алгоритм. Здесь вы также найдете свой «Секрет подписи» (он отличается от секрета API).
Создайте клиента, используя эти учетные данные и алгоритм, который будет использоваться, например:
$ client = new Vonage Client ( new Vonage Client Credentials SignatureSecret ( API_KEY , SIGNATURE_SECRET , ' sha256 ' ));Используя этот клиент, ваши сообщения SMS API будут отправляться как подписанные сообщения.
Вы также можете прочитать документацию о подписании сообщений.
Если у вас включена подпись входящих сообщений, веб-перехватчик SMS будет включать поля sig , nonce и timestamp . Чтобы убедиться, что подпись принадлежит Vonage, вы создаете объект Signature, используя входящие данные, секрет вашей подписи и метод подписи. Затем используйте метод 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 сообщений используется для отправки различных исходящих сообщений. В настоящее время поддерживаются следующие платформы:
На каждой из этих платформ есть разные категории сообщений, которые вы можете отправить (например, с помощью WhatsApp вы можете отправлять текст, изображение, аудио, видео, файл или шаблон, а с помощью Viber вы можете отправлять только текст или изображение). . Вы можете найти все типы отправляемых сообщений в пространстве имен VonageMessagesChannel . Причина, по которой каждый тип разделен таким образом, заключается в том, что платформа и тип сообщения требуют разных параметров в вызове API.
VonageMessagesClient настраивается аналогично клиенту SMS API. Разница в том, что аутентификацией может быть либо веб-токен JSON (JWT), либо базовая аутентификация. Дополнительную информацию о том, как настроить учетные данные вашего клиента, можно найти в разделе «Использование» данного файла ReadMe.
Вот несколько примеров:
Во-первых, нам нужно создать новый объект 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 ); Вашим ответом будет полезная нагрузка JSON, если диапазон ошибок находится в пределах 200, или будет выдано соответствующее исключение APIException , если он находится в пределах 400/500.
Для создания некоторых объектов Channel требуется больше аргументов. Вы можете увидеть грубое отображение этих требований, сравнив аргументы конструктора с документацией API. Некоторые из этих сообщений используют пользовательские повторно используемые объекты (которые находятся в пространстве имен VonageMessagesMessageObjects ). Одним из них является изображение. Вот пример того, как отправить изображение 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 );API Verify от Vonage позволяет легко доказать, что пользователь предоставил свой номер телефона при регистрации, или внедрить двухфакторную аутентификацию во время входа в систему.
Вы можете запустить процесс проверки, используя такой код:
$ request = new Vonage Verify Request ( ' 14845551212 ' , ' My App ' );
$ response = $ client -> verify ()-> start ( $ request );
echo " Started verification with an id of: " . $ response -> getRequestId (); Как только пользователь вводит полученный пин-код, вызовите метод check() (см. ниже) с идентификатором запроса и PIN-кодом, чтобы подтвердить правильность PIN-кода.
Чтобы отменить выполняющуюся проверку или инициировать следующую попытку отправки кода подтверждения, вы можете передать существующий объект проверки в клиентскую библиотеку или просто использовать идентификатор запроса:
$ client -> verify ()-> trigger ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );
$ client -> verify ()-> cancel ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );Таким же образом для проверки проверки требуется PIN-код, предоставленный пользователем, и идентификатор запроса:
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" ;
}Вы можете проверить статус проверки или получить доступ к результатам прошлых проверок, используя идентификатор запроса. Объект проверки затем предоставит богатый интерфейс:
$ 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 ;
}API Verify от Vonage имеет поддержку 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 ' ]; Как только пользователь вводит полученный пин-код, вызовите конечную точку /check с идентификатором запроса и пин-кодом, чтобы подтвердить правильность пин-кода.
Verify v2 от Vonage больше полагается на асинхронные рабочие процессы. веб-перехватчики и более настраиваемые рабочие процессы проверки для разработчика. Чтобы начать проверку, вам понадобится клиент 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. Однако вы можете добавить несколько рабочих процессов, которые работают с резервной логикой. Например, если вы хотите создать проверку, которая пытается получить от пользователя PIN-код через. SMS, но в случае возникновения проблем с доставкой SMS вы хотите добавить запасной вариант Voice: вы можете добавить его.
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
);
$ smsRequest = new Vonage Verify2 Request SMSRequest ( ' TO_NUMBER ' , ' my-verification ' );
$ voiceWorkflow = new Vonage Verify2 VerifyObjects VerificationWorkflow ( Vonage Verify2 VerifyObjects VerificationWorkflow:: WORKFLOW_VOICE , ' TO_NUMBER ' );
$ smsRequest -> addWorkflow ( $ voiceWorkflow );
$ client -> verify2 ()-> startVerification ( $ smsRequest );Это добавляет голосовой рабочий процесс к исходному SMS-запросу. Запрос на проверку попытается разрешить процесс в том порядке, в котором он задан (начиная со значения по умолчанию для типа запроса).
Базовые типы запросов следующие:
SMSRequestWhatsAppRequestWhatsAppInterativeRequestEmailRequestVoiceRequestSilentAuthRequest Для добавления рабочих процессов вы можете просмотреть доступные допустимые рабочие процессы в виде констант внутри объекта VerificationWorkflow . Для удобства разработчика вы не можете создать недопустимый рабочий процесс из-за проверки, которая происходит на объекте.
Чтобы отправить код, вам нужно будет заключить метод в try/catch из-за особенностей API. Если код верен, метод вернет true логическое значение. В случае неудачи будет выдано соответствующее исключение из API, которое необходимо будет перехватить.
$ code = ' 1234 ' ;
try {
$ client -> verify2 ()-> check ( $ code );
} catch ( Exception $ e ) {
var_dump ( $ e -> getMessage ())
}Поскольку события происходят во время рабочего процесса проверки, события и обновления будут запускаться как веб-перехватчики. Входящие запросы к серверу, соответствующие стандартам PSR-7, могут быть преобразованы в объект значения веб-перехватчика для более удобного взаимодействия. Вы также можете гидратировать их из необработанного массива. В случае успеха вы получите обратно объект значения для типа события/обновления. Возможные вебхуки:
VerifyEventVerifyStatusUpdateVerifySilentAuthUpdate // From a request object
$ verificationEvent = Vonage Verify2 Webhook Factory:: createFromRequest ( $ request );
var_dump ( $ verificationEvent -> getStatus ());
// From an array
$ payload = $ request -> getBody ()-> getContents ()
$ verificationEvent = Vonage Verify2 Webhook Factory:: createFromArray ( $ payload );
var_dump ( $ verificationEvent -> getStatus ());При необходимости вы можете отменить запрос до того, как конечный пользователь предпримет какие-либо действия.
$ requestId = ' c11236f4-00bf-4b89-84ba-88b25df97315 ' ;
$ client -> verify2 ()-> cancel ( $ requestId ); Все методы $client->voice() требуют, чтобы клиент был создан с помощью VonageClientCredentialsKeypair или VonageClientCredentialsContainer , который включает учетные данные Keypair :
$ basic = new Vonage Client Credentials Basic ( VONAGE_API_KEY , VONAGE_API_SECRET );
$ keypair = new Vonage Client Credentials Keypair (
file_get_contents ( VONAGE_APPLICATION_PRIVATE_KEY_PATH ),
VONAGE_APPLICATION_ID
);
$ client = new Vonage Client ( new Vonage Client Credentials Container ( $ basic , $ keypair )); Вы можете начать вызов, используя объект OutboundCall :
$ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ outboundCall
-> setAnswerWebhook (
new Vonage Voice Webhook ( ' https://example.com/webhooks/answer ' )
)
-> setEventWebhook (
new Vonage Voice Webhook ( ' https://example.com/webhooks/event ' )
)
;
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall ); Если вы хотите, чтобы система случайным образом выбирала номер FROM из чисел, связанных с приложением, вы можете опустить второй параметр конструктора VonageVoiceOutboundCall , и система выберет для вас номер случайным образом. .
SimSwap использует стандарты CAMARA, чтобы определить, как долго SIM-карта находилась внутри сотового устройства. Это означает, что механизм аутентификации немного сложнее, чем у других API. Вам понадобится:
Иметь собственный номер подписчика , зарегистрированный на глобальной сетевой платформе Vonage. Идентификатор вашего приложения Dashboard. Ваш закрытый ключ.
Для этого 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 и используется для определения правильности запроса. В отличие от других SDK, SDK разделен между началом и окончанием процесса.
Вам понадобится:
Иметь собственный номер подписчика , зарегистрированный на глобальной сетевой платформе Vonage. Идентификатор вашего приложения Dashboard. Ваш закрытый ключ, загруженный с панели мониторинга Vonage.
buildFrontEndUrl() на клиенте. При вызове вам необходимо указать маршрут, по которому ваше приложение должно получить обратный вызов, содержащий уникальный code . Чтобы это работало, вам потребуется иметь авторизованный номер телефона на авторизованной территории. Вот фиктивный пример: class VerificationController extends MyFrameworkAbsractController
{
$ credentials = new Vonage Client Credentials Gnp(
' 077380777111 ' ,
file_get_contents ( ' ../private.key ' ),
' 0dadaeb4-7c79-4d39-b4b0-5a6cc08bf537 '
)
$ client = new Vonage Client ( $ credentials );
$ verifyUrl = $ client -> numberVerification ()-> buildFrontEndUrl (
' 07777777777 ' ,
' https://myapp.com/auth/numberVerify '
);
return $ this -> render ( ' verify.html.twig ' , [
' verifyLink ' => $ verifyUrl
]);
}code . Метод возвращает логическое значение из API. Вот пример: $ code = $ request -> get ( ' code ' );
$ result = $ client -> numberVerification ()-> verifyNumber (
' 09947777777 ' ,
$ code
);
if ( $ result ) {
Auth:: login ( $ request -> user ())
}
return redirect ( ' login ' );
}Этот API используется для обмена сообщениями внутри приложения и содержит широкий спектр функций и концепций. Для получения дополнительной информации ознакомьтесь с документацией API.
$ credentials = new Vonage Client Credentials Keypair ( file_get_contents ( ' ./path-to-my-key.key ' , ' my-app-id ' ));
$ client = new Vonage Client ( $ credentials );
$ filter = new Vonage Conversation Filter ListConversationFilter ();
$ filter -> setStartDate ( ' 2018-01-01 10:00:00 ' );
$ filter -> setEndDate ( ' 2019-01-01 10:00:00 ' )
$ conversations = $ client -> conversations ()-> listConversations ( $ filter )
var_dump ( $ conversations ); $ credentials = new Vonage Client Credentials Keypair ( file_get_contents ( ' ./path-to-my-key.key ' , ' my-app-id ' ));
$ client = new Vonage Client ( $ credentials );
$ conversation = new CreateConversationRequest ( ' customer_chat ' , ' Customer Chat ' , ' https://example.com/image.png ' );
$ conversation -> setTtl ( 60 );
$ conversationNumber = new ConversationNumber ( ' 447700900000 ' );
$ conversationCallback = new ConversationCallback ( ' https://example.com/eventcallback ' );
$ conversationCallback -> setEventMask ( ' member:invited, member:joined ' );
$ conversationCallback -> setApplicationId ( ' afa393df-2c46-475b-b2d6-92da4ea05481 ' );
$ conversationCallback -> setNccoUrl ( ' https://example.com/ncco ' );
$ conversation -> setNumber ( $ conversationNumber );
$ conversation -> setConversationCallback ( $ conversationCallback );
$ response = $ this -> conversationsClient -> createConversation ( $ conversation );
var_dump ( $ response ); $ credentials = new Vonage Client Credentials Keypair ( file_get_contents ( ' ./path-to-my-key.key ' , ' my-app-id ' ));
$ client = new Vonage Client ( $ credentials );
$ filter = new ListUserConversationsFilter ();
$ filter -> setState ( ' INVITED ' );
$ filter -> setIncludeCustomData ( true );
$ filter -> setOrderBy ( ' created ' );
$ filter -> setStartDate ( ' 2018-01-01 10:00:00 ' );
$ filter -> setEndDate ( ' 2018-01-01 12:00:00 ' );
$ filter -> setPageSize ( 5 );
$ filter -> setOrder ( ' asc ' );
$ response = $ this -> conversationsClient -> listUserConversationsByUserId ( ' CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a ' );
foreach ( $ response as $ member ) {
$ members [] = $ member ;
}
var_dump ( $ members ); $ channel = Channel:: createChannel (Channel:: CHANNEL_TYPE_APP );
$ channel -> addUserFromTypes ([
' sms ' ,
' phone '
]);
$ channel -> addUserToField ( ' USR-82e028d9-9999-4f1e-8188-604b2d3471ec ' );
$ createMemberRequest = new CreateMemberRequest (
' invited ' ,
$ channel ,
' USR-82e028d9-5201-4f1e-8188-604b2d3471ec ' ,
' my_user_name ' ,
);
$ createMemberRequest -> setAudioPossible ( true );
$ createMemberRequest -> setAudioEnabled ( true );
$ createMemberRequest -> setAudioEarmuffed ( false );
$ createMemberRequest -> setAudioMuted ( false );
$ createMemberRequest -> setKnockingId ( ' 4f1e-8188 ' );
$ createMemberRequest -> setMemberIdInviting ( ' MEM-63f61863-4a51-4f6b-86e1-46edebio0391 ' );
$ createMemberRequest -> setFrom ( ' value ' );
$ response = $ this -> conversationsClient -> createMember (
$ createMemberRequest ,
' CON-63f61863-4a51-4f6b-86e1-46edebio0391 '
);
var_dump ( $ response );Полные списки параметров для действий NCCO можно найти в документации Voice API.
В каждом из этих примеров для добавления действий к вызову используется следующая структура:
$ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ ncco = new NCCO ();
// ADD ACTIONS TO THE NCCO OBJECT HERE
$ outboundCall -> setNCCO ( $ ncco );
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall ); $ outboundCall = new Vonage Voice OutboundCall (
new Vonage Voice Endpoint Phone ( ' 14843331234 ' ),
new Vonage Voice Endpoint Phone ( ' 14843335555 ' )
);
$ ncco = new NCCO ();
$ ncco -> addAction ( Vonage Voice NCCO Action Record:: factory ([
' eventUrl ' => ' https://example.com/webhooks/event '
]);
$ outboundCall -> setNCCO ( $ ncco );
$ response = $ client -> voice ()-> createOutboundCall ( $ outboundCall );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 );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 );URL-адрес веб-перехватчика получит полезную нагрузку, указанную в запросе.
Вы можете получить вызов, используя объект VonageCallCall или UUID вызова в виде строки:
$ call = $ client -> voice ()-> get ( ' 3fd4d839-493e-4485-b2a5-ace527aacff3 ' );
echo $ call -> getDirection ();Вы также можете искать звонки с помощью фильтра.
$ filter = new Vonage Voice Filter VoiceFilter ();
$ filter -> setStatus ( ' completed ' );
foreach ( $ client -> search ( $ filter ) as $ call ){
echo $ call -> getDirection ();
}Приложение представляет собой конфигурационные контейнеры. Вы можете создать его, используя структуру массива:
$ application = new Vonage Application Application ();
$ application -> fromArray ([
' name ' => ' test application ' ,
' keys ' => [
' public_key ' => ' -----BEGIN PUBLIC KEY-----nMIIBIjANBgkqhkiG9w0BAQEFAAOCAnKOxjsU4pf/sMFi9N0jqcSLcjxu33Gnd/vynKnlw9SENi+UZR44GdjGdmfm1ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3n0kYWekeIZawIwe/g9faFgkev+1xsOnOUNhPx2LhuLmgwWSRS4L5W851Xe3fnUQIDAQABn-----END PUBLIC KEY-----n '
],
' capabilities ' => [
' voice ' => [
' webhooks ' => [
' answer_url ' => [
' address ' => ' https://example.com/webhooks/answer ' ,
' http_method ' => ' GET ' ,
],
' event_url ' => [
' address ' => ' https://example.com/webhooks/event ' ,
' http_method ' => ' POST ' ,
],
]
],
' messages ' => [
' webhooks ' => [
' inbound_url ' => [
' address ' => ' https://example.com/webhooks/inbound ' ,
' http_method ' => ' POST '
],
' status_url ' => [
' address ' => ' https://example.com/webhooks/status ' ,
' http_method ' => ' POST '
]
]
],
' rtc ' => [
' webhooks ' => [
' event_url ' => [
' address ' => ' https://example.com/webhooks/event ' ,
' http_method ' => ' POST ' ,
],
]
],
' vbc ' => []
]
]);
$ client -> applications ()-> create ( $ application );Вы также можете передать клиенту объект приложения:
$ a = new Vonage Application Application ();
$ a -> setName ( ' PHP Client Example ' );
$ a -> getVoiceConfig ()-> setWebhook ( ' answer_url ' , ' https://example.com/webhooks/answer ' , ' GET ' );
$ a -> getVoiceConfig ()-> setWebhook ( ' event_url ' , ' https://example.com/webhooks/event ' , ' POST ' );
$ a -> getMessagesConfig ()-> setWebhook ( ' status_url ' , ' https://example.com/webhooks/status ' , ' POST ' );
$ a -> getMessagesConfig ()-> setWebhook ( ' inbound_url ' , ' https://example.com/webhooks/inbound ' , ' POST ' );
$ a -> getRtcConfig ()-> setWebhook ( ' event_url ' , ' https://example.com/webhooks/event ' , ' POST ' );
$ a -> disableVbc ();
$ client -> applications ()-> create ( $ a );Вы можете перебирать все ваши приложения:
foreach ( $ client -> applications ()-> getAll () as $ application ){
echo $ application -> getName () . PHP_EOL ;
}Или вы можете получить приложение, используя строковый UUID или объект приложения.
$ application = $ client -> applications ()-> get ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' );Если у вас есть объект приложения, вы можете изменить и сохранить его.
$ application = $ client -> applications ()-> get ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' );
$ application -> setName ( ' Updated Application ' );
$ client -> applications ()-> update ( $ application );Вы можете перечислить номера, принадлежащие вашей учетной записи, и при необходимости включить фильтрацию:
search_pattern :
0 - номер начинается с pattern1 - в номер входит pattern2 - номер заканчивается pattern $ filter = new Vonage Numbers Filter OwnedNumbers ();
$ filter
-> setPattern ( 234 )
-> setSearchPattern ( Vonage Numbers Filter OwnedNumbers:: SEARCH_PATTERN_CONTAINS )
;
$ response = $ client -> numbers ()-> searchOwned ( null , $ filter ); has_application :
true — номер привязан к приложениюfalse — номер не привязан к заявке $ filter = new Vonage Numbers Filter OwnedNumbers ();
$ filter -> setHasApplication ( true );
$ response = $ client -> numbers ()-> searchOwned ( $ filter ); application_id :
$ filter = new Vonage Numbers Filter OwnedNumbers ();
$ filter -> setApplicationId ( " 66c04cea-68b2-45e4-9061-3fd847d627b8 " );
$ response = $ client -> numbers ()-> searchOwned ( $ filter );Вы можете искать номера, доступные для покупки в конкретной стране:
$ numbers = $ client -> numbers ()-> searchAvailable ( ' US ' ); По умолчанию это вернет только первые 10 результатов. Вы можете добавить дополнительный фильтр VonageNumbersFilterAvailableNumbers чтобы сузить область поиска.
Чтобы приобрести номер, вы можете передать значение, полученное в результате поиска номера:
$ numbers = $ client -> numbers ()-> searchAvailable ( ' US ' );
$ number = $ numbers -> current ();
$ client -> numbers ()-> purchase ( $ number -> getMsisdn (), $ number -> getCountry ());Или вы можете указать номер и страну вручную:
$ client -> numbers ()-> purchase ( ' 14155550100 ' , ' US ' ); Чтобы обновить номер, используйте numbers()->update и передайте параметры конфигурации, которые вы хотите изменить. Чтобы очистить настройку, передайте пустое значение.
$ number = $ client -> numbers ()-> get ( VONAGE_NUMBER );
$ number
-> setAppId ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' )
-> setVoiceDestination ( ' 447700900002 ' , ' tel ' )
-> setWebhook (
Vonage Number Number:: WEBHOOK_VOICE_STATUS ,
' https://example.com/webhooks/status '
)
-> setWebhook (
Vonage Number Number:: WEBHOOK_MESSAGE ,
' https://example.com/webhooks/inbound-sms '
)
;
$ client -> numbers ()-> update ( $ number );
echo " Number updated " . PHP_EOL ; Чтобы отменить номер, укажите msisdn :
$ client -> numbers ()-> cancel ( ' 447700900002 ' );Предоставляется API, позволяющий вам менять секреты API. Вы можете создать новый секрет (максимум два секрета) и удалить существующий после обновления всех приложений.
Чтобы получить список секретов:
$ secretsCollection = $ client -> account ()-> listSecrets ( API_KEY );
/** @var VonageAccountSecret $secret */
foreach ( $ secretsCollection -> getSecrets () as $ secret ) {
echo " ID: " . $ secret -> getId () . " (created " . $ secret -> getCreatedAt () . " ) n" ;
}Вы можете создать новый секрет (созданные даты помогут вам узнать, что есть что):
$ client -> account ()-> createSecret ( API_KEY , ' awes0meNewSekret!!; ' );И удалите старый секрет (любое приложение, все еще использующее эти учетные данные, перестанет работать):
try {
$ response = $ client -> account ()-> deleteSecret ( API_KEY , ' d0f40c7e-91f2-4fe0-8bc6-8942587b622c ' );
} catch ( Vonage Client Exception Request $ e ) {
echo $ e -> getMessage ();
} Если вы знаете префикс страны, в которую хотите позвонить, вы можете использовать конечную точку prefix-pricing , чтобы узнать стоимость звонка на этот номер. Каждый префикс может возвращать несколько стран (например, 1 возвращает US , CA и UM ):
$ results = $ client -> account ()-> getPrefixPricing ( ' 1 ' );
foreach ( $ results as $ price ) {
echo $ price -> getCountryCode (). PHP_EOL ;
echo $ price -> getCountryName (). PHP_EOL ;
foreach ( $ price -> getNetworks () as $ network ) {
echo $ network -> getName () . ' :: ' . $ network -> getCode (). ' :: ' . $ network -> getPrefixPrice (). PHP_EOL ;
}
echo " ---------------- " . PHP_EOL ;
}Проверьте, сколько средств осталось на вашем счету:
$ response = $ client -> account ()-> getBalance ();
echo round ( $ response -> getBalance (), 2 ) . " EUR n" ;Проверьте текущие настройки аккаунта:
$ response = $ client -> account ()-> getConfig ();
print_r ( $ response -> toArray ());Обновите URL-адреса обратного вызова по умолчанию для входящих SMS-сообщений и уведомлений о доставке:
$ 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 ());Чтобы использовать сетевые API Vonage, вам необходимо включить их в сетевом реестре 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 Number Insights позволяет пользователю проверить правильность номера и узнать больше о том, как его использовать.
Вы можете использовать методы basic() или standard() (доступен метод advanced() , но для получения дополнительной информации рекомендуется использовать опцию async), например:
try {
$ insights = $ client -> insights ()-> basic ( PHONE_NUMBER );
echo $ insights -> getNationalFormatNumber ();
} catch ( Exception $ e ) {
// for the Vonage-specific exceptions, try the `getEntity()` method for more diagnostic information
} Данные возвращаются в переменной $insights в приведенном выше примере.
Чтобы получить расширенную информацию, используйте функцию асинхронности и укажите 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
}Ознакомьтесь с документацией и узнайте, чего ожидать от входящего веб-перехватчика, содержащего запрошенные вами данные.
Этот API используется для создания и настройки дополнительных учетных записей, связанных с вашей основной учетной записью, а также для переноса кредита, баланса и купленных номеров между учетными записями. API субаккаунтов отключен по умолчанию. Если вы хотите использовать субаккаунты, обратитесь в службу поддержки, чтобы включить API в вашей учетной записи.
$ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' 34kokdf ' ;
$ subaccounts = $ client -> subaccount ()-> getSubaccounts ( $ apiKey );
var_dump ( $ subaccounts ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ payload = [
' name ' => ' sub name ' ,
' secret ' => ' s5r3fds ' ,
' use_primary_account_balance ' => false
];
$ account = new Account ();
$ account -> fromArray ( $ payload );
$ response = $ client -> subaccount ()-> createSubaccount ( $ apiKey , $ account );
var_dump ( $ response ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ subaccountKey = ' bbe6222f ' ;
$ response = $ client -> subaccount ()-> getSubaccount ( $ apiKey , $ subaccountKey );
var_dump ( $ response ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ subaccountKey = ' bbe6222f ' ;
$ payload = [
' suspended ' => true ,
' use_primary_account_balance ' => false ,
' name ' => ' Subaccount department B '
];
$ account = new Account ();
$ account -> fromArray ( $ payload );
$ response = $ client -> subaccount ()-> updateSubaccount ( $ apiKey , $ subaccountKey , $ account )
var_dump ( $ response ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ filter = new Vonage Subaccount Filter Subaccount([ ' subaccount ' => ' 35wsf5 ' ])
$ transfers = $ client -> subaccount ()-> getCreditTransfers ( $ apiKey );
var_dump ( $ transfers ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ transferRequest = ( new TransferCreditRequest ( $ apiKey ))
-> setFrom ( ' acc6111f ' )
-> setTo ( ' s5r3fds ' )
-> setAmount ( ' 123.45 ' )
-> setReference ( ' this is a credit transfer ' );
$ response = $ this -> subaccountClient -> makeCreditTransfer ( $ transferRequest ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ filter = new Vonage Subaccount Filter Subaccount ([ ' end_date ' => ' 2022-10-02 ' ]);
$ transfers = $ client -> subaccount ()-> getBalanceTransfers ( $ apiKey , $ filter ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ transferRequest = ( new TransferBalanceRequest ( $ apiKey ))
-> setFrom ( ' acc6111f ' )
-> setTo ( ' s5r3fds ' )
-> setAmount ( ' 123.45 ' )
-> setReference ( ' this is a credit transfer ' );
$ response = $ client -> subaccount ()-> makeBalanceTransfer ( $ transferRequest );
var_dump ( $ response ); $ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET ));
$ apiKey = ' acc6111f ' ;
$ numberTransferRequest = ( new NumberTransferRequest ( $ apiKey ))
-> setFrom ( ' acc6111f ' )
-> setTo ( ' s5r3fds ' )
-> setNumber ( ' 4477705478484 ' )
-> setCountry ( ' GB ' );
$ response = $ client -> subaccount ()-> makeNumberTransfer ( $ numberTransferRequest );
var_dump ( $ response );| API | Статус выпуска API | Поддерживается? |
|---|---|---|
| API аккаунта | Общая доступность | |
| API оповещений | Общая доступность | |
| API приложения | Общая доступность | |
| Аудит API | Бета | |
| API разговора | Бета | |
| API отправки | Бета | |
| API внешних учетных записей | Бета | |
| Медиа API | Бета | |
| API для совещаний | Общая доступность | |
| API сообщений | Общая доступность | |
| API-интерфейс Number Insight | Общая доступность | |
| API управления номерами | Общая доступность | |
| API ценообразования | Общая доступность | |
| API ProActive Connect | Бета | |
| Редактировать API | Общая доступность | |
| API отчетов | Бета | |
| СМС API | Общая доступность | |
| API субаккаунтов | Общая доступность | |
| Проверить API | Общая доступность | |
| Проверка API (версия 2) | Общая доступность | |
| Голосовой API | Общая доступность |
Со временем API-интерфейсы Vonage развиваются и добавляют новые функции, меняют способ работы существующих функций, а также устаревают и удаляют старые методы и функции. Чтобы помочь разработчикам узнать, когда вносятся изменения в устаревшие версии, SDK выдает предупреждение E_USER_DEPRECATION . Эти предупреждения не остановят выполнение кода, но могут раздражать в производственных средах.
Чтобы помочь в этом, по умолчанию эти уведомления подавляются. При разработке вы можете включить эти предупреждения, передав конструктору VonageClient дополнительную опцию конфигурации, называемую show_deprecations . Включение этой опции покажет все уведомления об устаревании.
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
[
' show_deprecations ' => true
]
); Если вы заметили чрезмерное количество уведомлений об устаревании в производственных средах, убедитесь, что этот параметр конфигурации отсутствует или, по крайней мере, установлен на false .
unable to get local issuer certificateУ некоторых пользователей возникают проблемы с отправкой запросов из-за следующей ошибки:
Fatal error: Uncaught exception 'GuzzleHttpExceptionRequestException' with message 'cURL error 60: SSL certificate problem: unable to get local issuer certificate (see http://curl.haxx.se/libcurl/c/libcurl-errors.html)'
Это связано с тем, что некоторые установки PHP не поставляются со списком доверенных сертификатов CA. Это проблема конфигурации системы, не специфичная ни для cURL, ни для Vonage.
ВАЖНО : В следующем абзаце мы предоставляем ссылку на пакет сертификатов CA. Vonage не гарантирует безопасность этого пакета, и вам следует просмотреть его самостоятельно перед установкой любого пакета CA на свой компьютер.
Чтобы решить эту проблему, загрузите список доверенных сертификатов CA (например, пакет Curl) и скопируйте его на свой компьютер. Как только это будет сделано, отредактируйте php.ini и установите параметр curl.cainfo :
# Linux/MacOS
curl.cainfo = "/etc/pki/tls/cacert.pem"
# Windows
curl.cainfo = "C:phpextrassslcacert.pem"
Мы разрешаем использование любого адаптера HTTPlug или HTTP-клиента, совместимого с PSR-18, поэтому вы можете создать клиент с альтернативной конфигурацией, если вам это нужно, например, чтобы учесть локальный прокси-сервер или справиться с чем-то еще, специфичным для вашей настройки.
Вот пример, в котором время ожидания по умолчанию сокращается до 5 секунд, чтобы избежать длительных задержек, если у вас нет маршрута к нашим серверам:
$ adapter_client = new Http Adapter Guzzle6 Client ( new GuzzleHttp Client ([ ' timeout ' => 5 ]));
$ vonage_client = new Vonage Client ( new Vonage Client Credentials Basic ( $ api_key , $ api_secret ), [], $ adapter_client ); Если что-то пойдет не так, вы получите Exception . Классы исключений Vonage VonageClientExceptionRequest и VonageClientExceptionServer поддерживают дополнительный метод getEntity() , который вы можете использовать в дополнение к getCode() и getMessage() чтобы узнать больше о том, что пошло не так. Возвращаемая сущность обычно представляет собой объект, связанный с операцией, или объект ответа от вызова API.
Если у вас есть конфликтующая установка пакета, которая не может сосуществовать с рекомендуемым нами пакетом 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 test
Обратите внимание: этот набор тестов большой, и для его запуска может потребоваться значительный объем памяти. Если вы столкнулись с ошибкой «слишком много открытых файлов» в MacOS или Linux, существует способ увеличить количество разрешенных указателей файлов. Увеличьте количество файлов, которые можно открыть, введя следующее в командной строке (10240 — максимальное количество указателей, которые MacOS может открыть в данный момент):
ulimit -n 10240
Эта библиотека активно развивается, и мы будем рады услышать ваше мнение! Пожалуйста, не стесняйтесь создавать проблему или открывать запрос на включение с вашими вопросами, комментариями, предложениями и отзывами.
