Introdução à SMS API da Vonage

O Serviço de Mensagens Curtas (SMS) é um serviço de mensagens de texto que utiliza protocolos de comunicação padronizados para enviar mensagens de texto curtas para dispositivos ou entre eles. Essas mensagens são transmitidas por meio de redes de telefonia celular.

As APIs de comunicação, como a Messages API da Vonage, permitem enviar mensagens SMS programaticamente, por meio de uma solicitação HTTP a um endpoint da API. A mensagem é então encaminhada para a rede celular para ser entregue no dispositivo do destinatário.

A Messages API e a SMS API

Atualmente, existem duas SMS APIs da Vonage com as quais você pode enviar mensagens SMS:

• O Messages API
• O SMS API

Existem algumas diferenças entre as duas APIs que talvez você queira levar em consideração ao decidir qual delas usar.

Messages API

• A Messages API é uma API de mensagens multicanal que oferece suporte a outros canais de mensagens, além do SMS
• Isso inclui outros canais baseados em rede, como MMS e RCS, bem como canais OTT, como o WhatsApp e o Facebook Messenger
• Todos os canais utilizam o mesmo endpoint e a mesma estrutura básica para as cargas de solicitação; assim, é possível utilizar vários canais por meio de uma única integração
• A Messages API continuará sendo aprimorada com novos recursos e suporte para canais de rede e OTT
• A Messages API oferece um webhook de status de mensagens que suporta os seguintes status:
  • submitted
  • delivered
  • rejected
  • undeliverable

SMS API (versão antiga)

• A SMS API oferece Comprovantes de entrega para segmentos de mensagens individuais (nos casos em que uma mensagem longa foi dividida em várias partes para envio).
• A SMS API Comprovantes de entrega suportam os seguintes status:
  • accepted
  • delivered
  • buffered
  • expired
  • failed
  • rejected
  • unknown

Enviar um SMS

Este exemplo mostra como enviar um SMS para o número de sua escolha.

Primeiro, Crie um Account na Vonage se você ainda não tiver uma, e anote sua chave e seu segredo da API no página de introdução do painel de controle.

Substitua os seguintes valores de espaço reservado no código de exemplo:

curl -X POST https://rest.nexmo.com/sms/json \
  -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \
  -d "from=${SMS_SENDER_ID}" \
  -d "to=${SMS_TO_NUMBER}" \
  -d 'text=A text message sent using the Vonage SMS API'

npm install @vonage/server-sdk

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET,
});

vonage.sms.send({
  to: SMS_TO_NUMBER,
  from: SMS_SENDER_ID,
  text: 'A text message sent using the Vonage SMS API',
})
  .then((resp) => {
    console.log('Message sent successfully');
    console.log(resp);
  })
  .catch((err) => {
    console.log('There was an error sending the messages.');
    console.error(err);
  });

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

val client = Vonage {
    apiKey(VONAGE_API_KEY)
    apiSecret(VONAGE_API_SECRET)
}

val response = client.sms.sendText(
    from = SMS_SENDER_ID,
    to = SMS_TO_NUMBER,
    message = "Hello from Vonage SMS API"
)

println(
    if (response.wasSuccessfullySent())
        "Message sent successfully."
    else
        "Message failed with error: ${response[0].errorText}"
)

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

implementation 'com.vonage:server-sdk:9.3.1'

VonageClient client = VonageClient.builder().apiKey(VONAGE_API_KEY).apiSecret(VONAGE_API_SECRET).build();

TextMessage message = new TextMessage(
        SMS_SENDER_ID, SMS_TO_NUMBER,
        "A text message sent using the Vonage SMS API"
);

SmsSubmissionResponse response = client.getSmsClient().submitMessage(message);

if (response.getMessages().get(0).getStatus() == MessageStatus.OK) {
    System.out.println("Message sent successfully.");
} else {
    System.out.println("Message failed with error: " + response.getMessages().get(0).getErrorText());
}

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Install-Package Vonage

using Vonage;
using Vonage.Request;

var credentials = Credentials.FromApiKeyAndSecret(
    vonageApiKey,
    vonageApiSecret
    );

var vonageClient = new VonageClient(credentials);

var response = await vonageClient.SmsClient.SendAnSmsAsync(new Vonage.Messaging.SendSmsRequest()
{
    To = SMS_TO_NUMBER,
    From = SMS_SENDER_ID,
    Text = "A text message sent using the Vonage SMS API"
});
Console.WriteLine(response.Messages[0].To);

composer require vonage/client

$keypair = new \Vonage\Client\Credentials\Keypair(VONAGE_PRIVATE_KEY, VONAGE_APPLICATION_ID);
$client = new \Vonage\Client($keypair);

$response = $client->sms()->send(
    new \Vonage\SMS\Message\SMS(TO_NUMBER, BRAND_NAME, 'A text message sent using the Vonage SMS API')
);

$message = $response->current();

if ($message->getStatus() == 0) {
    echo "The message was sent successfully\n";
} else {
    echo "The message failed with status: " . $message->getStatus() . "\n";
}

pip install vonage python-dotenv

from vonage import Auth, Vonage
from vonage_sms import SmsMessage, SmsResponse

client = Vonage(Auth(api_key=VONAGE_API_KEY, api_secret=VONAGE_API_SECRET))

message = SmsMessage(
    to=SMS_TO_NUMBER,
    from_=SMS_SENDER_ID,
    text="A text message sent using the Vonage SMS API.",
)

response: SmsResponse = client.sms.send(message)
print(response)

gem install vonage

client = Vonage::Client.new(
  api_key: VONAGE_API_KEY,
  api_secret: VONAGE_API_SECRET
)

client.sms.send(
  from: SMS_SENDER_ID,
  to: SMS_TO_NUMBER,
  text: 'A text message sent using the Vonage SMS API'
)

Solução de problemas

Se você tiver problemas ao fazer chamadas de API, certifique-se de verificar o valor retornado campo de status para casos específicos códigos de erro.

Importante: Se você é um cliente dos EUA que utiliza a SMS API para enviar tráfego a partir de um número longo de 10 dígitos com código de país +1 (10 DLC) para redes nos EUA, é necessário registrar uma marca e uma campanha para obter aprovação para o envio. Após a aprovação, é necessário vincular um número à campanha. Consulte o 10 Seção de suporte a DLCs.

Concepts da SMS API da Vonage

Antes de usar a SMS API da Vonage, familiarize-se com o seguinte:

• Formato numérico - A SMS API exige que os números de telefone estejam no formato E.164.

• Autenticação - A SMS API realiza a autenticação por meio da chave e do segredo da API do seu Account.

• Webhooks - A SMS API envia solicitações HTTP ao servidor web do seu aplicativo para que você possa processá-las. Por exemplo: SMS recebidas e confirmaciones de entrega.

Referência

• Referência da SMS API
• Campo de status do objeto de resposta
• Códigos de erro