Migração da SMS API para a Messages API

A Messages API da Vonage é a forma recomendada para enviar e receber SMS. Ela oferece suporte a vários canais, como SMS, MMS, RCS e WhatsApp, por meio de uma interface única e consistente. Este guia compara a SMS API baseada em HTTP e a Messages API para casos de uso de SMS e orienta sobre a configuração da conta, solicitações de envio, cargas de dados recebidas e alterações no rastreamento de status que você precisa realizar durante uma migração. Ele não aborda integrações SMPP.

Configurando seu Account da Vonage para usar a Messages API

Selecione a Messages API no Painel

O primeiro passo para migrar da SMS API legada para a Messages API é atualizar o Tipo de API de mensagens configuração no Configurações da API página do Painel do Desenvolvedor da Vonage. Selecione Messages API como o Tipo de API aqui.

Se você não alterar essa configuração na SMS API (legada), as mensagens recebidas e os comprovantes de entrega continuarão a usar a configuração da SMS API no Painel.

Configurações no nível da Account x Applications da Vonage

Depois de configurar sua conta para usar a Messages API, você precisa decidir como deseja definir as configurações da Messages API. Há duas maneiras de fazer isso:

• Configurações no nível da conta
• Um aplicativo da Vonage

As principais diferenças entre as duas estão no local onde os webhooks são configurados e nas credenciais utilizadas para autenticação (e, portanto, nos métodos de autenticação disponíveis). O uso da Messages API com configurações no nível da conta é mais semelhante, em termos de configuração, à forma como as configurações da SMS API são definidas. A tabela abaixo compara essas diferenças com mais detalhes.

1. Tanto a SMS API quanto a Messages API também permitem substituir a URL do webhook DLR/Status configurada em cada solicitação.
2. Recomendamos enfaticamente o uso da Messages API v1 para sua migração. Certifique-se de que o Version está definido como v1 nas configurações da sua conta ou em qualquer aplicativo da Vonage que você criar (dependendo da forma de configuração que você estiver usando). Essa é a configuração padrão para todas as novas contas da Vonage, mas pode ser definida como v0.1 em accounts mais antigas, para garantir a compatibilidade com versões anteriores.

Em geral, recomendamos o uso dos Aplicativos da Vonage para sua integração com a Messages API, devido à maior flexibilidade que oferecem e ao uso de JWTs para autenticação. No entanto, como as configurações no nível da conta se assemelham mais à abordagem utilizada pela SMS API, talvez seja interessante considerar uma abordagem em duas etapas para sua migração: primeiro, migrar para as configurações no nível da conta e a autenticação básica para a Messages API e, só depois, passar a utilizar os Applications da Vonage.

O que é uma aplicação da Vonage?

Um aplicativo da Vonage pode ser um conceito novo para desenvolvedores que vêm da SMS API. Trata-se, essencialmente, de um contêiner para a configuração e as credenciais. Não é o mesmo que seu aplicativo de software.

Cada aplicação da Vonage contém:

• Um nome
• Um ID de aplicativo exclusivo
• Um par de chaves pública/privada gerado (usado para autenticação JWT)
• Configurações adicionais específicas do produto. Para a Messages API, isso inclui URLs de webhooks para mensagens recebidas e atualizações de status das mensagens

A SMS API não utiliza aplicativos. Os webhooks são configurados globalmente no nível da conta. Embora você ainda possa usar configurações no nível da conta com a Messages API, se assim desejar, ela também oferece suporte ao uso dos aplicativos da Vonage. Como cada aplicativo possui sua própria configuração e ajustes de webhook, isso facilita o gerenciamento independente de várias integrações.

Por que as Applications da Vonage são recomendadas?

A escolha da abordagem de configuração na Messages API afeta o local onde suas configurações são definidas e também o método de autenticação utilizado.

Os aplicativos da Vonage são recomendados porque:

• Como as configurações são definidas no nível do aplicativo da Vonage e é possível criar vários aplicativos, isso facilita o gerenciamento de múltiplas integrações para diferentes fluxos de trabalho ou casos de uso.
• Os aplicativos da Vonage podem ser criados e gerenciados programaticamente usando a CLI da Vonage ou a API de aplicativos
• Os aplicativos da Vonage permitem o uso de JWTs, gerados por meio de um par de chaves pública e privada, para autenticação. Isso adiciona uma camada extra de segurança ao processo de autenticação em comparação com a autenticação básica.

Como usar as configurações no nível da Account

Se você quiser usar configurações no nível da Account com os webhooks da Messages API, o fluxo básico de configuração é o seguinte:

