vonage php sdk core
4.10.7
Esta biblioteca requer uma versão mínima do PHP 8.1
Esta é a biblioteca cliente PHP para uso da API da Vonage. Para usar isso, você precisará de uma conta Vonage. Cadastre-se gratuitamente aqui.
Para usar a biblioteca cliente, você precisa ter criado uma conta Vonage.
Para instalar a biblioteca cliente PHP em seu projeto, recomendamos usar o Composer.
composer require vonage/clientObserve que isso na verdade aponta para uma biblioteca wrapper que inclui um cliente HTTP e esta biblioteca principal. Você pode instalar esta biblioteca diretamente do Composer se desejar, com a capacidade de escolher o cliente HTTP que seu projeto usa.
Você não precisa clonar este repositório para usar esta biblioteca em seus próprios projetos. Use o Composer para instalá-lo do Packagist.
Se você é novo no Composer, aqui estão alguns recursos que podem ser úteis:
Se você estiver usando o Composer, certifique-se de que o autoloader esteja incluído no arquivo de inicialização do seu projeto:
require_once " vendor/autoload.php " ;Crie um cliente com sua chave e segredo de API:
$ client = new Vonage Client ( new Vonage Client Credentials Basic ( API_KEY , API_SECRET )); Para fins de teste, você pode querer alterar o URL para o qual vonage/client faz solicitações de api.vonage.com para outro. Você pode fazer isso fornecendo uma matriz contendo base_api_url como o segundo parâmetro ao criar uma instância VonageClient .
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
[
' base_api_url ' => ' https://example.com '
]
); Para APIs que normalmente atingiriam rest.nexmo.com , fornecer um base_rest_url como uma opção para o construtor alterará essas solicitações.
Para usar a API SMS da Vonage para enviar uma mensagem SMS, chame o método $client->sms()->send() .
Um objeto de mensagem é usado para criar as mensagens SMS. Cada tipo de mensagem pode ser construído com os parâmetros necessários e uma interface fluente fornece acesso a parâmetros opcionais.
$ text = new Vonage SMS Message SMS ( VONAGE_TO , VONAGE_FROM , ' Test message using PHP client library ' );
$ text -> setClientRef ( ' test-message ' ); O objeto mensagem é passado para o método send :
$ response = $ client -> sms ()-> send ( $ text );Uma vez enviado, o objeto de mensagem pode ser usado para acessar os dados de resposta.
$ data = $ response -> current ();
echo " Sent message to " . $ data -> getTo () . " . Balance is now " . $ data -> getRemainingBalance () . PHP_EOL ; Como cada mensagem SMS pode ser dividida em múltiplas mensagens, a resposta contém um objeto para cada mensagem gerada. Você pode verificar quantas mensagens foram geradas usando a função padrão count() em PHP. Se quiser receber a primeira mensagem, você pode usar o método current() na resposta.
$ data = $ response -> current ();
$ data -> getRemainingBalance ();
foreach ( $ response as $ index => $ data ){
$ data -> getRemainingBalance ();
}O exemplo de envio também possui exemplos de trabalho completos.
Você pode usar um método estático isGsm7() dentro do código do cliente SMS para determinar se a mensagem deve ser enviada usando a codificação GSM-7 ou Unicode. Aqui está um exemplo:
$ 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 ' );
}As mensagens de entrada são enviadas para seu aplicativo como um webhook. A biblioteca cliente fornece uma maneira de criar um objeto de mensagem de entrada a partir de um webhook:
try {
$ inbound = Vonage SMS Webhook Factory:: createFromGlobals ();
error_log ( $ inbound -> getText ());
} catch ( InvalidArgumentException $ e ) {
error_log ( ' invalid message ' );
}Você também pode ler a documentação sobre assinatura de mensagens.
A API SMS oferece suporte à capacidade de assinar mensagens gerando e adicionando uma assinatura usando um "Segredo de assinatura" em vez do segredo da API. Os algoritmos suportados são:
md5hash1md5sha1sha256sha512Tanto seu aplicativo quanto a Vonage precisam concordar sobre qual algoritmo será usado. No painel, visite a página de configurações da sua conta e em "Configurações da API" você pode selecionar o algoritmo a ser usado. Este também é o local onde você encontrará o seu “Segredo de Assinatura” (é diferente do segredo da API).
Crie um cliente usando essas credenciais e o algoritmo a ser usado, por exemplo:
$ client = new Vonage Client ( new Vonage Client Credentials SignatureSecret ( API_KEY , SIGNATURE_SECRET , ' sha256 ' ));Usando este cliente, suas mensagens da API SMS serão enviadas como mensagens assinadas.
Você também pode ler a documentação sobre assinatura de mensagens.
Se você tiver a assinatura de mensagens habilitada para mensagens recebidas, o webhook do SMS incluirá os campos sig , nonce e timestamp . Para verificar se a assinatura é da Vonage, crie um objeto Signature usando os dados recebidos, seu segredo de assinatura e o método de assinatura. Em seguida, use o método check() com a assinatura real que foi recebida (geralmente _GET['sig'] ) para ter certeza de que está correta.
$ signature = new Vonage Client Signature ( $ _GET , SIGNATURE_SECRET , ' sha256 ' );
// is it valid? Will be true or false
$ isValid = $ signature -> check ( $ _GET [ ' sig ' ]);Usando o segredo da sua assinatura e outros parâmetros fornecidos, a assinatura pode ser calculada e verificada em relação ao valor da assinatura recebida.
A API de mensagens é usada para enviar uma variedade de mensagens de saída. As seguintes plataformas são atualmente suportadas:
Cada uma dessas plataformas possui uma categoria diferente de mensagem que você pode enviar (por exemplo, com o WhatsApp você pode enviar um texto, uma imagem, um áudio, um vídeo, um arquivo ou um modelo, mas para o Viber você só pode enviar um texto ou uma imagem) . Você pode encontrar todos os tipos de mensagens enviáveis no namespace VonageMessagesChannel . A razão pela qual cada tipo é separado dessa forma é que a plataforma e o tipo de mensagem exigem parâmetros diferentes na chamada da API.
O VonageMessagesClient é configurado de maneira semelhante ao SMS API Client. A diferença é que a autenticação pode ser um JSON Web Token (JWT) ou uma Autenticação Básica. Você pode encontrar mais informações sobre como configurar as credenciais do seu cliente na seção 'Uso' deste Leia-me.
Aqui estão alguns exemplos:
Primeiro, precisamos criar um novo objeto WhatsAppText assim:
$ whatsAppText = new Vonage Messages Channel WhatsApp WhatsAppText (
FROM_NUMBER ,
TO_NUMBER ,
' this is a WA text from vonage '
); O Messages API Client possui um método, send() onde você pode enviar qualquer um dos tipos de mensagens fornecidos. Então, para enviar esta mensagem, o código a seguir fará isso, supondo que você já tenha configurado seu cliente Vonage corretamente:
$ client -> messages ()-> send ( $ whatsAppText ); Sua resposta será uma carga JSON se o intervalo de erro for 200 ou lançará uma APIException relevante se estiver entre 400/500.
Alguns objetos Channel requerem mais argumentos para serem criados. Você pode ver o mapeamento aproximado desses requisitos comparando os argumentos do construtor com a documentação da API. Algumas dessas mensagens usam objetos reutilizáveis personalizados (que estão no namespace VonageMessagesMessageObjects ). Uma delas é uma imagem - então aqui está um exemplo de como enviar uma imagem 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 );A API Verify da Vonage facilita provar que um usuário forneceu seu próprio número de telefone durante a inscrição ou implementar a autenticação de segundo fator durante o login.
Você pode iniciar um processo de verificação usando um 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 (); Depois que o usuário inserir o código PIN recebido, chame o método check() (veja abaixo) com o ID da solicitação e o PIN para confirmar se o PIN está correto.
Para cancelar uma verificação em andamento ou acionar a próxima tentativa de envio do código de confirmação, você pode passar um objeto de verificação existente para a biblioteca cliente ou simplesmente usar um ID de solicitação:
$ client -> verify ()-> trigger ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );
$ client -> verify ()-> cancel ( ' 00e6c3377e5348cdaf567e1417c707a5 ' );Da mesma forma, a verificação de uma verificação requer o PIN fornecido pelo usuário e o ID da solicitação:
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" ;
}Você pode verificar o status de uma verificação ou acessar os resultados de verificações anteriores usando um ID de solicitação. O objeto de verificação fornecerá então uma interface 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 ;
}A API Verify da Vonage possui suporte SCA (Secure Customer Authentication), exigido pela PSD2 (Diretiva de Serviços de Pagamento) e usado por aplicativos que precisam obter confirmação de pagamentos dos clientes. Inclui o beneficiário e o valor da mensagem.
Inicie a verificação para um pagamento 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 ' ]; Depois que o usuário inserir o código PIN recebido, chame o endpoint /check com o ID da solicitação e o PIN para confirmar se o PIN está correto.
O Verify v2 da Vonage depende mais de fluxos de trabalho assíncronos via. webhooks e fluxos de trabalho de verificação mais personalizáveis para o desenvolvedor. Para iniciar uma verificação, você precisará do cliente API, que está no namespace verify2 .
Fazer uma solicitação de verificação precisa de um canal de comunicação “base” para entregar o modo de verificação. Você pode personalizar essas interações adicionando diferentes 'fluxos de trabalho'. Para cada tipo de fluxo de trabalho, há uma classe Verify2 que você pode criar e que tratará do fluxo de trabalho inicial para você. Por exemplo:
$ 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 ); O objeto SMSRequest resolverá os padrões para você e criará um objeto workflow padrão para usar o SMS. No entanto, você pode adicionar vários fluxos de trabalho que operam com lógica alternativa. Por exemplo, se você quiser criar uma verificação que tente obter um código PIN do usuário por meio de. SMS, mas caso haja um problema com a entrega do SMS, você deseja adicionar um substituto de voz: você pode adicioná-lo.
$ 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 );Isso adiciona o fluxo de trabalho de voz à solicitação de SMS original. A solicitação de verificação tentará resolver o processo na ordem fornecida (começando com o padrão para o tipo de solicitação).
Os tipos de solicitação base são os seguintes:
SMSRequestWhatsAppRequestWhatsAppInterativeRequestEmailRequestVoiceRequestSilentAuthRequest Para adicionar fluxos de trabalho, você pode ver os fluxos de trabalho válidos disponíveis como constantes no objeto VerificationWorkflow . Para uma melhor experiência do desenvolvedor, não é possível criar um fluxo de trabalho inválido devido à validação que ocorre no objeto.
Para enviar um código, você precisará cercar o método em um try/catch devido à natureza da API. Se o código estiver correto, o método retornará um booleano true . Se falhar, lançará a exceção relevante da API que precisará ser capturada.
$ code = ' 1234 ' ;
try {
$ client -> verify2 ()-> check ( $ code );
} catch ( Exception $ e ) {
var_dump ( $ e -> getMessage ())
}À medida que os eventos acontecem durante um fluxo de trabalho de verificação, os eventos e atualizações serão disparados como webhooks. As solicitações recebidas do servidor que estão em conformidade com os padrões PSR-7 podem ser hidratadas em um objeto de valor do webhook para interações mais agradáveis. Você também pode hidratá-los a partir de uma matriz crua. Se for bem-sucedido, você receberá de volta um objeto de valor para o tipo de evento/atualização. Os possíveis webhooks são:
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 ());Você pode cancelar uma solicitação se necessário, antes que o usuário final execute qualquer ação.
$ requestId = ' c11236f4-00bf-4b89-84ba-88b25df97315 ' ;
$ client -> verify2 ()-> cancel ( $ requestId ); Todos os métodos $client->voice() exigem que o cliente seja construído com um VonageClientCredentialsKeypair ou um VonageClientCredentialsContainer que inclua as credenciais 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 )); Você pode iniciar uma chamada usando um 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 ); Se desejar que o sistema escolha aleatoriamente um número FROM dos números vinculados a um aplicativo, você pode deixar de lado o segundo parâmetro para o construtor de VonageVoiceOutboundCall e o sistema selecionará um número aleatoriamente para você .
O SimSwap usa padrões CAMARA para determinar há quanto tempo um SIM está dentro de um dispositivo celular. Isso significa que o mecanismo de autenticação é um pouco mais complexo do que outras APIs. Você precisará de:
Ter seu próprio número de assinante registrado na Vonage Global Network Platform. Seu ID do aplicativo do painel Sua chave privada
Existem dois métodos disponíveis para esta API: checkSimSwap e checkSimSwapDate .
Aqui está um exemplo de 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 ' );A verificação de número usa padrões CAMARA API e é usada para determinar se uma solicitação é válida. Ao contrário de outros SDKs, o SDK é dividido entre o início e o fim do processo.
Você precisará de:
Ter seu próprio número de assinante registrado na Vonage Global Network Platform. Seu ID do aplicativo do painel Sua chave privada, baixada do Vonage Dashboard
buildFrontEndUrl() no cliente. Ao chamar isso, você precisará fornecer a rota que seu aplicativo deverá receber um retorno de chamada contendo um code exclusivo. Você precisará ter um número de telefone autorizado em um território autorizado para que isso funcione. Aqui está um exemplo fictício: 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 . O método retorna um booleano da API. Aqui está um exemplo: $ code = $ request -> get ( ' code ' );
$ result = $ client -> numberVerification ()-> verifyNumber (
' 09947777777 ' ,
$ code
);
if ( $ result ) {
Auth:: login ( $ request -> user ())
}
return redirect ( ' login ' );
}Esta API é usada para mensagens no aplicativo e contém uma ampla variedade de recursos e conceitos. Para mais informações, dê uma olhada na documentação da 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 );Listas completas de parâmetros para ações NCCO podem ser encontradas nos documentos da API de voz.
Cada um desses exemplos usa a seguinte estrutura para adicionar ações a uma chamada:
$ 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 );O URL do seu webhook receberá uma carga 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"
}
Você pode então buscar e armazenar a gravação assim:
$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 ); Suporta entrada de teclado e voz. Nota. a ação de entrada deve seguir uma ação com bargeIn definido como 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 );O URL do webhook receberá uma carga contendo a entrada do usuário com classificações de confiança relativas para entrada de fala.
$ 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 );O URL do webhook receberá uma carga conforme especificado na solicitação.
Você pode buscar uma chamada usando um objeto VonageCallCall ou o UUID da chamada como uma string:
$ call = $ client -> voice ()-> get ( ' 3fd4d839-493e-4485-b2a5-ace527aacff3 ' );
echo $ call -> getDirection ();Você também pode pesquisar chamadas usando um filtro.
$ filter = new Vonage Voice Filter VoiceFilter ();
$ filter -> setStatus ( ' completed ' );
foreach ( $ client -> search ( $ filter ) as $ call ){
echo $ call -> getDirection ();
}Aplicativos são contêineres de configuração. Você pode criar um usando uma estrutura de array:
$ 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 );Você também pode passar ao cliente um objeto de aplicativo:
$ 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 );Você pode iterar em todos os seus aplicativos:
foreach ( $ client -> applications ()-> getAll () as $ application ){
echo $ application -> getName () . PHP_EOL ;
}Ou você pode buscar um aplicativo usando um UUID de string ou um objeto de aplicativo.
$ application = $ client -> applications ()-> get ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' );Depois de ter um objeto de aplicativo, você poderá modificá-lo e salvá-lo.
$ application = $ client -> applications ()-> get ( ' 1a20a124-1775-412b-b623-e6985f4aace0 ' );
$ application -> setName ( ' Updated Application ' );
$ client -> applications ()-> update ( $ application );Você pode listar os números pertencentes à sua conta e, opcionalmente, incluir filtragem:
search_pattern :
0 - o número começa com pattern1 - o número inclui pattern2 - o número termina com 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 - O número está anexado a um aplicativofalse - O número não está anexado a um aplicativo $ 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 );Você pode pesquisar os números disponíveis para compra em um país específico:
$ numbers = $ client -> numbers ()-> searchAvailable ( ' US ' ); Por padrão, isso retornará apenas os 10 primeiros resultados. Você pode adicionar um filtro adicional VonageNumbersFilterAvailableNumbers para restringir sua pesquisa.
Para comprar um número, você pode passar um valor retornado da pesquisa de número:
$ numbers = $ client -> numbers ()-> searchAvailable ( ' US ' );
$ number = $ numbers -> current ();
$ client -> numbers ()-> purchase ( $ number -> getMsisdn (), $ number -> getCountry ());Ou você pode especificar o número e o país manualmente:
$ client -> numbers ()-> purchase ( ' 14155550100 ' , ' US ' ); Para atualizar um número, use numbers()->update e passe as opções de configuração que deseja alterar. Para limpar uma configuração, passe um valor vazio.
$ 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 um número, forneça o msisdn :
$ client -> numbers ()-> cancel ( ' 447700900002 ' );Uma API é fornecida para permitir que você alterne seus segredos de API. Você pode criar um novo segredo (até no máximo dois segredos) e excluir o existente assim que todos os aplicativos forem atualizados.
Para obter uma lista dos segredos:
$ secretsCollection = $ client -> account ()-> listSecrets ( API_KEY );
/** @var VonageAccountSecret $secret */
foreach ( $ secretsCollection -> getSecrets () as $ secret ) {
echo " ID: " . $ secret -> getId () . " (created " . $ secret -> getCreatedAt () . " ) n" ;
}Você pode criar um novo segredo (as datas criadas ajudarão você a saber qual é qual):
$ client -> account ()-> createSecret ( API_KEY , ' awes0meNewSekret!!; ' );E exclua o segredo antigo (qualquer aplicativo que ainda use essas credenciais irá parar de funcionar):
try {
$ response = $ client -> account ()-> deleteSecret ( API_KEY , ' d0f40c7e-91f2-4fe0-8bc6-8942587b622c ' );
} catch ( Vonage Client Exception Request $ e ) {
echo $ e -> getMessage ();
} Se você souber o prefixo de um país para o qual deseja ligar, poderá usar o endpoint prefix-pricing para descobrir os custos para ligar para esse número. Cada prefixo pode retornar vários países (por exemplo, 1 retorna US , CA e 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 quanto crédito resta em sua conta:
$ response = $ client -> account ()-> getBalance ();
echo round ( $ response -> getBalance (), 2 ) . " EUR n" ;Inspecione as configurações atuais da conta:
$ response = $ client -> account ()-> getConfig ();
print_r ( $ response -> toArray ());Atualize os URLs de retorno de chamada padrão para mensagens SMS recebidas e 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 usar as APIs de rede da Vonage, você precisa estar habilitado no registro da rede Vonage
Depois de registrar um MSNDIN, você poderá usar o SimSwap.
O SimSwap usa o mecanismo de autenticação da Global Network Platform, portanto o fluxo de autorização parece um pouco diferente de outros clientes API. Nos bastidores, o SDK lidará com várias chamadas para você configurar um token de acesso padrão CAMARA.
Aqui está um exemplo de como verificar se um SIM foi trocado recentemente:
$ 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 '
}E aqui está como você recupera a data de troca:
$ 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;A API Number Insights permite que um usuário verifique se um número é válido e saiba mais sobre como usá-lo.
Você pode usar os métodos basic() ou standard() (um método advanced() está disponível, mas é recomendado usar a opção async para obter informações avançadas), assim:
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
} Os dados são retornados na variável $insights no exemplo acima.
Para obter insights avançados, use o recurso assíncrono e forneça um URL para o qual o webhook será enviado:
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
}Confira a documentação para saber o que esperar do webhook recebido contendo os dados que você solicitou.
Esta API é usada para criar e configurar subcontas relacionadas à sua conta principal e transferir créditos, saldos e números comprados entre contas. A API de subcontas está desabilitada por padrão. Se você quiser usar subcontas, entre em contato com o suporte para ativar a API em sua conta.
$ 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 | Status de lançamento da API | Suportado? |
|---|---|---|
| API de conta | Disponibilidade Geral | |
| API de alertas | Disponibilidade Geral | |
| API do aplicativo | Disponibilidade Geral | |
| API de auditoria | Beta | |
| API de conversação | Beta | |
| API de envio | Beta | |
| API de contas externas | Beta | |
| API de mídia | Beta | |
| API de reuniões | Disponibilidade Geral | |
| API de mensagens | Disponibilidade Geral | |
| API de informações numéricas | Disponibilidade Geral | |
| API de gerenciamento de números | Disponibilidade Geral | |
| API de preços | Disponibilidade Geral | |
| API ProActive Connect | Beta | |
| Editar API | Disponibilidade Geral | |
| API de relatórios | Beta | |
| API SMS | Disponibilidade Geral | |
| API de subcontas | Disponibilidade Geral | |
| Verificar API | Disponibilidade Geral | |
| Verificar API (versão 2) | Disponibilidade Geral | |
| API de voz | Disponibilidade Geral |
Com o tempo, as APIs da Vonage evoluem e adicionam novos recursos, alteram a forma como os recursos existentes funcionam e descontinuam e removem métodos e recursos mais antigos. Para ajudar os desenvolvedores a saber quando alterações de descontinuação estão sendo feitas, o SDK acionará um aviso E_USER_DEPRECATION . Esses avisos não interromperão a execução do código, mas podem ser um incômodo em ambientes de produção.
Para ajudar com isso, por padrão esses avisos são suprimidos. No desenvolvimento, você pode ativar esses avisos passando uma opção de configuração adicional para o construtor VonageClient , chamada show_deprecations . Ativar esta opção mostrará todos os avisos de suspensão de uso.
$ client = new Vonage Client (
new Vonage Client Credentials Basic ( API_KEY , API_SECRET ),
[
' show_deprecations ' => true
]
); Se você notar uma quantidade excessiva de avisos de descontinuação em ambientes de produção, certifique-se de que a opção de configuração esteja ausente ou pelo menos definida como false .
unable to get local issuer certificateAlguns usuários têm problemas ao fazer solicitações devido ao seguinte erro:
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)'
Isso ocorre porque algumas instalações do PHP não são fornecidas com uma lista de certificados CA confiáveis. Este é um problema de configuração do sistema e não é específico do cURL ou do Vonage.
IMPORTANTE : No próximo parágrafo fornecemos um link para um pacote de certificados CA. A Vonage não garante a segurança deste pacote e você deve revisá-lo antes de instalar qualquer pacote CA em sua máquina.
Para resolver esse problema, baixe uma lista de certificados CA confiáveis (por exemplo, o pacote curl) e copie-a para sua máquina. Feito isso, edite php.ini e defina o parâmetro curl.cainfo :
# Linux/MacOS
curl.cainfo = "/etc/pki/tls/cacert.pem"
# Windows
curl.cainfo = "C:phpextrassslcacert.pem"
Permitimos o uso de qualquer adaptador HTTPlug ou cliente HTTP compatível com PSR-18, para que você possa criar um cliente com configuração alternativa se precisar, por exemplo, para levar em conta um proxy local, ou lidar com algo específico para sua configuração.
Aqui está um exemplo que reduz o tempo limite padrão para 5 segundos para evitar longos atrasos se você não tiver rota para nossos 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 ); Quando as coisas dão errado, você receberá uma Exception . As classes de exceção Vonage VonageClientExceptionRequest e VonageClientExceptionServer suportam um método getEntity() adicional que você pode usar além de getCode() e getMessage() para descobrir mais sobre o que deu errado. A entidade retornada normalmente será um objeto relacionado à operação ou o objeto de resposta da chamada de API.
Se você tiver uma instalação de pacote conflitante que não pode coexistir com nosso pacote guzzlehttp/guzzle recomendado, então você pode instalar o pacote vonage/client-core junto com qualquer pacote que satisfaça o requisito php-http/client-implementation .
Consulte a página Packagist para implementação do cliente para opções.
Nossa biblioteca cliente tem suporte para registrar a solicitação e a resposta para depuração por meio de mecanismos de registro compatíveis com PSR-3. Se a opção debug for passada para o cliente e um registrador compatível com PSR-3 estiver configurado na fábrica de serviços do nosso cliente, usaremos o registrador para fins de depuração.
$ 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 );ATIVAR O REGISTRO DE DEPURAÇÃO TEM POTENCIAL PARA REGISTRO DE INFORMAÇÕES SENSÍVEIS, NÃO ATIVAR NA PRODUÇÃO
Esta biblioteca possui um conjunto de testes completo projetado para ser executado com PHPUnit.
Para executar, use o compositor:
composer test
Observação: este conjunto de testes é grande e pode exigir uma quantidade considerável de memória para ser executado. Se você encontrar o erro “muitos arquivos abertos” no MacOS ou Linux, há um hack para aumentar a quantidade de ponteiros de arquivo permitidos. Aumente a quantidade de arquivos que podem ser abertos digitando o seguinte na linha de comando (10240 é a quantidade máxima de ponteiros que o MacOS abrirá atualmente):
ulimit -n 10240
Esta biblioteca é desenvolvida ativamente e adoramos ouvir sua opinião! Sinta-se à vontade para criar um problema ou abrir uma solicitação pull com suas perguntas, comentários, sugestões e feedback.
