Send message request transformation tutorial

When migrating away from the standalone SMS API, you must update your requests to use the Conversation API. One of the most common requests made in either API is a send message request. This tutorial instructs you on how to transform a request to send a text message using the standalone SMS API into a request to send a text message using the Conversation API.

Below are an example of each request. Note that, for this guide, we are using node.js, though the principles apply to any language you use to make requests to the API:

// Find your Service Plan ID and API Token at dashboard.sinch.com/sms/api/rest
// Find your Sinch numbers at dashboard.sinch.com/numbers/your-numbers/numbers
const SERVICE_PLAN_ID = 'YOUR_servicePlanId';
const API_TOKEN = 'YOUR_API_token';
const SINCH_NUMBER = 'YOUR_Sinch_virtual_number';
const TO_NUMBER = 'sender_number';

import fetch from 'node-fetch';

async function run() {
  const resp = await fetch(
    'https://us.sms.api.sinch.com/xms/v1/' + SERVICE_PLAN_ID + '/batches',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer ' + API_TOKEN
      },
      body: JSON.stringify({
        from: SINCH_NUMBER,
        to: [TO_NUMBER],
        body: 'Text message from Sinch SMS API.'
      })
    }
  );

  const data = await resp.json();
  console.log(data);
}

run();

// Find your App ID at dashboard.sinch.com/convapi/apps
// Find your Project ID at dashboard.sinch.com/settings/project-management
// Get your Access Key and Access Secret at dashboard.sinch.com/settings/access-keys
const APP_ID = '';
const ACCESS_KEY = '';
const ACCESS_SECRET = '';
const PROJECT_ID = '';
const CHANNEL = 'SMS';
const IDENTITY = '';
const SINCH_NUMBER = 'YOUR_virtual_number'

import fetch from 'node-fetch';

async function run() {
  const resp = await fetch(
    'https://us.conversation.api.sinch.com/v1/projects/' + PROJECT_ID + '/messages:send',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Basic ' + Buffer.from(ACCESS_KEY + ':' + ACCESS_SECRET).toString('base64')
      },
      body: JSON.stringify({
        app_id: APP_ID,
        recipient: {
          identified_by: {
            channel_identities: [
              {
                channel: CHANNEL,
                identity: IDENTITY
              }
            ]
          }
        },
        message: {
          text_message: {
            text: 'Text message from Sinch Conversation API.'
          }
        },
        channel_properties: {
          SMS_SENDER: SINCH_NUMBER
        }
      })
    }
  );

  const data = await resp.json();
  console.log(data);
}

run();

As demonstrated in the above code samples, there are several sections that need to be updated when you are transforming a send message request for the standalone SMS API to a send message request for the Conversation API. They are:

• The endpoint URL
• The authorization method (optional)
• The inclusion of your Conversation app's ID
• The recipient of the message
• The construction of the message itself
• The sender of the message

URL

When updating a standalone SMS API send message request to a Converation API send message request, you'll need to update the endpoint URL:

'https://us.sms.api.sinch.com/xms/v1/' + SERVICE_PLAN_ID + '/batches';

var url = 'https://us.conversation.api.sinch.com/v1/projects/' + PROJECT_ID + '/messages:send';

Each of the above URL snippets is configured for the US region. To switch to the EU servers, simply update us to eu in the standalone SMS URL, and us to eu in the Conversation API URL.

Also note that, for the Conversation API URL, you'll no longer need to include your SERVICE_PLAN_ID. Instead, you'll need to include your PROJECT_ID, which can be found on the Overview tab in the Conversation API section of the Sinch Customer Dashboard.

Authorization

The Conversation API supports Basic authentication in addition to Access Token authentication. Therefore, when updating a standalone SMS API send message request to a Converation API send message request, you may update the authorization method used in your request:

headers: {
  'Content-Type': 'application/json',
  Authorization: 'Bearer ' + API_TOKEN
}

headers: {
  'Content-Type': 'application/json',
  Authorization: 'Basic ' + Buffer.from(ACCESS_KEY + ':' + ACCESS_SECRET).toString('base64')
}

App ID inclusion

When updating a standalone SMS API send message request to a Converation API send message request, you'll need to include your Conversation app's ID in the request:

app_id: APP_ID

This is a required field in any send message request made to the Conversation API. Your app's ID is displayed in the APP ID column of the Apps section on the Conversation apps page of the Sinch Customer Dashboard.

Recipient construction

When updating a standalone SMS API send message request to a Converation API send message request, you'll need to update the way you identify your recipient:

to: [TO_NUMBER]

//Remember that CHANNEL is set to SMS.
recipient: {
  identified_by: {
    channel_identities: [{
      channel: CHANNEL,
      identity: IDENTITY
    }]
  }
}

The recipient object used by the Conversation API can be a bit more complex than the to field used in the standalone SMS API. This is because the Conversation API can be used to send messages to contacts over multiple channels. In the above example, we use channel_identities, which are pairs of data that include a channel and a unique identifier, to specify the intended recipient.

In this case, the CHANNEL variable is set to SMS. The to variable in the standalone SMS call and the IDENTITY variable in the Conversation API call will be the phone number of your intended recipient.

Contact IDs

Another way to specify contacts in the Conversation API is through the use of contact IDs:

recipient: {
  contact_id: 'RECIPIENT_contact_ID'
}

When using this method, you do not need to provide channel identity pairs. However, you must know the contact ID of your intended recipient. This contact ID is a unique identifier that is generated by the Conversation API whenever a message is sent to a new contact. You can also create new contacts manually. You can use Conversation API calls to find contact ID values after they have been established, but the contacts will need to have been created beforehand.

Dispatch processing mode

By default, Conversation API always associates new messages with a Contact and a Conversation. If there's no existing contact or active conversation, new ones are created. This is the CONVERSATION mode intended to be used by the majority of apps.

This behavior may not be desired for use cases in which contacts and conversations are not leveraged, mainly unidirectional SMS campaigns. Such use cases may find the DISPATCH processing mode more attractive in order to prevent storage of unused information. Dispatch mode aims to address this necessity by handling messages without maintaining contacts and conversations.

See our page on processing modes for more information.

Message construction

When updating a standalone SMS API send message request to a Converation API send message request, you'll need to update the way your messages are constructed:

body: 'Text message from Sinch SMS API.'

message: {
  text_message: {
    text: 'Text message from Sinch Conversation API.'
  }
}

For text messages, the construction is very similar. However, instead of just specifying the body field (as you do in the standalone SMS API), you include a text_message object under the message object when making a call to the Conversation API. Then, you specify the actual text of the message in the the text field.

Other message types will contain different fields and objects for both the standalone SMS API and the Conversation API.

Sender construction

When updating a standalone SMS API send message request to a Converation API send message request, you'll need to update the way you identify yourself in the request:

from: SINCH_NUMBER

channel_properties: {
  SMS_SENDER: SINCH_NUMBER
}

The SMS_SENDER object used by the Conversation API can be a bit more complex than the from field used in the standalone SMS API.

It is contained within the channel_properties object, which is on the same level as the message object in the Conversation API send message request. In both the case of the from field and the SMS_SENDER field, the corresponding value is your Sinch virtual number.