1. Abrir Configurações da API no Painel de controle.
2. Defina o Versão da Messages API para v1.
3. Configure as URLs dos webhooks de entrada e de status no nível da Account.
4. Resenha Seus Numbers para quaisquer substituições de chamadas recebidas específicas por número que possam alterar o roteamento.
5. Envie solicitações à Messages API usando a autenticação básica.
6. Verifique se as mensagens recebidas e os retornos de chamada de status estão chegando aos endpoints esperados no nível da Account antes de redirecionar o tráfego de produção.

Utilização da Messages API do aplicativo Vonage

Se você deseja roteamento no nível do aplicativo e autenticação por JWT, o fluxo de configuração é o seguinte:

1. Crie uma nova aplicação ou abra a aplicação existente que você deseja usar.
2. Ativar o Mensagens capacidade.
3. Configure as URLs de webhooks de entrada e de status das Applications.
4. Defina o Versão da Messages API para v1.
5. Vincule o número com capacidade para receber SMS a esse aplicativo.
6. Envie solicitações à Messages API usando autenticação JWT.
7. Verifique se as mensagens recebidas e os callbacks de status estão chegando aos endpoints no nível do aplicativo antes de redirecionar o tráfego de produção.

Criar uma aplicação da API da Vonage

Existem três métodos alternativos para criar um aplicativo de Mensagens:

1. Como usar a CLI da Vonage
2. Como usar o painel
3. Como usar a API do aplicativo

Cada um desses métodos é descrito nas seções a seguir.

Como criar uma aplicação de mensagens usando a CLI da Vonage

Para criar seu aplicativo usando a CLI da Vonage, digite o seguinte comando no shell:

Este comando cria uma aplicação da API da Vonage com mensagens capacidade, e as URLs dos webhooks estão configuradas conforme especificado. Ele também gera um arquivo de chave privada my_messages_app.key e cria ou atualiza o vonage_app.json arquivo.

Guarde a chave privada gerada em um local seguro assim que o comando for concluído. A autenticação JWT para a Messages API depende dessa chave e, caso você a perca, não será possível baixar novamente a chave privada original.

Como criar um aplicativo de mensagens usando o painel de controle

Você pode criar um aplicativo de Mensagens no Painel de controle.

Para criar seu aplicativo usando o Painel:

1. Sob Applications No Painel, clique no Criar um novo aplicativo botão.

2. Sob Nome, digite o nome da Application. Escolha um nome que facilite a identificação futura.

3. Clique no botão Gerar chave pública e chave privada. Isso criará um par de chaves pública/privada, e a chave privada será baixada pelo seu navegador.

   Guarde a chave privada baixada em um local seguro. A autenticação JWT para a Messages API depende dessa chave e, caso você a perca, não será possível baixar novamente a chave privada original.

4. Sob Recursos selecione o Mensagens botão.

5. No URL de origem na caixa, digite a URL do seu webhook de mensagens recebidas, por exemplo, https://example.com/webhooks/inbound-message.

6. No URL de status na caixa, digite a URL do seu webhook de status de mensagem, por exemplo, https://example.com/webhooks/message-status.

7. Clique no Criar um novo pedido botão. Agora você será direcionado para a próxima etapa do procedimento de criação do aplicativo, onde poderá vincular um número da API da Vonage ao aplicativo e vincular contas externas, como o Facebook, a esse aplicativo.

8. Se houver um account externo à qual você queira vincular este aplicativo, clique no External accounts linked aba e, em seguida, clique no botão correspondente Link botão correspondente à conta que você deseja vincular.

Você já criou seu aplicativo.

Como criar um aplicativo de mensagens usando a API do aplicativo

A API de Aplicativos permite criar e configurar um aplicativo da Vonage programaticamente — sem usar o painel de controle nem a CLI. Um aplicativo da Vonage criado por meio da API de Aplicativos funciona da mesma forma que um criado pelo painel de controle.

Para obter uma visão geral completa sobre como criar uma aplicação da Vonage, consulte Criar uma aplicação da Vonage.

Como vincular um número de telefone ao seu aplicativo

No Painel, abra o Applications página, selecione o aplicativo que deseja usar e vincule o número a partir do Números de link aba.

Você também pode gerenciar as configurações de webhooks de entrada específicas para cada número a partir de Seus Numbers. O Painel indica que um webhook de entrada por número substitui o webhook de entrada no nível da conta. Se você estiver usando números que também estejam vinculados a uma Application de mensagens, verifique o roteamento resultante em sua conta antes de contar com esse comportamento de substituição.

Envio de SMS (mensagens de saída)

