Conversation Applications via Bundles

To create Conversation Applications via Bundles, you can either just send boolean true, or specify the name of the Conversation Application together with some optional parameters.

Conversation Applications can be added together with subprojects, and an SMS 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.

Creating a Conversation Application using boolean

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',
        convApp: true,
    })
  );

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

If set to true, a Conversation 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 Conversation Application will not be created.

Creating a Conversation Application with custom name

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',
        convApp: {
          name: 'Conversation Application name',
        },
    })
  );

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

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

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

Creating a Conversation Application with custom parameters

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',
        convApp: {
          name: 'Conversation Application name',
          webhooks: [
            {
              target: 'https://webhook.site/d614d077-302a-4e0b-a06a-276923f7d8d4',
              secret: 'secret',
              triggers: [
                'MESSAGE_DELIVERY'
              ]
            }
          ],
          processingMode: 'DISPATCH',
          retentionPolicy: {
            retentionPolicyType: 'MESSAGE_EXPIRE_POLICY',
            ttl: 7
          }
        },
      });
    }
  );

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

An Conversation Application will be created under the project or subproject specified, with given name and with custom parameters.

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

Conversation Application response

The bundle response includes a convApp object with the following fields:

Field	Type	Description
`id`	`string`	Unique identifier of the Conversation Application
`name`	`string`	Name of the Conversation Application
`webhooks`	`array \| undefined`	Webhooks configured for the application
`processingMode`	`string`	One of `CONVERSATION`, `DISPATCH`, `UNRECOGNIZED`, `UNSPECIFIED`
`retentionPolicy`	`object \| undefined`	Message and conversation retention settings
`consentManagerSettings`	`object \| undefined`	Consent manager settings
`smsChannelStatus`	`string \| undefined`	Integration status of the SMS channel credential. One of `PENDING`, `ACTIVE`, `FAILING`, `UNRECOGNIZED`

The smsChannelStatus field reflects whether the SMS channel has been successfully linked to the Conversation Application. When a bundle creates or links an SMS App, this status begins as PENDING and transitions to ACTIVE once the connection is established. A FAILING status indicates the channel credential could not be verified — for example, due to a suspended SMS service (e.g. a credit block).