# 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.

 Note:
This tutorial provides instructions on how to send a message to a single recipient using the Conversation API. The Conversation API [batch messaging endpoint](/docs/conversation/api-reference/batch-api/), which is currently available to select customers for closed beta testing, allows you to send one message to multiple recipients at the same time. To gain access to this functionality, reach out to your account manager.

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:


```Javascript

// 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](#url)
- [The authorization method](#authorization) (optional)
- [The inclusion of your Conversation app's ID](#app-id-inclusion)
- [The recipient of the message](#recipient-construction)
- [The construction of the message itself](#message-construction)
- [The sender of the message](#sender-construction)


## 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:

Standalone SMS API

```Javascript

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

Conversation API

```Javascript

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 [<b>Overview</b> tab in the <b>Conversation API</b> section of the Sinch Build Dashboard](https://dashboard.sinch.com/convapi/overview).

 Projects
When you sign up for a Sinch account, a default [project](/docs/conversation/keyconcepts/#project) is created for you. Conversation API uses this project to group contacts and apps together. Contacts are shared across apps within the same project. Depending on your needs, you may need to create additional projects to keep contact lists separate. To create additional projects, reach out to your account manager for assistance.

## Authorization

The [Conversation API](/docs/conversation/api-reference/#authentication) 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:


```Javascript

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


```Javascript

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:


```Javascript

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 Build Dashboard](https://dashboard.sinch.com/convapi/apps).

## 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:

Standalone SMS API

```Javascript

to: [TO_NUMBER]
```

Conversation API

```Javascript

//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:


```Javascript

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](/docs/conversation/contact-management/) whenever a message is sent to a new contact. You can also [create new contacts manually](/docs/conversation/api-reference/conversation/contact/contact_createcontact). You can use Conversation API calls to [find contact ID values](/docs/conversation/api-reference/conversation/contact/) after they have been established, but the contacts will need to have been created beforehand.

### Dispatch processing mode

By default, Conversation API uses the `DISPATCH` processing mode, which handles messages without maintaining contacts and conversations.

See our page on [processing modes](/docs/conversation/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:

Standalone SMS API

```Javascript

body: 'Text message from Sinch SMS API.'
```

Conversation API

```Javascript

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.

 Note:
In addition to the documentation that exists for [Conversation API message types](/docs/conversation/message-types/), you can also use the [Message Composer](https://community.sinch.com/t5/Conversation-API/How-do-I-use-Message-Composer-to-create-omni-channel-message/ta-p/9890) on the [Sinch Build Dashboard](https://dashboard.sinch.com/convapi/message-composer) to help you construct Conversation API messages. You can use the **Code** editor to create template content using code samples, or you can use the **Form** or **Visual** editors to compose a message and then extract the snippet from the **Code** editor. This snippet can then be used to populate the message field of non-template messages.

## 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:

Standalone SMS API

```Javascript

from: SINCH_NUMBER
```

Conversation API

```Javascript

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.

Note:
`SMS_SENDER` is a Conversation API [SMS channel property](/docs/conversation/channel-support/sms/properties/), and its inclusion is optional. If not included, a default number is used (if specified).

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.