Ponto final

Estrutura da solicitação

Carga útil da Messages API:

{
  "message_type": "text",
  "text": "Hello from Vonage",
  "to": "447700900000",
  "from": "Vonage",
  "channel": "sms"
}

Carga útil da SMS API (legada):

from=Vonage
text=Hello from Vonage
to=447700900000

Principais diferenças no corpo da solicitação

Trechos de código

Os trechos de código a seguir incluem o exemplo do cURL e os exemplos disponíveis do SDK do servidor para cada API.

Trechos de código da Messages API

curl -X POST https://api.nexmo.com/v1/messages \
  -H "Authorization: Bearer "$JWT\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d $'{
    "to": "'${MESSAGES_TO_NUMBER}'",
    "from": "'${SMS_SENDER_ID}'",
    "channel": "sms",
    "message_type": "text",
    "text": "This is an SMS sent using the Vonage Messages API."
  }'

npm install @vonage/server-sdk @vonage/messages

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

/**
 * It is best to send messages using JWT instead of basic auth. If you leave out
 * apiKey and apiSecret, the messages SDK will send requests using JWT tokens
 *
 * @link https://developer.vonage.com/en/messages/technical-details#authentication
 */
const vonage = new Vonage(
  {
    applicationId: VONAGE_APPLICATION_ID,
    privateKey: VONAGE_PRIVATE_KEY,
  },
  {
    ...(MESSAGES_API_URL ? {apiHost: MESSAGES_API_URL} : {}),
  },
);

vonage.messages.send({
  messageType: 'sms',
  channel: Channels.SMS,
  text: 'This is an SMS text message sent using the Messages API',
  to: MESSAGES_TO_NUMBER,
  from: SMS_SENDER_ID,
})
  .then(({ messageUUID }) => console.log(messageUUID))
  .catch((error) => console.error(error));

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

val client = Vonage {
    applicationId(VONAGE_APPLICATION_ID)
    privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}

val messageId = client.messages.send(
    smsText {
        to(MESSAGES_TO_NUMBER)
        from(SMS_SENDER_ID)
        text("This is an SMS text message sent using the Messages API")
    }
)

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

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

VonageClient client = VonageClient.builder()
		.applicationId(VONAGE_APPLICATION_ID)
		.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
		.build();

var response = client.getMessagesClient().sendMessage(
		SmsTextRequest.builder()
			.from(SMS_SENDER_ID).to(MESSAGES_TO_NUMBER)
			.text("This is an SMS text message sent using the Messages API")
			.build()
);
System.out.println("Message sent successfully. ID: " + response.getMessageUuid());

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

Install-Package Vonage

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APP_ID, VONAGE_PRIVATE_KEY_PATH);

var vonageClient = new VonageClient(credentials);

var request = new Vonage.Messages.Sms.SmsRequest
{
    To = MESSAGES_TO_NUMBER,
    From = SMS_SENDER_ID,
    Text = "An SMS sent using the Vonage Messages API"
};

var response = await vonageClient.MessagesClient.SendAsync(request);

composer require vonage/client

$keypair = new \Vonage\Client\Credentials\Keypair(
    file_get_contents(VONAGE_APPLICATION_PRIVATE_KEY_PATH),
    VONAGE_APPLICATION_ID
);

$client = new \Vonage\Client($keypair);

$sms = new \Vonage\Messages\Channel\SMS\SMSText(
    TO_NUMBER,
    FROM_NUMBER,
    'This is an SMS sent using the Vonage PHP SDK'
);

pip install vonage python-dotenv

from vonage import Auth, Vonage
from vonage_messages import Sms

client = Vonage(
    Auth(
        application_id=VONAGE_APPLICATION_ID,
        private_key=VONAGE_PRIVATE_KEY,
    )
)

response = client.messages.send(
    Sms(
        to=MESSAGES_TO_NUMBER,
        from_=SMS_SENDER_ID,
        text='This is an SMS sent using the Vonage Messages API.',
    )
)
print(response)

gem install vonage

client = Vonage::Client.new(
  application_id: VONAGE_APPLICATION_ID,
  private_key: VONAGE_PRIVATE_KEY
)

message = client.messaging.sms(
  message: "A SMS message sent using the Vonage Messages API"
)

client.messaging.send(
  from: SMS_SENDER_ID,
  to: MESSAGES_TO_NUMBER,
  **message
)

Trechos de código da SMS API (versão antiga)

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'
)

Parâmetros opcionais e diferenças entre as versões

Depois que os campos obrigatórios do SMS forem migrados, a próxima etapa é verificar quaisquer parâmetros opcionais da SMS API dos quais sua integração dependa.

