Skip to navigation

Send an SMS

In this code snippet you will see how to send an SMS using the Messages API.

For a step-by-step guide to this topic, you can read our tutorial Sending SMS messages with the Messages API.

Delivery receipts

The webhook used for the delivery receipt will depend on the type of authentication used:

Authentication type used Webhook used for delivery receipt
Basic Auth account-level webhook is used for delivery receipt.
JWT Auth application-level webhook is used for delivery receipt / status.

Reception of delivery receipts depends on availability of network support.

Example

Find the description for all variables used in each code snippet below:

Key Description
VONAGE_APPLICATION_ID The Vonage Application ID.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Private key path.
VONAGE_PRIVATE_KEY_PATH Private key path.
VONAGE_FROM_NUMBER Refer to FROM_NUMBER above
VONAGE_BRAND_NAME The alphanumeric string that represents the name or number of the organization sending the message.
FROM_NUMBER The phone number you are sending the message from.
TO_NUMBER The phone number you are sending the message to.

NOTE: Don't use a leading + or 00 when entering a phone number, start with the country code, for example 447700900000.

  • cURL
  • Node.js
  • Java
  • Dotnet
  • Python
  • Ruby

    • Prerequisites

    If you do not have an application you can create one. Make sure you also configure your webhooks.

    Write the code

    Add the following to send-sms.sh:

    curl -X POST https://api.nexmo.com/v1/messages \
  -H 'Authorization: Bearer '$JWT\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d $'{
          "message_type": "text",
          "text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
          "to": "$TO_NUMBER",
          "from": "$FROM_NUMBER",
          "channel": "sms"
}'

    View full source

    Run your code

    Save this file to your machine and run it: 

    bash send-sms.sh

    Prerequisites

    If you do not have an application you can create one. Make sure you also configure your webhooks. 

    npm install @vonage/server-sdk

    Create a file named send-sms.js and add the following code:

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

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET,
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH
})

    View full source

    Write the code

    Add the following to send-sms.js:

    vonage.messages.send(
  new SMS("This is an SMS text message sent using the Messages API", TO_NUMBER, FROM_NUMBER)
)
  .then(resp => console.log(resp.message_uuid))
  .catch(err => console.error(err));

    View full source

    Run your code

    Save this file to your machine and run it: 

    node send-sms.js

    Prerequisites

    If you do not have an application you can create one. Make sure you also configure your webhooks.

    Add the following to `build.gradle`:

    compile 'com.vonage:client:6.2.0'

    Create a class named SendSmsText and add the following code to the main method:

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

MessagesClient messagesClient = client.getMessagesClient();

    View full source

    Write the code

    Add the following to the main method of the SendSmsText class:

    var message = SmsTextRequest.builder()
        .from(FROM_NUMBER).to(TO_NUMBER)
        .text("Hello from Vonage!")
        .build();

try {
    MessageResponse response = messagesClient.sendMessage(message);
    System.out.println("Message sent successfully. ID: "+response.getMessageUuid());
}
catch (MessageResponseException mrx) {
    switch (mrx.getStatusCode()) {
        default: throw mrx;
        case 401: // Bad credentials
            throw new IllegalStateException(mrx.getTitle(), mrx);
        case 422: // Invalid
            throw new IllegalStateException(mrx.getDetail(), mrx);
        case 402: // Low balance
            client.getAccountClient().topUp("transactionID");
            break;
        case 429: // Rate limit
            Thread.sleep(12_000);
            break;
    }
}

    View full source

    Run your code

    We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:

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

    Run the following gradle command to execute your application, replacing com.vonage.quickstart.messages.sms with the package containing SendSmsText:

    gradle run -Pmain=com.vonage.quickstart.messages.sms.SendSmsText

    Prerequisites

    If you do not have an application you can create one. Make sure you also configure your webhooks. 

    Install-Package Vonage

    Write the code

    Add the following to SendSms.cs:

    var credentials = Credentials.FromAppIdAndPrivateKeyPath(appId, privateKeyPath);

var vonageClient = new VonageClient(credentials);

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

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

    View full source

    Prerequisites

    If you do not have an application you can create one. Make sure you also configure your webhooks. 

    pip install vonage

    Write the code

    Add the following to send_sms.py:

    client = vonage.Client(
    application_id=VONAGE_APPLICATION_ID,
    private_key=VONAGE_APPLICATION_PRIVATE_KEY_PATH,
)

client.messages.send_message(
    {
        "channel": "sms",
        "message_type": "text",
        "to": TO_NUMBER,
        "from": VONAGE_BRAND_NAME,
        "text": "This is an SMS sent using the Vonage Messages API",
    }
)

    View full source

    Run your code

    Save this file to your machine and run it: 

    python3 send_sms.py

    Prerequisites

    If you do not have an application you can create one. Make sure you also configure your webhooks. 

    gem install vonage

    Write the code

    Add the following to send-mms.rb:

    client = Vonage::Client.new(
  application_id: VONAGE_APPLICATION_ID,
  private_key: File.read(VONAGE_APPLICATION_PRIVATE_KEY_PATH)
)

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

client.messaging.send(
  from: VONAGE_FROM_NUMBER,
  to: TO_NUMBER,
  **message
)

    View full source

    Run your code

    Save this file to your machine and run it: 

    ruby send-mms.rb

    Try it out

    When you run the code a message is sent to the destination number.

    Improve this page