Migración de SMS API a Messages API

Messages API de Vonage es la forma recomendada de enviar y recibir SMS. Admite múltiples canales como SMS, MMS, RCS y WhatsApp a través de una interfaz única y consistente. Esta guía compara la API de SMS basada en HTTP y la API de Messages para casos de uso de SMS, y explica la configuración de la cuenta, las solicitudes salientes, las cargas útiles entrantes y los cambios de seguimiento de estado que debes realizar durante una migración. No cubre las integraciones SMPP.

Cómo configurar tu cuenta de Vonage para usar Messages API

Seleccione la API Messages en el Panel de control

El primer paso para migrar de la API de SMS heredada a la API de Messages consiste en actualizar el archivo Tipo de API de mensajería en el Ajustes API página del panel para desarrolladores de Vonage. Selecciona Messages API como el Tipo de API aquí.

Si no cambia esta configuración de SMS API (heredada), los mensajes entrantes y los recibos de entrega seguirán utilizando la configuración de SMS API en el Panel de control.

Configuración a nivel de cuenta vs. Aplicaciones de Vonage

Una vez que haya configurado su Account para utilizar el API de Messages, deberá decidir cómo desea configurar los ajustes del API de Messages. Hay dos maneras de hacerlo:

• Configuración a nivel de Account
• Una aplicación de Vonage

Las principales diferencias entre ambas son la configuración de los webhooks y las credenciales utilizadas para la autenticación (y, por tanto, los métodos de autenticación disponibles). El uso de Messages API con ajustes a nivel de cuenta es más parecido, en términos de configuración, a cómo se configuran los ajustes para SMS API. En la tabla siguiente se comparan las diferencias con más detalle.

1. Tanto la SMS API como la Messages API también permiten anular la URL del webhook DLR/Status configurada para cada solicitud.
2. Le recomendamos encarecidamente que utilice Messages API v1 para su migración. Asegúrese de que la Version se establece en v1 ya sea en la configuración de tu cuenta o en cualquier aplicación de Vonage que crees (según el enfoque de configuración que estés utilizando). Este es el valor predeterminado para todas las nuevas cuentas de Vonage, pero puede configurarse en v0.1 en cuentas antiguas por compatibilidad con versiones anteriores.

En general, recomendaríamos usar Vonage Applications para tu integración con Messages API debido a su mayor flexibilidad y al uso de JWT para la autenticación. Sin embargo, dado que las configuraciones a nivel de cuenta se acercan más al enfoque utilizado por la API de SMS, es posible que desees considerar un enfoque de dos pasos para tu migración, primero pasar a las configuraciones a nivel de cuenta y la autenticación básica para la API de Messages antes de usar las aplicaciones de Vonage.

¿Qué es una aplicación de Vonage?

Una aplicación de Vonage puede ser un concepto nuevo para los desarrolladores que provienen de SMS API. Es esencialmente un contenedor para la configuración y las credenciales. No es lo mismo que tu aplicación de software.

Cada aplicación de Vonage contiene:

• Un nombre
• Un identificador único de Applications
• Un par de claves pública/privada generado (utilizado para la autenticación JWT)
• Ajustes adicionales específicos del producto. En el caso de la Messages API, se trata de las URL de los webhooks para los mensajes entrantes y las actualizaciones del estado de los mensajes

La SMS API no utiliza Applications. Los webhooks se configuran globalmente a nivel de Account. Aunque puede seguir utilizando la configuración a nivel de cuenta con la Messages API si así lo desea, ésta también admite el uso de Vonage Applications. Dado que cada aplicación tiene su propia configuración y ajustes de webhook, esto facilita la gestión de múltiples integraciones de forma independiente.

¿Por qué se recomiendan las aplicaciones de Vonage?

La elección del enfoque de configuración en la Messages API afecta al lugar donde se configuran los ajustes y también al método de autenticación utilizado.

Vonage Applications se recomienda porque:

• Como las configuraciones se definen a nivel de Vonage Applications y puedes crear muchas aplicaciones, esto facilita la administración de múltiples integraciones para diferentes flujos de trabajo o casos de uso comerciales.
• Las Applications de Vonage pueden crearse y administrarse mediante programación con la CLI o la API de aplicaciones de Vonage.
• Las Applications de Vonage permiten el uso de JWT, generados mediante un par de claves públicas/privadas, para la autenticación. Esto agrega una capa adicional de seguridad al proceso de autenticación en comparación con la autenticación básica.

