Download OpenAPI specification:Download

App

Apps are created and configured through the Sinch Dashboard, are tied to the API user and come with a set of channel credentials for each underlying connected channel. The app has a list of conversations between itself and different contacts which share the same project.

Webhooks, which the app is attached to, defines the destination for various events coming from the Conversation API. An app has the following configurable properties:

Field Description
Display name The name visible in the Sinch Dashboard.
Conversation metadata report Specifies the amount of conversationmetadata that's returned as part of each callback.
Retention Policy The retention policy specifies how long messages, sent to or from an app, are stored by the Conversation API.

List all apps for a given project

Get a list of all apps in the specified project.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Conversation API app)

List of apps belonging to a specific project ID.

Array
Array of objects (Channel Credential)

An array of channel credentials. The order of the credentials defines the app channel priority.

conversation_metadata_report_view
string (ConversationMetadataReportView)
Enum: "NONE" "FULL"
display_name
string

The display name for the app.

id
string

The ID of the app. You can find this on the Sinch Dashboard.

object (RateLimits)
object (RetentionPolicy)

The retention policy configured for the app. For more information about retention policies, see Retention Policy.

object (DispatchRetentionPolicy)

The retention policy configured for messages in Dispatch Mode. Currently only MESSAGE_EXPIRE_POLICY is available. For more information about retention policies, see Retention Policy.

processing_mode
string (ProcessingMode)

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Enum: Description
CONVERSATION

The default Processing Mode. Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

Does not associate messages with contacts and conversations. This processing mode is mostly intended for unidirectional high volume SMS use cases. The lack of contacts and conversations limits some API features as related data won't be queryable in the Contact and Conversation APIs.

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

get/v1/projects/{project_id}/apps
Request samples
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/apps`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

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

run();
Response samples
application/json
{
  • "apps": [
    • {
      }
    ]
}

Create an app

You can create a new Conversation API app using the API. You can create an app for one or more channels at once. The ID of the app is generated at creation and will be returned in the response.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

Request Body schema: application/json

The app to create.

display_name
required
string

The display name for the app.

required
Array of objects (Channel Credential)

An array of channel credentials. The order of the credentials defines the app channel priority.

conversation_metadata_report_view
string (ConversationMetadataReportView)
Enum: "NONE" "FULL"
object (RetentionPolicy)

The retention policy configured for the app. For more information about retention policies, see Retention Policy.

object (DispatchRetentionPolicy)

The retention policy configured for messages in Dispatch Mode. Currently only MESSAGE_EXPIRE_POLICY is available. For more information about retention policies, see Retention Policy.

processing_mode
string (ProcessingMode)

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Enum: Description
CONVERSATION

The default Processing Mode. Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

Does not associate messages with contacts and conversations. This processing mode is mostly intended for unidirectional high volume SMS use cases. The lack of contacts and conversations limits some API features as related data won't be queryable in the Contact and Conversation APIs.

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Channel Credential)

An array of channel credentials. The order of the credentials defines the app channel priority.

conversation_metadata_report_view
string (ConversationMetadataReportView)
Enum: "NONE" "FULL"
display_name
string

The display name for the app.

id
string

The ID of the app. You can find this on the Sinch Dashboard.

object (RateLimits)
object (RetentionPolicy)

The retention policy configured for the app. For more information about retention policies, see Retention Policy.

object (DispatchRetentionPolicy)

The retention policy configured for messages in Dispatch Mode. Currently only MESSAGE_EXPIRE_POLICY is available. For more information about retention policies, see Retention Policy.

processing_mode
string (ProcessingMode)

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Enum: Description
CONVERSATION

The default Processing Mode. Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

Does not associate messages with contacts and conversations. This processing mode is mostly intended for unidirectional high volume SMS use cases. The lack of contacts and conversations limits some API features as related data won't be queryable in the Contact and Conversation APIs.

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

post/v1/projects/{project_id}/apps
Request samples
application/json
{
  • "channel_credentials": [
    • {
      }
    ],
  • "display_name": "Demo Facebook App"
}
Response samples
application/json
{
  • "channel_credentials": [
    • {
      }
    ],
  • "conversation_metadata_report_view": "NONE",
  • "display_name": "Sinch Conversation API Demo App 001",
  • "id": "{APP_ID}",
  • "rate_limits": {
    • "inbound": 0,
    • "outbound": 0,
    • "webhooks": 0
    },
  • "retention_policy": {
    • "retention_type": "MESSAGE_EXPIRE_POLICY",
    • "ttl_days": 180
    },
  • "dispatch_retention_policy": {
    • "retention_type": "MESSAGE_EXPIRE_POLICY",
    • "ttl_days": 0
    },
  • "processing_mode": "CONVERSATION"
}

Get an app

Returns a particular app as specified by the App ID.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

app_id
required
string

The unique ID of the app. You can find this on the Sinch Dashboard.

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Channel Credential)

An array of channel credentials. The order of the credentials defines the app channel priority.

conversation_metadata_report_view
string (ConversationMetadataReportView)
Enum: "NONE" "FULL"
display_name
string

The display name for the app.

id
string

The ID of the app. You can find this on the Sinch Dashboard.

object (RateLimits)
object (RetentionPolicy)

The retention policy configured for the app. For more information about retention policies, see Retention Policy.

object (DispatchRetentionPolicy)

The retention policy configured for messages in Dispatch Mode. Currently only MESSAGE_EXPIRE_POLICY is available. For more information about retention policies, see Retention Policy.

processing_mode
string (ProcessingMode)

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Enum: Description
CONVERSATION

The default Processing Mode. Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

Does not associate messages with contacts and conversations. This processing mode is mostly intended for unidirectional high volume SMS use cases. The lack of contacts and conversations limits some API features as related data won't be queryable in the Contact and Conversation APIs.

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

get/v1/projects/{project_id}/apps/{app_id}
Request samples
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const appId = 'YOUR_app_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/apps/${appId}`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

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

