vonage php sdk core
4.10.7
Esta biblioteca requiere una versión mínima de PHP 8.1
Esta es la biblioteca cliente PHP para usar la API de Vonage. Para usar esto, necesitarás una cuenta de Vonage. Regístrate gratis aquí.
Para usar la biblioteca del cliente, deberás haber creado una cuenta de Vonage.
Para instalar la biblioteca cliente PHP en su proyecto, le recomendamos utilizar Composer.
composer require vonage/clientTenga en cuenta que esto en realidad apunta a una biblioteca contenedora que incluye un cliente HTTP y esta biblioteca principal. Puede instalar esta biblioteca directamente desde Composer si lo desea, con la posibilidad de elegir el cliente HTTP que utiliza su proyecto.
No es necesario clonar este repositorio para utilizar esta biblioteca en sus propios proyectos. Utilice Composer para instalarlo desde Packagist.
Si eres nuevo en Composer, aquí tienes algunos recursos que pueden resultarte útiles:
Si estás usando Composer, asegúrate de que el cargador automático esté incluido en el archivo de arranque de tu proyecto:
require_once " vendor/autoload.php " ;Cree un cliente con su clave API y su secreto:
$ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET )); Para fines de prueba, es posible que desee cambiar la URL a la que vonage/client realiza solicitudes desde api.vonage.com a otra. Puedes hacer esto proporcionando una matriz que contenga base_api_url como segundo parámetro al crear una instancia VonageClient .
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
[
' base_api_url ' => ' https://example.com '
]
); Para las API que normalmente llegarían a rest.nexmo.com , proporcionar una base_rest_url como opción al constructor cambiará esas solicitudes.
Para usar la API de SMS de Vonage para enviar un mensaje SMS, llame al método $client->sms()->send() .
Se utiliza un objeto de mensaje para crear los mensajes SMS. Cada tipo de mensaje se puede construir con los parámetros requeridos y una interfaz fluida proporciona acceso a parámetros opcionales.
$ text = new Vonage SMS Message SMS ( VONAGE_TO , VONAGE_FROM , ' Test message using PHP client library ' );
$ text -> setClientRef ( ' test-message ' ); El objeto de mensaje se pasa al método send :
$ response = $ client -> sms ()-> send ( $ text );Una vez enviado, el objeto del mensaje se puede utilizar para acceder a los datos de respuesta.
$ data = $ response -> current ();
echo " Sent message to " . $ data -> getTo () . " . Balance is now " . $ data -> getRemainingBalance () . PHP_EOL ; Dado que cada mensaje SMS se puede dividir en varios mensajes, la respuesta contiene un objeto para cada mensaje que se generó. Puede verificar cuántos mensajes se generaron usando la función estándar count() en PHP. Si desea recibir el primer mensaje, puede utilizar el método current() en la respuesta.
$ data = $ response -> current ();
$ data -> getRemainingBalance ();
foreach ( $ response as $ index => $ data ){
$ data -> getRemainingBalance ();
}El ejemplo de envío también tiene ejemplos de trabajo completos.
Puede utilizar un método estático isGsm7() dentro del código del Cliente SMS para determinar si se envía el mensaje utilizando la codificación GSM-7 o Unicode. Aquí hay un ejemplo:
$ 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 ' );
}Los mensajes entrantes se envían a su aplicación como un webhook. La biblioteca Cliente proporciona una forma de crear un objeto de mensaje entrante desde un webhook:
try {
$ inbound = Vonage SMS Webhook Factory:: createFromGlobals ();
error_log ( $ inbound -> getText ());
} catch ( InvalidArgumentException $ e ) {
error_log ( ' invalid message ' );
}También te puede interesar leer la documentación sobre la firma de mensajes.
La API de SMS admite la capacidad de firmar mensajes generando y agregando una firma utilizando un "Secreto de firma" en lugar de su secreto de API. Los algoritmos soportados son:
md5hash1md5sha1sha256sha512Tanto tu aplicación como Vonage deben ponerse de acuerdo sobre qué algoritmo se utiliza. En el panel, visite la página de configuración de su cuenta y en "Configuración de API" puede seleccionar el algoritmo que desea utilizar. Esta es también la ubicación donde encontrará su "Secreto de firma" (es diferente del secreto de API).
Cree un cliente usando estas credenciales y el algoritmo a usar, por ejemplo:
$ client = new Vonage Client ( new Vonage Client Credentials SignatureSecret ( API_KEY , SIGNATURE_SECRET , ' sha256 ' ));Al utilizar este cliente, sus mensajes SMS API se enviarán como mensajes firmados.
También te puede interesar leer la documentación sobre la firma de mensajes.
Si tiene habilitada la firma de mensajes para los mensajes entrantes, el webhook de SMS incluirá los campos sig , nonce y timestamp . Para verificar que la firma proviene de Vonage, crea un objeto Firma utilizando los datos entrantes, su secreto de firma y el método de firma. Luego use el método check() con la firma real que se recibió (generalmente _GET['sig'] ) para asegurarse de que sea correcta.
$ signature = new Vonage Client Signature ( $ _GET , SIGNATURE_SECRET , ' sha256 ' );
// is it valid? Will be true or false
$ isValid = $ signature -> check ( $ _GET [ ' sig ' ]);Utilizando su secreto de firma y los demás parámetros proporcionados, la firma se puede calcular y comparar con el valor de la firma entrante.
La API de mensajes se utiliza para enviar una variedad de mensajes salientes. Actualmente se admiten las siguientes plataformas:
Cada una de estas plataformas tiene una categoría diferente de mensaje que puedes enviar (por ejemplo, con WhatsApp puedes enviar un texto, una imagen, un audio, un video, un archivo o una plantilla pero con Viber solo puedes enviar un texto o una imagen) . Puedes encontrar todos los tipos de mensajes que se pueden enviar en el espacio de nombres VonageMessagesChannel . La razón por la que cada tipo se separa de esta manera es que la plataforma y el tipo de mensaje requieren diferentes parámetros en la llamada API.
VonageMessagesClient está configurado de manera similar al cliente API de SMS. La diferencia es que la autenticación puede ser un token web JSON (JWT) o una autenticación básica. Puede encontrar más información sobre cómo configurar las credenciales de su Cliente en la sección "Uso" de este Léame.
Aquí algunos ejemplos:
Primero, necesitamos crear un nuevo objeto WhatsAppText así:
$ whatsAppText = new Vonage Messages Channel WhatsApp WhatsAppText (
FROM_NUMBER ,
TO_NUMBER ,
' this is a WA text from vonage '
); El cliente API de mensajes tiene un método, send() donde puede enviar cualquiera de los tipos de mensajes proporcionados. Entonces, para enviar este mensaje, el siguiente código lo hará, suponiendo que ya hayas configurado tu cliente de Vonage correctamente:
$ client -> messages ()-> send ( $ whatsAppText ); Su respuesta será una carga útil JSON si el rango de error es 200, o generará una APIException relevante si está dentro de 400/500.
Algunos objetos Channel requieren más argumentos para poder ser creados. Puede ver el mapeo aproximado de estos requisitos comparando los argumentos del constructor con la documentación de la API. Algunos de estos mensajes toman objetos reutilizables personalizados (que se encuentran en el espacio de nombres VonageMessagesMessageObjects ). Uno de ellos es una imagen, así que aquí hay un ejemplo de cómo enviar una imagen de 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 );La API Verify de Vonage facilita demostrar que un usuario proporcionó su propio número de teléfono durante el registro o implementar la autenticación de segundo factor durante el inicio de sesión.
Puede iniciar un proceso de verificación usando un código como este:
$ request = new Vonage Verify Request ( ' 14845551212 ' , ' My App ' );
$ response = $ client -> verify ()-> start ( $ request );
echo " Started verification with an id of: " . $ response -> getRequestId (); Una vez que el usuario ingresa el código PIN que recibió, llame al método check() (ver a continuación) con el ID de solicitud y el PIN para confirmar que el PIN es correcto.
Para cancelar una verificación en curso o activar el siguiente intento de enviar el código de confirmación, puede pasar un objeto de verificación existente a la biblioteca del cliente o simplemente usar un ID de solicitud:
$ client -> verify ()-> trigger ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );
$ client -> verify ()-> cancel ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );De la misma manera, para verificar una verificación se requiere el PIN que proporcionó el usuario y el ID de solicitud:
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" ;
}Puede comprobar el estado de una verificación o acceder a los resultados de verificaciones anteriores utilizando un ID de solicitud. El objeto de verificación proporcionará entonces una interfaz rica:
$ 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 ;
}La API Verify de Vonage tiene soporte SCA (Autenticación segura del cliente), requerido por la PSD2 (Directiva de servicios de pago) y utilizado por aplicaciones que necesitan obtener confirmación de los clientes para los pagos. Incluye el beneficiario y el monto en el mensaje.
Inicie la verificación para un pago como este:
$ request = new Vonage Verify RequestPSD2 ( ' 14845551212 ' , ' My App ' );
$ response = $ client -> verify ()-> requestPSD2 ( $ request );
echo " Started verification with an id of: " . $ response [ ' request_id ' ]; Una vez que el usuario ingresa el código PIN que recibió, llame al punto final /check con el ID de solicitud y el PIN para confirmar que el PIN sea correcto.
Verify v2 de Vonage se basa más en flujos de trabajo asincrónicos a través de. webhooks y flujos de trabajo de verificación más personalizables para el desarrollador. Para iniciar una verificación, necesitará el cliente API, que se encuentra en el espacio de nombres verify2 .
Para realizar una solicitud de Verificación se necesita un canal de comunicación "base" para ofrecer el modo de verificación. Puede personalizar estas interacciones agregando diferentes "flujos de trabajo". Para cada tipo de flujo de trabajo, existe una clase Verify2 que puede crear y que manejará el flujo de trabajo inicial por usted. Por ejemplo:
$ 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 ); El objeto SMSRequest resolverá los valores predeterminados por usted y creará un objeto workflow predeterminado para usar SMS. Sin embargo, puede agregar varios flujos de trabajo que funcionen con lógica alternativa. Por ejemplo, si desea crear una verificación que intente obtener un código PIN del usuario. SMS, pero en caso de que haya un problema con la entrega de SMS, desea agregar un respaldo de voz: puede agregarlo.
$ 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 );Esto agrega el flujo de trabajo de voz a la solicitud de SMS original. La solicitud de verificación intentará resolver el proceso en el orden en que se proporciona (comenzando con el valor predeterminado para el tipo de solicitud).
Los tipos de solicitud base son los siguientes:
SMSRequestWhatsAppRequestWhatsAppInterativeRequestEmailRequestVoiceRequestSilentAuthRequest Para agregar flujos de trabajo, puede ver los flujos de trabajo válidos disponibles como constantes dentro del objeto VerificationWorkflow . Para una mejor experiencia del desarrollador, no puede crear un flujo de trabajo no válido debido a la validación que ocurre en el objeto.
Para enviar un código, deberá rodear el método en un try/catch debido a la naturaleza de la API. Si el código es correcto, el método devolverá un valor booleano true . Si falla, arrojará la excepción relevante de la API que deberá detectarse.
$ code = ' 1234 ' ;
try {
$ client -> verify2 ()-> check ( $ code );
} catch ( Exception $ e ) {
var_dump ( $ e -> getMessage ())
}A medida que ocurren eventos durante un flujo de trabajo de verificación, los eventos y las actualizaciones se activarán como webhooks. Las solicitudes entrantes del servidor que cumplen con los estándares PSR-7 se pueden hidratar en un objeto de valor de webhook para lograr interacciones más agradables. También puedes hidratarlos a partir de una matriz cruda. Si tiene éxito, recibirá un objeto de valor para el tipo de evento/actualización. Los posibles webhooks son:
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 ());Puede cancelar una solicitud si es necesario, antes de que el usuario final haya realizado alguna acción.
$ requestId = ' c11236f4-00bf-4b89-84ba-88b25df97315 ' ;
$ client -> verify2 ()-> cancel ( $ requestId ); Todos los métodos $client->voice() requieren que el cliente se construya con un VonageClientCredentialsKeypair o un VonageClientCredentialsContainer que incluya las credenciales 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 )); Puede iniciar una llamada utilizando un objeto 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 ); Si desea que el sistema elija aleatoriamente un número FROM de los números vinculados a una aplicación, puede omitir el segundo parámetro del constructor de VonageVoiceOutboundCall y el sistema seleccionará un número al azar por usted. .
SimSwap utiliza los estándares CAMARA para determinar cuánto tiempo ha estado una SIM dentro de un dispositivo celular. Esto significa que el mecanismo de autenticación es un poco más complejo que el de otras API. Necesitarás:
Tener su propio Número de Suscriptor que haya sido registrado en la Plataforma Vonage Global Network. Su ID de aplicación del Panel de control Su clave privada
Hay dos métodos disponibles para esta API: checkSimSwap y checkSimSwapDate .
A continuación se muestra un ejemplo del uso de ambos:
$ 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 ' );La verificación de números utiliza los estándares CAMARA API y se utiliza para determinar si una solicitud es válida. A diferencia de otros SDK, el SDK se divide entre el inicio y el final del proceso.
Necesitarás:
Tener su propio Número de Suscriptor que haya sido registrado en la Plataforma Vonage Global Network. Su ID de aplicación del Panel de control Su clave privada, descargada del Panel de control de Vonage
buildFrontEndUrl() en el cliente. Al llamar a esto, deberá proporcionar la ruta por la que se espera que su aplicación reciba una devolución de llamada que contenga un code único. Necesitará tener un número de teléfono autorizado en un territorio autorizado para que esto funcione. Aquí hay un ejemplo ficticio: 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 . El método devuelve un valor booleano de la API. Aquí hay un ejemplo: $ code = $ request -> get ( ' code ' );
$ result = $ client -> numberVerification ()-> verifyNumber (
' 09947777777 ' ,
$ code
);
if ( $ result ) {
Auth:: login ( $ request -> user ())
}
return redirect ( ' login ' );
}Esta API se utiliza para mensajería dentro de la aplicación y contiene una amplia gama de características y conceptos. Para obtener más información, consulte la documentación de 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 );Las listas completas de parámetros para las acciones NCCO se pueden encontrar en los documentos de Voice API.
Cada uno de estos ejemplos utiliza la siguiente estructura para agregar acciones a una llamada:
$ 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 );La URL de su webhook recibirá una carga útil como esta:
{
"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"
}
Luego puedes buscar y almacenar la grabación de esta manera:
$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 ); Admite entrada por teclado y voz. NÓTESE BIEN. la acción de entrada debe seguir una acción con bargeIn establecido en 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 );La URL del webhook recibirá una carga útil que contiene la entrada del usuario con calificaciones de confianza relativas para la entrada de voz.
$ 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 );La URL del webhook recibirá una carga útil según lo especificado en la solicitud.
Puedes recuperar una llamada usando un objeto VonageCallCall o el UUID de la llamada como una cadena:
$ call = $ client -> voice ()-> get ( ' 3fd4d839-493e-4485-b2a5-ace527aacff3 ' );
echo $ call -> getDirection ();También puedes buscar llamadas usando un filtro.
$ filter = new Vonage Voice Filter VoiceFilter ();
$ filter -> setStatus ( ' completed ' );
foreach ( $ client -> search ( $ filter ) as $ call ){
echo $ call -> getDirection ();
}Las aplicaciones son contenedores de configuración. Puedes crear uno usando una estructura de matriz:
$ 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 );También puede pasarle al cliente un objeto de aplicación:
$ 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 );Puede iterar sobre todas sus aplicaciones:
foreach ( $ client -> applications ()-> getAll () as $ application ){
echo $ application -> getName () . PHP_EOL ;
}O puede recuperar una aplicación utilizando una cadena UUID o un objeto de aplicación.
$ application = $ client -> applications ()-> get ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' );Una vez que tenga un objeto de aplicación, puede modificarlo y guardarlo.
$ application = $ client -> applications ()-> get ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' );
$ application -> setName ( ' Updated Application ' );
$ client -> applications ()-> update ( $ application );Puede enumerar los números que pertenecen a su cuenta y, opcionalmente, incluir filtrado:
search_pattern :
0 - el número comienza con pattern1 - el número incluye pattern2 - el número termina con 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 : el número está adjunto a una solicitudfalse : el número no está adjunto a una solicitud $ 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 );Puedes buscar números disponibles para comprar en un país específico:
$ numbers = $ client -> numbers ()-> searchAvailable ( ' US ' ); De forma predeterminada, esto sólo devolverá los primeros 10 resultados. Puedes agregar un filtro VonageNumbersFilterAvailableNumbers adicional para limitar tu búsqueda.
Para comprar un número, puede pasar un valor devuelto por la búsqueda de números:
$ numbers = $ client -> numbers ()-> searchAvailable ( ' US ' );
$ number = $ numbers -> current ();
$ client -> numbers ()-> purchase ( $ number -> getMsisdn (), $ number -> getCountry ());O puede especificar el número y el país manualmente:
$ client -> numbers ()-> purchase ( ' 14155550100 ' , ' US ' ); Para actualizar un número, use numbers()->update y pase las opciones de configuración que desea cambiar. Para borrar una configuración, pase un valor vacío.
$ 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 ; Para cancelar un número, proporcione el msisdn :
$ client -> numbers ()-> cancel ( ' 447700900002 ' );Se proporciona una API para permitirle rotar sus secretos de API. Puede crear un nuevo secreto (hasta un máximo de dos secretos) y eliminar el existente una vez que se hayan actualizado todas las aplicaciones.
Para obtener una lista de los secretos:
$ secretsCollection = $ client -> account ()-> listSecrets ( API_KEY );
/** @var VonageAccountSecret $secret */
foreach ( $ secretsCollection -> getSecrets () as $ secret ) {
echo " ID: " . $ secret -> getId () . " (created " . $ secret -> getCreatedAt () . " ) n" ;
}Puedes crear un nuevo secreto (las fechas creadas te ayudarán a saber cuál es cuál):
$ client -> account ()-> createSecret ( API_KEY , ' awes0meNewSekret!!; ' );Y elimine el antiguo secreto (cualquier aplicación que todavía use estas credenciales dejará de funcionar):
try {
$ response = $ client -> account ()-> deleteSecret ( API_KEY , ' d0f40c7e-91f2-4fe0-8bc6-8942587b622c ' );
} catch ( Vonage Client Exception Request $ e ) {
echo $ e -> getMessage ();
} Si conoce el prefijo de un país al que desea llamar, puede utilizar el punto final prefix-pricing para averiguar los costos de llamar a ese número. Cada prefijo puede devolver varios países (por ejemplo, 1 devuelve US , CA y 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 ;
}Verifique cuánto crédito queda en su cuenta:
$ response = $ client -> account ()-> getBalance ();
echo round ( $ response -> getBalance (), 2 ) . " EUR n" ;Inspeccione la configuración actual de la cuenta:
$ response = $ client -> account ()-> getConfig ();
print_r ( $ response -> toArray ());Actualice las URL de devolución de llamada predeterminadas para mensajes SMS entrantes y recibos de entrega:
$ 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 ());Para utilizar las API de red de Vonage, deberás estar habilitado en el Registro de red de Vonage.
Una vez que tenga un MSNDIN registrado, podrá utilizar SimSwap.
SimSwap utiliza el mecanismo de autenticación de Global Network Platform, por lo que el flujo de autorización se ve un poco diferente al de otros Clientes API. Debajo del capó, el SDK manejará múltiples llamadas para que usted configure un token de acceso estándar CAMARA.
A continuación se muestra un ejemplo de cómo comprobar si una SIM se ha cambiado recientemente:
$ 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 '
}Y así es como se recupera la fecha de intercambio:
$ 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;La API Number Insights permite al usuario comprobar que un número es válido y obtener más información sobre cómo utilizarlo.
Puede usar los métodos basic() o standard() (hay un método advanced() disponible, pero se recomienda usar la opción async para obtener información avanzada), como este:
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
} Los datos se devuelven en la variable $insights en el ejemplo anterior.
Para obtener información avanzada, utilice la función asíncrona y proporcione una URL a la que se enviará el webhook:
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
}Consulte la documentación para saber qué esperar en el webhook entrante que contiene los datos que solicitó.
Esta API se utiliza para crear y configurar subcuentas relacionadas con su cuenta principal y transferir crédito, saldos y números comprados entre cuentas. La API de subcuentas está deshabilitada de forma predeterminada. Si desea utilizar subcuentas, comuníquese con el soporte para habilitar la API en su cuenta.
$ 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 | Estado de lanzamiento de API | ¿Apoyado? |
|---|---|---|
| API de cuenta | Disponibilidad general | |
| API de alertas | Disponibilidad general | |
| API de aplicación | Disponibilidad general | |
| API de auditoría | Beta | |
| API de conversación | Beta | |
| API de envío | Beta | |
| API de cuentas externas | Beta | |
| API de medios | Beta | |
| API de reuniones | Disponibilidad general | |
| API de mensajes | Disponibilidad general | |
| API de información numérica | Disponibilidad general | |
| API de gestión de números | Disponibilidad general | |
| API de precios | Disponibilidad general | |
| API de conexión proactiva | Beta | |
| Redactar API | Disponibilidad general | |
| API de informes | Beta | |
| API de SMS | Disponibilidad general | |
| API de subcuentas | Disponibilidad general | |
| Verificar API | Disponibilidad general | |
| Verificar API (Versión 2) | Disponibilidad general | |
| API de voz | Disponibilidad general |
Con el tiempo, las API de Vonage evolucionan y agregan nuevas funciones, cambian el funcionamiento de las funciones existentes y desaprueban y eliminan métodos y funciones más antiguos. Para ayudar a los desarrolladores a saber cuándo se realizan cambios de obsolescencia, el SDK activará una advertencia E_USER_DEPRECATION . Estas advertencias no detendrán la ejecución del código, pero pueden resultar molestas en entornos de producción.
Para ayudar con esto, estos avisos están suprimidos de forma predeterminada. En desarrollo, puedes habilitar estas advertencias pasando una opción de configuración adicional al constructor VonageClient , llamada show_deprecations . Al habilitar esta opción se mostrarán todos los avisos de obsolescencia.
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
[
' show_deprecations ' => true
]
); Si observa una cantidad excesiva de avisos de desuso en entornos de producción, asegúrese de que la opción de configuración esté ausente o al menos esté configurada en false .
unable to get local issuer certificateAlgunos usuarios tienen problemas para realizar solicitudes debido al siguiente error:
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)'
Esto se debe a que algunas instalaciones de PHP no incluyen una lista de certificados de CA confiables. Este es un problema de configuración del sistema y no es específico ni de cURL ni de Vonage.
IMPORTANTE : en el siguiente párrafo proporcionamos un enlace a un paquete de certificados de CA. Vonage no garantiza la seguridad de este paquete y debes revisarlo tú mismo antes de instalar cualquier paquete de CA en tu máquina.
Para resolver este problema, descargue una lista de certificados de CA confiables (por ejemplo, el paquete curl) y cópiela en su máquina. Una vez hecho esto, edite php.ini y configure el parámetro curl.cainfo :
# Linux/MacOS
curl.cainfo = "/etc/pki/tls/cacert.pem"
# Windows
curl.cainfo = "C:phpextrassslcacert.pem"
Permitimos el uso de cualquier adaptador HTTPlug o cliente HTTP compatible con PSR-18, por lo que puede crear un cliente con una configuración alternativa si lo necesita, por ejemplo, para tener en cuenta un proxy local o tratar con algo más específico de su configuración.
A continuación se muestra un ejemplo que reduce el tiempo de espera predeterminado a 5 segundos para evitar largas demoras si no tiene una ruta a nuestros servidores:
$ 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 ); Cuando las cosas van mal, recibirás una Exception . Las clases de excepción de Vonage VonageClientExceptionRequest y VonageClientExceptionServer admiten un método getEntity() adicional que puedes usar además de getCode() y getMessage() para obtener más información sobre lo que salió mal. La entidad devuelta normalmente será un objeto relacionado con la operación o el objeto de respuesta de la llamada API.
Si tiene una instalación de paquete conflictiva que no puede coexistir con nuestro paquete guzzlehttp/guzzle recomendado, entonces puede instalar el paquete vonage/client-core junto con cualquier paquete que cumpla con el requisito de php-http/client-implementation .
Consulte la página de Packagist para conocer las opciones de implementación del cliente.
Nuestra biblioteca cliente admite el registro de la solicitud y la respuesta para la depuración a través de mecanismos de registro compatibles con PSR-3. Si la opción debug se pasa al cliente y se configura un registrador compatible con PSR-3 en la fábrica de servicios de nuestro cliente, usaremos el registrador para fines de depuración.
$ 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 );HABILITAR EL REGISTRO DE DEPURACIÓN TIENE EL POTENCIAL DE REGISTRAR INFORMACIÓN CONFIDENCIAL, NO HABILITAR EN PRODUCCIÓN
Esta biblioteca tiene un conjunto de pruebas completo diseñado para ejecutarse con PHPUnit.
Para ejecutar, use el compositor:
composer test
Tenga en cuenta: este conjunto de pruebas es grande y puede requerir una cantidad considerable de memoria para ejecutarse. Si encuentra el error "demasiados archivos abiertos" en MacOS o Linux, existe un truco para aumentar la cantidad de punteros de archivos permitidos. Aumente la cantidad de archivos que se pueden abrir ingresando lo siguiente en la línea de comando (10240 es la cantidad máxima de punteros que MacOS abrirá actualmente):
ulimit -n 10240
¡Esta biblioteca se desarrolla activamente y nos encantaría saber de usted! No dude en crear un problema o abrir una solicitud de extracción con sus preguntas, comentarios, sugerencias y opiniones.