Uso de la configuración a nivel de cuenta

Si desea utilizar la configuración a nivel de cuenta con los webhooks de Messages API, el flujo de configuración básico es el siguiente:

1. Abrir Ajustes API en el Cuadro de mandos.
2. Fije el Versión de la API de Messages a v1.
3. Configure las URL de los webhooks de entrada y de estado a nivel de Account.
4. Consulte Tus Numbers para cualquier anulación de entrada por número que pudiera cambiar el enrutamiento.
5. Envíe solicitudes a la API de Messages utilizando la autenticación básica.
6. Valide que los mensajes entrantes y las devoluciones de llamada de estado llegan a los puntos finales de nivel de cuenta esperados antes de conmutar el tráfico de producción.

Cómo usar una aplicación de Vonage para Messages API

Si desea enrutamiento a nivel de aplicación y autenticación JWT, el flujo de configuración es:

1. Cree una nueva aplicación o abra la aplicación existente que desee utilizar.
2. Habilitar el Mensajes capacidad.
3. Configure las URL de los webhooks de entrada y de estado de la aplicación.
4. Fije el Versión de la API de Messages a v1.
5. Vincular el número compatible con SMS a esa aplicación.
6. Envíe solicitudes a la API de Messages utilizando la autenticación JWT.
7. Validar que los mensajes entrantes y las devoluciones de llamada de estado llegan a los puntos finales a nivel de aplicación antes de conmutar el tráfico de producción.

Crear una aplicación API de Vonage

Existen tres métodos alternativos para crear una aplicación de Mensajes:

1. Uso de la CLI de Vonage
2. Uso del panel de control
3. Uso de la API de aplicaciones

Cada uno de estos métodos se describe en las secciones siguientes.

Cómo crear una aplicación de mensajes con la CLI de Vonage

Para crear tu aplicación usando la CLI de Vonage, ingresa el siguiente comando en el shell:

Este comando crea una aplicación API de Vonage con un mensaje capacidady las URL de los webhooks están configuradas según lo especificado. También genera un archivo de clave privada my_messages_app.key y crea o actualiza el vonage_app.json archivo.

Cómo crear una aplicación de mensajes con el panel de control

Puede crear una aplicación Mensajes en la sección Cuadro de mandos.

Para crear su aplicación utilizando el Panel de control:

1. En Applications en el Panel de control, haga clic en el botón Crear una nueva aplicación botón.

2. En NombreIntroduzca el nombre de la aplicación. Elija un nombre para facilitar futuras referencias.

3. Pulse el botón Generar clave pública y privada. Esto creará un par de claves pública/privada y su navegador descargará la clave privada.

4. En Capacidades seleccione el Mensajes botón.

5. En el URL de entrada introduzca la URL de su webhook de mensajes entrantes, por ejemplo, https://example.com/webhooks/inbound-message.

6. En el URL de estado introduzca la URL de su webhook de estado de mensajes, por ejemplo, https://example.com/webhooks/message-status.

7. Haga clic en el botón Generar nueva aplicación botón . Ahora pasarás al siguiente paso del procedimiento para crear una aplicación, donde podrás vincular un número API de Vonage a la aplicación y vincular cuentas externas, como Facebook, a esta aplicación.

8. Si hay una cuenta externa a la que desea vincular esta aplicación, haga clic en el botón Cuentas externas vinculadas y, a continuación, haga clic en el botón Enlace de la Account que desea vincular.

Ya ha creado su aplicación.

Cómo crear una aplicación de Messages API

La API de aplicaciones te permite crear y configurar una aplicación de Vonage mediante programación, sin usar el panel ni la CLI. Una aplicación de Vonage creada a través de la API de aplicaciones funciona igual que una creada a través del panel.

Para obtener información general sobre cómo crear una aplicación de Vonage, consulta Crear una aplicación de Vonage.

Vincular un número de teléfono a su aplicación

En el cuadro de mandos, abra la ventana Applications páginaseleccione la aplicación que desee utilizar y vincule el número desde el menú de esa aplicación. Números de enlace ficha.

También puede gestionar la configuración de los webhooks de entrada específicos de cada número desde Tus Numbers. El Panel de control indica que un webhook de entrada por número anula el webhook de entrada a nivel de cuenta. Si utiliza Numbers que también están vinculados a una aplicación de Mensajes, valide el enrutamiento resultante en su cuenta antes de confiar en ese comportamiento de anulación.

