Getting Started with the Messages API

This page will walk you through all of the necessary steps to get up and running with the Vonage Messages API. The Messages API provides a simple way to send messages to your customers through multiple popular channels - SMS, MMS, RCS, WhatsApp, Facebook, and Viber. Instead of integrating with each platform separately, you can connect once and manage all conversations in one place.

To begin, follow this guide to create your account and application. Then, navigate to the getting started guide for your chosen channels to complete your onboarding.

Prerequisites

Before sending your first message, you'll need to create a Vonage account and application:

Create a Vonage account

To create your free Vonage account:

  1. In your browser, navigate to Dashboard.
  2. Add your company information and click Sign up. Vonage sends a PIN to your phone as a text message or automated phone call. The timeout for each verification attempt is 5 minutes.
    Note: you can associate a phone number with one account only. If your phone number is already associated with a Vonage account you should remove that phone number from the existing account.
  3. In Phone number verification, enter the PIN sent to you by Vonage and click Verify. You are logged into Dashboard and shown how to start developing with Vonage. This page is displayed each time you login until you have made your first successful call with Vonage APIs.

When you create your Vonage account you are given €2 free test credit and your account is set in DEMO mode. You can use our products to send messages to up to 10 destination numbers, a message stating that the account is in demo mode is added to all the SMS you send. To move out of the demo mode add credit to your account.

For very few countries Vonage cannot create an account for you automatically. This is because of payment restrictions or legal trading restrictions for a US registered company.

Create a Vonage API Application

There are two alternative methods for creating a Messages application:

  1. Using the Vonage CLI
  2. Using the Dashboard

Each of these methods is described in the following sections.

How to create a Messages application using the Vonage CLI

To create your application using the Vonage CLI, enter the following command into the shell:

vonage apps:create "My Messages App" --messages_inbound_url=https://example.com/webhooks/inbound-message --messages_status_url=https://example.com/webhooks/message-status

This creates a Vonage API application with a messages capability, with the webhook URLs configured as specified, and generate a private key file my_messages_app.key and creates or updates the vonage_app.json file.

How to create a Messages application using the Dashboard

You can create Messages application in the Dashboard.

To create your application using the Dashboard:

  1. Under Applications in the Dashboard, click the Create a new application button.

  2. Under Name, enter the Application name. Choose a name for ease of future reference.

  3. Click the button Generate public and private key. This will create a public/private key pair and the private key will be downloaded by your browser.

  4. Under Capabilities select the Messages button.

  5. In the Inbound URL box, enter the URL for your inbound message webhook, for example, https://example.com/webhooks/inbound-message.

  6. In the Status URL box, enter the URL for your message status webhook, for example, https://example.com/webhooks/message-status.

  7. Click the Generate new application button. You are now taken to the next step of the Create Application procedure where you can link a Vonage API number to the application, and link external accounts such as Facebook to this application.

  8. If there is an external account you want to link this application to, click the Linked external accounts tab, and then click the corresponding Link button for the account you want to link to.

You have now created your application.

NOTE: Before testing your application ensure that your webhooks are configured and your webhook server is running.

Channel specific Getting started sections