Send a Conversation message

Learn how to set up and send a message with SMS and Conversation API in a Node.js application.

Conversation API allows you to send messages to any channel you have configured, but for the purposes of this guide, we will set up an SMS channel.

In this guide you will learn how to:

Learn how to:
  1. Sign up for your free Sinch account
  2. Buy a number
  3. Create and set up a channel
  4. Set up your Node.js application
  5. Send your first Conversation message

What you need to know before you start

Before you can get started, you need the following already set up:

  • Node.js and a familiarity with how to create a new app.

Sign up for your free account

Already have an account?

If you already have a free account, skip to the next section

You can sign up for a free Sinch account here.

  • When you sign up, you'll have to verify your email address and phone number. This lets Sinch verify your identity and you'll also be able to use your phone to send and receive test messages.
  • After you've verified your number, you'll be asked some questions in order to get you started in a way that's relevent to you.
  • After you finish setting up your account, you'll have access to your dashboard where you can view all of your projects and applications. You can also access your account ID, set up API tokens, get phone numbers, and more.
  • Once your account is created, you need to add a new REST API in order to send SMS Messages. Click Add New REST API and your new service plan and ID token will be created. Take note of them, because you'll use them later.

Buy a number

Already have an number?

If you already have sinch number, skip to the next section

You can get numbers that are set up for SMS, Voice, or both. You can buy a number from any country where Sinch has numbers in inventory. Countries with numbers available for purchase are marked with Direct Access. All other countries will require you to submit a request to Sinch for manual handling.

You can search for and purchase virtual numbers by logging in to your dashboard.

  1. Go to Numbers | Get virtual numbers, fill in the required information, and click SEARCH. If you don't want to specify anything about the number, choose your country and click SEARCH. Available numbers to buy are displayed in the list.

  2. When you see a number you want to buy, click GET next to the number to buy it.

  3. You can configure your number with an SMS, Voice or Campaign ID (only for 10DLC numbers) when you activate the number.

    When you get a virtual number, if supporting documentation is needed, you will see a message in an orange box at the bottom of your form. You won't be able to get a virtual number until supporting documentation is submitted. Click here to learn more about supporting documentation.

Create an app

To create a new Conversations App, sign in to your Sinch Dashboard account and use the menu on the left to access Conversations > Apps.

Click the New App button on the right, name your App, choose an appropriate region for it, and click Create.

Set up a channel

In your Sinch Dashboard, navigate to Conversations > Apps. Click the name of the app to which you want to add the SMS Channel.

Under "Set up channels" find SMS channel and click Set Up Channel.

For setting up the SMS channel, you need to choose your SMS Service Plan ID from the drop-down and click Save.

Get your oAuth2 token

Conversation API uses an oAuth2 token for authentication. You will need an access token in order to send messages.

Go to the Access Keys page and create a new key by clicking the New Key button.

Important!

Be sure to copy and store the Key Secret you will get. You won't be able to retrieve it again once you’ve created the key.

Use the key_id and key_secret to obtain an access token by executing the following curl command:

curl https://auth.sinch.com/oauth2/token -d grant_type=client_credentials --user <key_id>:<key_secret>

Copy the token and set it aside, because you'll use it in the next steps.

Set up your Node.js application

Create a new node app with npm.

npm init

Accept the defaults for the application.

Add the fetch package with npm to generate the necessary dependencies.

npm install 'node-fetch'

Create your file

Create a new file named index.js in the project and paste the provided "Send a Conversation text message" code into the file. This code sends a text message generic message type using the SMS channel.

Send a Conversation text message

// Find your App ID at dashboard.sinch.com/convapi/apps
// Find your Project ID at dashboard.sinch.com/settings/project-management
// Find your Sinch numbers at dashboard.sinch.com/numbers/your-numbers/numbers
const APP_ID = '';
const ACCESS_TOKEN = '';
const PROJECT_ID = '';
const TO_NUMBER = '';

const fetch = require('node-fetch');

const sendMessage = {
  app_id: APP_ID,
  recipient: {
    identified_by: {
      channel_identities: [
      {
        channel: "SMS",
        identity: TO_NUMBER
      } 
      ]
    }
  },
  message: {
    text_message: {
     text: "Text message from Sinch Conversation API."
    }
  }
};

fetch('https://us.conversation.api.sinch.com/v1/projects/' + PROJECT_ID + '/messages:send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + ACCESS_TOKEN,
  },
  body: JSON.stringify(sendMessage),
})
  .then((res) => res.json())
  .then((json) => console.log(json));

Fill in your parameters

Assign your values to the following parameters:

ParameterYour value
APP_IDThe app ID found on your Sinch dashboard.
ACCESS_TOKENThe access token generated in the oAuth2 step.
PROJECT_IDThe project ID found on your Sinch dashboard.
TO_NUMBERThe phone number to which you want to send the test SMS message.

Save the file.

Send your first Conversation message

Now you can execute the code and send your test Conversation message. Run the following command:

node index.js

You should receive a text message.

Next steps

The code you used in the index.js file sends a POST request to the Sinch Conversation API /messages:send endpoint to send the Conversation message. Click here to read more about the messages endpoint.

Send a Conversation text message

// Find your App ID at dashboard.sinch.com/convapi/apps
// Find your Project ID at dashboard.sinch.com/settings/project-management
// Find your Sinch numbers at dashboard.sinch.com/numbers/your-numbers/numbers
const APP_ID = '';
const ACCESS_TOKEN = '';
const PROJECT_ID = '';
const TO_NUMBER = '';

const fetch = require('node-fetch');

const sendMessage = {
  app_id: APP_ID,
  recipient: {
    identified_by: {
      channel_identities: [
      {
        channel: "SMS",
        identity: TO_NUMBER
      } 
      ]
    }
  },
  message: {
    text_message: {
     text: "Text message from Sinch Conversation API."
    }
  }
};

fetch('https://us.conversation.api.sinch.com/v1/projects/' + PROJECT_ID + '/messages:send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + ACCESS_TOKEN,
  },
  body: JSON.stringify(sendMessage),
})
  .then((res) => res.json())
  .then((json) => console.log(json));