Enviar un SMS (Mensajes salientes)

Punto final

Solicitar estructura

Carga útil de la API de Messages:

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

Carga útil de SMS API (heredada):

from=Vonage
text=Hello from Vonage
to=447700900000

Diferencias clave en el cuerpo de la solicitud

Fragmentos de código

Los siguientes fragmentos de código incluyen el ejemplo cURL y los ejemplos Server SDK disponibles para cada API.

Fragmentos de código de la API de Messages

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

Fragmentos de código de la SMS API (heredada)

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

Parámetros opcionales y diferencias de funciones

Una vez migrados los campos SMS obligatorios, el siguiente paso es revisar los parámetros SMS API opcionales de los que depende tu integración.

Códigos de respuesta HTTP

Esta es una de las diferencias de comportamiento más significativas entre las dos API.

La SMS API siempre devuelve un 200 código de respuesta HTTP, independientemente del éxito o el fracaso, con un status en el cuerpo de la respuesta, cuyo valor corresponde al resultado.

La API Messages devuelve un archivo 202 código de respuesta para las solicitudes correctas, y 4xx o 5xx códigos para las respuestas de error.

En el siguiente cuadro comparativo se muestran algunos ejemplos.

Véase Messages API errores, Códigos de error de SMS APIy el Punto final de envío de SMS API para conocer todos los detalles del error.

SMS API Respuesta correcta

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

Respuesta a error de SMS API

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

Messages API Respuesta correcta

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

Messages API Error Response (401 No autorizado)

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

Recibir un SMS (Mensajes entrantes)

Ambas API envían mensajes SMS entrantes a una URL de webhook configurada por ti. Existen algunas diferencias entre las dos API en cuanto a la estructura de la carga útil entrante y la denominación de los parámetros. La configuración de los webhooks se explica en Cómo configurar tu cuenta de Vonage para usar Messages API.

Carga útil de entrada de SMS API

Cuando se recibe un mensaje en la API de SMS, Vonage envía una solicitud

Ejemplo 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 de la API de Messages

Cuando se recibe un mensaje en Messages API, Vonage envía una solicitud

Ejemplo 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"
   }
}

Seguimiento del estado de los mensajes

La API de Messages utiliza retrollamadas de estado para notificar a su aplicación cuando cambia el estado de un mensaje. Son el equivalente en la Messages API de los recibos de entrega (DLR) utilizados por la SMS API.

Equivalentes de estado DLR

A continuación se muestran los equivalentes más cercanos de la API de Messages para los estados DLR de la API de SMS:

Para más información, consulte Llamadas de estado de la API de Messages.

Funciones adicionales de la Messages API

Aunque esta guía se centra en la migración de la integración de SMS, Messages API ofrece una serie de funciones adicionales que merece la pena explorar una vez completada la migración.

Mensajería multicanal

Messages API admite varios canales a través de una única y coherente interfaz API. Una vez que haya migrado su integración de SMS, puede añadir nuevos canales sin cambiar su integración principal:

La estructura de la solicitud es la misma para todos los canales. Para enviar un mensaje por un canal diferente, cambie el campo del canal y añada los parámetros específicos del canal. El gestor de webhooks para devoluciones de llamada de estado y mensajes entrantes funciona de la misma manera independientemente del canal.

Conmutación por error

La Messages API admite flujos de trabajo de conmutación por error, que le permiten reintentar automáticamente un mensaje en un canal diferente si el primer intento falla o no se lee dentro de una ventana de tiempo especificada. Por ejemplo, puede enviar un mensaje de WhatsApp y reintentarlo por SMS si el destinatario no tiene WhatsApp o no lee el mensaje en un plazo determinado.

Véase Fallo de la API de Messages para más información.

Contenido enriquecido

En los canales que lo admiten (RCS, WhatsApp, MMS, Messenger, Viber), la Messages API permite enviar:

• Imágenes, vídeo, audio y archivos adjuntos
• Plantillas de mensajes interactivos
• Botones de respuesta y de acción sugeridos (RCS, WhatsApp)
• Tarjetas enriquecidas y carruseles (RCS)

Lecturas complementarias

• Referencia de la API Messages
• Detalles técnicos de la API de Messages
• Fallo de la API de Messages