nvoip-ruby

SDK e exemplos oficiais da Nvoip para integrar a API v3 com OAuth, chamadas, OTP, WhatsApp, SMS e saldo em Ruby.

Migração para v3

Esta é uma quebra de compatibilidade: use create_client_credentials_token e envie o access token RS256 em Authorization: Bearer. O SDK usa https://api.nvoip.com.br/auth/oauth2/token; não use napikey, password grant ou /v3/oauth/token. Para SMS de texto livre, valide antes a política e o template aprovado aplicáveis à sua conta.

Os tokens retornados devem ser consumidos somente pelo backend. Não os registre em logs, commits ou mensagens. Em OTP, methods é um objeto, por exemplo { sms: true } para phoneNumber ou { email: true } para email.

Requisitos

Ruby 3.0+

Instalacao

gem install nvoip

Configuração

cp .env.example .env

Ou exporte:

export NVOIP_OAUTH_CLIENT_ID="seu_client_id"
export NVOIP_OAUTH_CLIENT_SECRET="seu_client_secret"
export NVOIP_CALLER="1049"
export NVOIP_TARGET_NUMBER="11999999999"

Fluxos cobertos

gerar access_token
renovar token
consultar saldo
enviar SMS
realizar chamada
enviar OTP
validar OTP
listar templates de WhatsApp
enviar template de WhatsApp

Exemplos

ruby examples/create_client_credentials_token.rb
ruby examples/get_balance.rb
ruby examples/send_sms.rb
ruby examples/create_call.rb
ruby examples/send_otp.rb
ruby examples/check_otp.rb
ruby examples/list_whatsapp_templates.rb
ruby examples/send_whatsapp_template.rb

Destinatário WhatsApp

O exemplo mantém NVOIP_WA_DESTINATION para telefone. Para o contrato tipado, use NVOIP_WA_RECIPIENT_TYPE=phone|bsuid|parent_bsuid e NVOIP_WA_RECIPIENT_VALUE, sem destination. BSUID é opaco; não use @username nem o coloque em campo de telefone. Exemplos mascarados: US.MASKED_BSUID_001 e PARENT.MASKED_BSUID_001.

SDK web

Para o fluxo de popup com telefone e código, use em conjunto o repositório nvoip-web-sdk. Este repo cobre o consumo server-side da API.

nvoip

Runtime