SMS Applications via Bundles

To create SMS Applications via Bundles, you can either just send boolean true, or specify the name of the SMS Application.

SMS Applications can be added together with subprojects, and a Conversation Application, in which case the application(s) will be associated to the subproject.

Note that, for this guide, we provide node.js code samples. However, the principles apply to any language you use to make requests to the API.

The following code sample creates a subproject using the Provisioning API Bundles:

import fetch from 'node-fetch';

async function createSubproject() {
  const resp = await fetch(
    `https://provisioning.api.sinch.com/v1/projects/${PROJECT_ID}/bundles`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization:
          'Basic ' +
          Buffer.from(ACCESS_KEY + ':' + ACCESS_SECRET).toString('base64'),
      },
      body: JSON.stringify({
        name: 'Small bundle example',
        region: 'US',
        smsApp: true,
      })
    }  
  );

  const data = await resp.json();
  return data;
}

If set to true, an SMS Application will be created under the project or subproject specified, with the name of the root object. If neither this value or the name in the root is set, then the request will fail.

If set to false or left undefined, a SMS Application will not be created.

The following code sample creates a subproject using the Provisioning API Bundles:

import fetch from 'node-fetch';

async function createSubproject() {
  const resp = await fetch(
    `https://provisioning.api.sinch.com/v1/projects/${PROJECT_ID}/bundles`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization:
          'Basic ' +
          Buffer.from(ACCESS_KEY + ':' + ACCESS_SECRET).toString('base64'),
      },
      body: JSON.stringify({
        name: 'Small bundle example',
        region: 'US',
        smsApp: {
          name: 'SMS Application name',
        },
      })
    }  
  );

  const data = await resp.json();
  return data;
}

An SMS Application will be created under the project or subproject specified, with given name.

If set to false or left undefined, a SMS Application will not be created.

If you already have an SMS Application and want to link it to a new Conversation Application via a bundle, provide the SMS App ID:

import fetch from 'node-fetch';

async function linkExistingSmsApp() {
  const resp = await fetch(
    `https://provisioning.api.sinch.com/v1/projects/${PROJECT_ID}/bundles`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization:
          'Basic ' +
          Buffer.from(ACCESS_KEY + ':' + ACCESS_SECRET).toString('base64'),
      },
      body: JSON.stringify({
        name: 'Link existing SMS app',
        region: 'EU',
        smsApp: {
          smsAppId: 'your-existing-sms-app-id',
        },
        convApp: true,
      }),
    }
  );

  const data = await resp.json();
  return data;
}

The bundle creation process is asynchronous. The response is returned immediately with the bundle's current state:

Once the bundle is created, the following happens behind the scenes:

1. The Conversation Application is created (or retrieved if you linked an existing one)
2. The SMS Application is created (or retrieved if you linked an existing one)
3. The SMS channel credentials are added to the Conversation Application
4. The channel activation occurs asynchronously — the smsChannelStatus on the Conversation App transitions from PENDING to ACTIVE

You can poll the bundle endpoint (GET /v1/projects/:projectId/bundles/:bundleId) to check the current state.

The following errors may be returned during bundle creation with an SMS Application: