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.

Configuración de tu cuenta de Vonage para utilizar la Messages API

Seleccione la API Messages en el Panel de control

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

Si no modificas este ajuste de la SMS API (heredada), los mensajes entrantes y los acuses de recibo seguirán utilizando la configuración de la SMS API del panel de control.

Configuración a nivel de Account frente a las 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 cuenta
• Una aplicación de Vonage

Las principales diferencias entre ambas residen en el lugar donde se configuran los webhooks y en las credenciales utilizadas para la autenticación (y, por lo tanto, en los métodos de autenticación disponibles). El uso de la Messages API con ajustes a nivel de cuenta se asemeja más, en cuanto a la configuración, a la forma en que se configuran los ajustes de la 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. Recomendamos encarecidamente que utilices la Messages API v1 para tu migración. Asegúrate de que el Version se establece en v1 ya sea en la configuración de tu Account o en cualquier Application de Vonage que crees (dependiendo del método de configuración que utilices). Esta es la opción predeterminada para todas las cuentas nuevas de Vonage, pero se puede cambiar a v0.1 in older accounts, for compatibility with previous versions.

En general, recomendamos utilizar las aplicaciones de Vonage para la integración de la Messages API, debido a su mayor flexibilidad y al uso de JWT para la autenticación. Sin embargo, dado que la configuración a nivel de cuenta se asemeja más al enfoque utilizado por la SMS API, quizá le convenga plantearse un enfoque en dos fases para su migración: primero, pasar a la configuración a nivel de cuenta y a la autenticación básica para la Messages API, y después utilizar las aplicaciones de Vonage.

¿Qué es una aplicación de Vonage?

Una aplicación de Vonage puede resultar un concepto nuevo para los desarrolladores que provienen del ámbito de la SMS API. Se trata, básicamente, de 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 de aplicación único
• 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 aplicaciones. Los webhooks se configuran de forma global a nivel de cuenta. Aunque, si lo prefieres, puedes seguir utilizando la configuración a nivel de cuenta con la Messages API, esta además Admite el uso de las aplicaciones de Vonage. Dado que cada aplicación tiene su propia configuración y ajustes de webhook, esto facilita la gestión independiente de múltiples integraciones.

¿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:

• Dado que la configuración se define a nivel de la aplicación de Vonage y que se pueden crear muchas aplicaciones, esto facilita la gestión de múltiples integraciones para diferentes flujos de trabajo empresariales o casos de uso.
• 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 quieres utilizar la configuración a nivel de Account con los webhooks de la Messages API, el proceso básico de configuración es el siguiente:

1. Abrir Ajustes API en el Panel de control.
2. Fije el Versión de la Messages API a v1.
3. Configura las URL de los webhooks de entrada y de estado a nivel de Account.
4. Reseña Tus Numbers para cualquier anulación de entrada por número que pudiera cambiar el enrutamiento.
5. Envía solicitudes a la Messages API utilizando la autenticación básica.
6. Comprueba que los mensajes entrantes y las respuestas de estado lleguen a los puntos finales previstos a nivel de Account antes de desviar 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. Crea una nueva aplicación o abre la aplicación existente que quieras utilizar.
2. Activa la 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 Messages API 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 capacidad, y las URL de los webhooks se configuran tal y como se indica. Además, 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 utilizando el panel de control

Puede crear una aplicación Mensajes en la sección Panel de control.

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. Haz clic en el 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 un Account externo que quieras vincular a esta aplicación, haz clic en el 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 mensajes utilizando la API de aplicaciones

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 panel de control, abre el 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 pestaña.

También puedes 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 tiene prioridad sobre el webhook de entrada a nivel de cuenta. Si utilizas números que también están vinculados a una aplicación de Messages, comprueba el enrutamiento resultante en tu cuenta antes de basarte en ese comportamiento de prioridad.

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

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
)

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

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 opcionales y diferencias de funciones

Una vez migrados los campos SMS obligatorios, el siguiente paso es revisar los parámetros opcionales de la SMS API 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 Messages API devuelve un 202 código de respuesta para las solicitudes correctas, y 4xx o 5xx códigos para las respuestas de error.

En la tabla comparativa que figura a continuación se muestran algunos ejemplos.

Véase Messages API errores, Códigos de error de SMS API, y 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 los mensajes SMS entrantes a una URL de webhook que tú configures. Existen algunas diferencias entre ambas API en cuanto a la estructura de la carga útil entrante y la denominación de los parámetros. La configuración del webhook se explica en Configuración de tu Account de Vonage para utilizar la Messages API.

Carga útil entrante de la SMS API

Cuando se recibe un mensaje en la SMS API, Vonage envía una solicitud GET o POST a la URL del webhook de entrada que hayas configurado.

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

Cuando se recibe un mensaje en Messages API, Vonage envía una solicitud POST a la URL de entrada configurada de tu aplicación.

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 Messages API para los estados DLR de la SMS API:

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

Funcionalidades 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

La Messages API admite varios canales a través de una única interfaz API coherente. Una vez que hayas migrado tu integración de SMS, podrás añadir nuevos canales sin modificar tu 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, lo que te permite reenviar automáticamente un mensaje por un canal diferente si el primer intento es rechazado. Por ejemplo, puedes enviar un mensaje por WhatsApp y, si este es rechazado (por ejemplo, porque el destinatario no tiene WhatsApp), recurrir al SMS.

Véase Conmutación por error de la Messages API para más información.

Contenido enriquecido

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

• Imágenes, vídeos, archivos de 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 Messages API
• Detalles técnicos de la Messages API
• Conmutación por error de la Messages API