run();
Response samples
application/json
{
  • "channel_credentials": [
    • {
      }
    ],
  • "conversation_metadata_report_view": "NONE",
  • "display_name": "Sinch Conversation API Demo App 001",
  • "id": "{APP_ID}",
  • "rate_limits": {
    • "inbound": 0,
    • "outbound": 0,
    • "webhooks": 0
    },
  • "retention_policy": {
    • "retention_type": "MESSAGE_EXPIRE_POLICY",
    • "ttl_days": 180
    },
  • "dispatch_retention_policy": {
    • "retention_type": "MESSAGE_EXPIRE_POLICY",
    • "ttl_days": 0
    },
  • "processing_mode": "CONVERSATION"
}

Delete an app

Deletes a particular app as specified by the App ID.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

app_id
required
string

The unique ID of the app. You can find this on the Sinch Dashboard.

Responses
200

A successful response.

Response Schema: application/json
any
400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

delete/v1/projects/{project_id}/apps/{app_id}
Request samples
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const appId = 'YOUR_app_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/apps/${appId}`,
    {
      method: 'DELETE',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

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

run();
Response samples
application/json
null

Update an app

Updates a particular app as specified by the App ID.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

app_id
required
string

The unique ID of the app. You can find this on the Sinch Dashboard.

query Parameters
update_mask.paths
Array of strings

The set of field mask paths.

Request Body schema: application/json

The updated app.

display_name
required
string

The display name for the app.

Array of objects (Channel Credential)

An array of channel credentials. The order of the credentials defines the app channel priority.

conversation_metadata_report_view
string (ConversationMetadataReportView)
Enum: "NONE" "FULL"
object (RetentionPolicy)

The retention policy configured for the app. For more information about retention policies, see Retention Policy.

object (DispatchRetentionPolicy)

The retention policy configured for messages in Dispatch Mode. Currently only MESSAGE_EXPIRE_POLICY is available. For more information about retention policies, see Retention Policy.

processing_mode
string (ProcessingMode)

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Enum: Description
CONVERSATION

The default Processing Mode. Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

Does not associate messages with contacts and conversations. This processing mode is mostly intended for unidirectional high volume SMS use cases. The lack of contacts and conversations limits some API features as related data won't be queryable in the Contact and Conversation APIs.

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Channel Credential)

An array of channel credentials. The order of the credentials defines the app channel priority.

conversation_metadata_report_view
string (ConversationMetadataReportView)
Enum: "NONE" "FULL"
display_name
string

The display name for the app.

id
string

The ID of the app. You can find this on the Sinch Dashboard.

object (RateLimits)
object (RetentionPolicy)

The retention policy configured for the app. For more information about retention policies, see Retention Policy.

object (DispatchRetentionPolicy)

The retention policy configured for messages in Dispatch Mode. Currently only MESSAGE_EXPIRE_POLICY is available. For more information about retention policies, see Retention Policy.

processing_mode
string (ProcessingMode)

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Enum: Description
CONVERSATION

The default Processing Mode. Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

Does not associate messages with contacts and conversations. This processing mode is mostly intended for unidirectional high volume SMS use cases. The lack of contacts and conversations limits some API features as related data won't be queryable in the Contact and Conversation APIs.

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

patch/v1/projects/{project_id}/apps/{app_id}
Request samples
application/json
{
  • "channel_credentials": [
    • {
      },
    • {
      },
    • {
      }
    ],
  • "display_name": "New App Display Name"
}
Response samples
application/json
{
  • "channel_credentials": [
    • {
      }
    ],
  • "conversation_metadata_report_view": "NONE",
  • "display_name": "Sinch Conversation API Demo App 001",
  • "id": "{APP_ID}",
  • "rate_limits": {
    • "inbound": 0,
    • "outbound": 0,
    • "webhooks": 0
    },
  • "retention_policy": {
    • "retention_type": "MESSAGE_EXPIRE_POLICY",
    • "ttl_days": 180
    },
  • "dispatch_retention_policy": {
    • "retention_type": "MESSAGE_EXPIRE_POLICY",
    • "ttl_days": 0
    },
  • "processing_mode": "CONVERSATION"
}