Send SMS tutorial

In this tutorial, you will create a simple application that sends a message from a GoToConnect phone number to another phone number. For example, a dental clinic might want to send a reminder to their patients before their appointment. To achieve this, you will use the GoTo Messaging REST API and Node.js (but any programming language would do).

At a high level, you will complete the following steps:

1. Install any required software and set up a test phone number.
2. Obtain an access token to get the authorization to send a message.
3. Set up a demo application for sending messages.
4. Send a test message using your demo app.

You can follow along or read the completed project.

Prerequisites

1. Install Node.js (version equal to or greater than 16.14.2).
2. Obtain a phone number to receive messages (for example, your personal phone).
3. Obtain GoTo Phone number with SMS permissions to send messages from:
   1. Make sure that phone number is assigned to you in GoTo Admin under "Phone system > Phone numbers".

Obtain access token for authorization

Since you want to send a message, you should first have a look at this useful snippet from the API documentation for "GoToConnect > Message > Send a message" request. It tells you the following: to have the authorization to send a message, you need a bearer token (access token) with the messaging.v1.send OAuth scope:

When making API requests to a GoTo server, your application needs to prove that it has the required permissions to access GoTo data hosted on the GoTo server. GoTo servers use the OAuth 2.0 protocol to give applications access to protected data. How can you obtain access permissions?

1. Create an OAuth client for your application. Your client will get a client ID and a client secret.
2. When making an API request, your application will identify itself using the client ID and secret. The GoTo authentication service will validate the client ID and secret, and on successful validation return an access token. The access token can then be used in subsequent API requests, acting as proof that your application has permissions to access GoTo data.

To obtain an access token using the OAuth scope messaging.v1.send, follow the instructions in the "How to obtain an OAuth access token (in Node.js)" tutorial. When you have completed the tutorial, you will have a Node.js project and an accessToken variable required for the next step.

Set up demo application to send SMS message

Now, you need to send a request to the API endpoint with the right headers and parameters. Luckily, the documentation provides request samples in various languages for each endpoint.

Note: The following image serves as illustration only and the actual request sample that you will be using may be different.

1. Install the Axios HTTP client:

   npm install axios

2. Go to the "Send a message" API documentation, copy the "Node + Axios" request sample, then paste it in the app.js file that you created when obtaining the access token.
3. Replace the request parameters with your own values. They are fully documented in the "Send a message" API documentation, but here's a summary:
   1. Bearer token: The access token you have previously obtained.
   2. ownerPhoneNumber: The GoTo phone number you will send the message from.
   3. contactPhoneNumbers: A list of phone numbers that you will send the message to.
   4. body: The content of the message.
   5. userKey: You can omit this because you will send the message from the user of the bearer token.

 var express = require("express");
+var axios = require("axios").default;

 // ...

 app.get('/login/oauth2/code/goto', async function (req, res) {
     // ...
     var accessToken = tokenResponse.token.access_token;
+    var options = {
+        method: 'POST',
+        url: 'https://api.goto.com/messaging/v1/messages',
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            'content-type': 'application/json'
+        },
+        data: {
+            ownerPhoneNumber: '+15145550100',
+            contactPhoneNumbers: ['+15145550199'],
+            body: 'Congratulations! You have successfully completed the tutorial!'
+        }
+    };
+
+    axios.request(options).then(function (response) {
+        console.log(response.data);
+    }).catch(function (error) {
+        console.error(error);
+    });
 });

Send SMS message: demo

1. Run the application:

   node app.js

2. Open the displayed authentication link in a browser.

Once the message is sent successfully, you should see the following message on your phone:

Meanwhile, the response body will be returned in the terminal. The "id" field is the ID of the message that you just sent -- we can use it to retrieve the message.

As a next exercise, you could try to get the message that you just sent using its ID.

Tips for the get message exercise:

1. You will need to modify your OAuth client scope by adding messaging.v1.read in the GoToConnect scopes.
2. Don't forget to change the scope in the app.js file.
3. You should use a valid message ID to retrieve a message. For example, you can use the message ID that you got from the previous exercise.

Trial request

If you do not have a test PBX, please request access by contacting sales here. An SMS limit may apply.