Send message request transformation tutorial

When migrating away from the standalone WhatsApp 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 WhatsApp 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:

import fetch from 'node-fetch';

var BOT_ID = 'your-received-bot-id';
var RECIPIENT_NUMBER = 'your-phone-number-which-is-whatsapp-enabled';
var BEARER_TOKEN = 'your-received-bearer-token';

var url = 'https://us1.whatsapp.api.sinch.com/whatsapp/v1/' + BOT_ID + '/messages';
var data = {
  to: [RECIPIENT_NUMBER],
  message: {
    type: 'text',
    text: 'Greetings from Sinch'
  }
};

var postReq = {
  method: "POST",
  headers: {
    'Authorization': 'Bearer ' + BEARER_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data),
  json: true
};

fetch(url, postReq)
  .then(data => {
    return data.json()
  })
  .then(res => {
    console.log(res)
  })
  .catch(error => console.log(error));

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

import fetch from 'node-fetch';

const APP_ID = '';
const ACCESS_KEY = '';
const ACCESS_SECRET = '';
const PROJECT_ID = '';
const CHANNEL = 'WHATSAPP';
const IDENTITY = '';

var url = 'https://us.conversation.api.sinch.com/v1/projects/' + PROJECT_ID + '/messages:send';
var data = {
  app_id: APP_ID,
  recipient: {
    identified_by: {
      channel_identities: [{
        channel: CHANNEL,
        identity: IDENTITY
      }]
    }
  },
  message: {
    text_message: {
      text: 'Text message from Sinch Conversation API.'
    }
  }
};

var postReq = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Basic ' + Buffer.from(ACCESS_KEY + ':' + ACCESS_SECRET).toString('base64')
  },
  body: JSON.stringify(data),
  json: true
}

fetch(url, postReq)
  .then(data => {
    return data.json()
  })
  .then(res => {
    console.log(res)
  })
  .catch(error => console.log(error));

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 WhatsApp 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

URL

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

var url = 'https://us1.whatsapp.api.sinch.com/whatsapp/v1/' + BOT_ID + '/messages';

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 us1 to eu1 in the standalone WhatsApp URL, and us to eu in the Conversation API URL.

The Sender Identity to be used when sending WhatsApp messages is set when you configure the WhatsApp channel of your Conversation API app (if you have not yet created a Conversation API app, see this migration guide's Getting Started page).

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

Authorization

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

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

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

App ID inclusion

When updating a standalone WhatsApp 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 WhatsApp API send message request to a Converation API send message request, you'll need to update the way you identify your recipient:

to: [RECIPIENT_NUMBER]

//Remember that CHANNEL is set to WHATSAPP.
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 WhatsApp API. This is because the Conversation API can be used to send messages to contacts over multiple channels, and those channels can identify recipients in different ways. 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 WHATSAPP. The RECIPIENT_NUMBER variable in the standalone WhatsApp 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.

Message construction

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

message: {
  type: 'text',
  text: 'Greetings from Sinch'
}

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

For text messages, the construction is very similar. Instead of specifying type: 'text' (as you would in the standalone WhatsApp API), you include a text_message object under the message object when making a call to the Conversation API. In both the standalone WhatsApp API case and the Conversation API case, you specify the body of the text message by populating the text field.

Other message types will contain different fields and objects for both the standalone WhatsApp API and the Conversation API. See this migration guide's reference material for a full mapping of message types, objects, and fields between the standalone WhatsApp API and the Conversation API.