Códigos de resposta HTTP

Essa é uma das diferenças comportamentais mais significativas entre as duas APIs.

A SMS API sempre retorna um 200 Código de resposta HTTP, independentemente de ter sido bem-sucedida ou não, com um status parâmetro no corpo da resposta, cujo valor corresponde ao resultado.

A Messages API retorna um 202 código de resposta para solicitações bem-sucedidas, e 4xx ou 5xx códigos de respostas de erro.

Alguns exemplos são apresentados na tabela comparativa abaixo.

Veja Erros da Messages API, Códigos de erro da SMS API, e o Ponto de extremidade de envio da SMS API para obter os detalhes completos do erro.

Resposta de sucesso da SMS API

{
  "message-count": "1",
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "23410"
    }
  ]
}

Resposta de erro da SMS API

{
  "message-count": "1",
  "messages": [
    {
      "status": "4",
      "error-text": "Bad Credentials"
    }
  ]
}

Resposta de sucesso da Messages API

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
}

Resposta de erro da Messages API (401 Não autorizado)

{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Unauthorized",
  "detail": "You did not provide correct credentials.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Recebimento de SMS (mensagens recebidas)

Ambas as APIs enviam mensagens SMS recebidas para uma URL de webhook que você configura. Existem algumas diferenças entre as duas APIs na estrutura da carga útil recebida e na nomenclatura dos parâmetros. A configuração do webhook é abordada em Configurando seu Account da Vonage para usar a Messages API.

Carga útil de entrada da SMS API

Quando uma mensagem é recebida na SMS API, a Vonage envia uma solicitação GET ou POST para a URL do webhook de entrada que você configurou.

Exemplo de carga útil:

{
  "msisdn": "447700900001",
  "to": "447700900000",
  "messageId": "0A0000000123ABCD1",
  "text": "Hello from a user",
  "type": "text",
  "keyword": "HELLO",
  "message-timestamp": "2020-01-01 12:00:00"
}

Carga útil de entrada da Messages API

Quando uma mensagem é recebida na Messages API, a Vonage envia uma solicitação POST para a URL de entrada configurada no seu aplicativo.

Exemplo de carga útil:

{
   "channel": "sms",
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "447700900001",
   "timestamp": "2025-02-03T12:14:25Z",
   "text": "Hello From Vonage!",
   "sms": {
      "num_messages": "2",
      "keyword": "HELLO"
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   },
   "origin": {
      "network_code": "12345"
   }
}

Acompanhamento do status da mensagem

A Messages API utiliza callbacks de status para notificar seu aplicativo quando o status de uma mensagem é alterado. Esses callbacks são o equivalente, na Messages API, aos recibos de entrega (DLRs) utilizados pela SMS API.

Equivalentes de status do DLR

Os equivalentes mais próximos na Messages API para os status DLR da SMS API são apresentados a seguir:

Para obter mais informações, consulte Callbacks de status da Messages API.

Recursos adicionais da Messages API

Embora este guia se concentre na migração da sua integração de SMS, a Messages API oferece uma série de recursos adicionais que vale a pena explorar assim que a migração estiver concluída.

Mensagens multicanal

A Messages API oferece suporte a vários canais por meio de uma única interface de API consistente. Depois de migrar sua integração de SMS, você poderá adicionar novos canais sem alterar sua integração principal:

A estrutura da solicitação é consistente em todos os canais. Para enviar uma mensagem em um canal diferente, basta alterar o campo “canal” e adicionar quaisquer parâmetros específicos do canal. Seu manipulador de webhook para retornos de chamada de status e mensagens recebidas funciona da mesma maneira, independentemente do canal.

Failover

A Messages API oferece suporte a fluxos de trabalho de failover, que permitem que você tente novamente enviar uma mensagem em um canal diferente caso a primeira tentativa seja rejeitada. Por exemplo, você pode enviar uma mensagem pelo WhatsApp e, caso ela seja rejeitada (por exemplo, porque o destinatário não tem o WhatsApp), recorrer ao SMS.

Veja Failover da Messages API para mais informações.

Conteúdo rico

Nos canais compatíveis (RCS, WhatsApp, MMS, Messenger, Viber), a Messages API permite enviar:

• Imagens, vídeos, áudio e anexos
• Modelos de mensagens interativas
• Botões de resposta sugeridos e botões de ação (RCS, WhatsApp)
• Cartões e carrosséis enriquecidos (RCS)

Leitura complementar

• Referência da Messages API
• Detalhes técnicos da Messages API
• Failover da Messages API