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.

SecurityBasic or oAuth2

Request

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.

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.

object (SmartConversation)

This object is required for apps that subscribe to Smart Conversations features. Note that this functionality is available for open beta testing.

object (QueueStats)

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

Node.js
C#
Java
Python
curl

Response samples

application/json

{"apps": [{"channel_credentials": [{"callback_secret": "string",
"channel": "WHATSAPP",
"mms_credentials": {"account_id": "string",
"api_key": "string",
"basic_auth": {"password": "string",
"username": "string"
}
},
"kakaotalk_credentials": {"kakaotalk_plus_friend_id": "string",
"kakaotalk_sender_key": "string"
},
"static_bearer": {"claimed_identity": "string",
"token": "string"
},
"static_token": {"token": "string"
},
"telegram_credentials": {"token": "{{TELEGRAM_BOT_TOKEN}}"
},
"line_credentials": {"token": "{{LINE_TOKEN}}",
"secret": "{{LINE_SECRET}}"
},
"wechat_credentials": {"app_id": "{{WECHAT_APPID}}",
"app_secret": "{{WECHAT_APPSECRET}}",
"token": "{{WECHAT_TOKEN}}",
"aes_key": "{{WECHAT_AESKEY}}"
}
}
],
"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",
"smart_conversation": {"enabled": false
},
"queue_stats": {"outbound_size": 0,
"outbound_limit": 0
}
}
]
}

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.

SecurityBasic or oAuth2

Request

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
required

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.

object (SmartConversation)

This object is required for apps that subscribe to Smart Conversations features. Note that this functionality is available for open beta testing.

object (CallbackSettings)

This object contains additional settings related to callback processing.

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.

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.

object (SmartConversation)

This object is required for apps that subscribe to Smart Conversations features. Note that this functionality is available for open beta testing.

object (QueueStats)

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": [{"channel": "MESSENGER",
"static_token": {"token": "{Facebook_Token}"
}
}
],
"display_name": "Demo Facebook App"
}

Response samples

application/json

{"channel_credentials": [{"callback_secret": "string",
"channel": "WHATSAPP",
"mms_credentials": {"account_id": "string",
"api_key": "string",
"basic_auth": {"password": "string",
"username": "string"
}
},
"kakaotalk_credentials": {"kakaotalk_plus_friend_id": "string",
"kakaotalk_sender_key": "string"
},
"static_bearer": {"claimed_identity": "string",
"token": "string"
},
"static_token": {"token": "string"
},
"telegram_credentials": {"token": "{{TELEGRAM_BOT_TOKEN}}"
},
"line_credentials": {"token": "{{LINE_TOKEN}}",
"secret": "{{LINE_SECRET}}"
},
"wechat_credentials": {"app_id": "{{WECHAT_APPID}}",
"app_secret": "{{WECHAT_APPSECRET}}",
"token": "{{WECHAT_TOKEN}}",
"aes_key": "{{WECHAT_AESKEY}}"
}
}
],
"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",
"smart_conversation": {"enabled": false
},
"queue_stats": {"outbound_size": 0,
"outbound_limit": 0
}
}

Get an app

Returns a particular app as specified by the App ID.

SecurityBasic or oAuth2

Request

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.

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.

object (SmartConversation)

This object is required for apps that subscribe to Smart Conversations features. Note that this functionality is available for open beta testing.

object (QueueStats)

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

Node.js
C#
Java
Python
curl

Response samples

application/json

{"channel_credentials": [{"callback_secret": "string",
"channel": "WHATSAPP",
"mms_credentials": {"account_id": "string",
"api_key": "string",
"basic_auth": {"password": "string",
"username": "string"
}
},
"kakaotalk_credentials": {"kakaotalk_plus_friend_id": "string",
"kakaotalk_sender_key": "string"
},
"static_bearer": {"claimed_identity": "string",
"token": "string"
},
"static_token": {"token": "string"
},
"telegram_credentials": {"token": "{{TELEGRAM_BOT_TOKEN}}"
},
"line_credentials": {"token": "{{LINE_TOKEN}}",
"secret": "{{LINE_SECRET}}"
},
"wechat_credentials": {"app_id": "{{WECHAT_APPID}}",
"app_secret": "{{WECHAT_APPSECRET}}",
"token": "{{WECHAT_TOKEN}}",
"aes_key": "{{WECHAT_AESKEY}}"
}
}
],
"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",
"smart_conversation": {"enabled": false
},
"queue_stats": {"outbound_size": 0,
"outbound_limit": 0
}
}

Delete an app

Deletes the app specified by the App ID. Note that this operation will not delete contacts (which are stored at the project level) nor any channel-specific resources (for example, WhatsApp Sender Identities will not be deleted).

SecurityBasic or oAuth2

Request

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

Node.js
C#
Java
Python
curl

Response samples

application/json

null

Update an app

Updates a particular app as specified by the App ID. Note that this is a PATCH operation, so any specified field values will replace existing values. Therefore, if you'd like to add additional configurations to an existing Conversation API app, ensure that you include existing values AND new values in the call. For example, if you'd like to add new channel_credentials, you can get your existing Conversation API app, extract the existing channel_credentials list, append your new configuration to that list, and include the updated channel_credentials list in this update call.

SecurityBasic or oAuth2

Request

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
required

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.

object (SmartConversation)

This object is required for apps that subscribe to Smart Conversations features. Note that this functionality is available for open beta testing.

object (CallbackSettings)

This object contains additional settings related to callback processing.

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.

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.

object (SmartConversation)

This object is required for apps that subscribe to Smart Conversations features. Note that this functionality is available for open beta testing.

object (QueueStats)

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": [{"channel": "WHATSAPP",
"static_bearer": {"claimed_identity": "{{WhatsApp_Sender_Id}}",
"token": "{{WhatsApp_Bearer_Token}}"
},
"callback_secret": "{{Callback_Secret_1}}"
},
{"channel": "MESSENGER",
"static_token": {"token": "{{Facebook_Token}}"
},
"callback_secret": "{{Callback_Secret_2}}"
},
{"channel": "SMS",
"static_bearer": {"claimed_identity": "{{Service_Plan_Id}}",
"token": "{{API_Token}}"
}
}
],
"display_name": "New App Display Name"
}

Response samples

application/json

{"channel_credentials": [{"callback_secret": "string",
"channel": "WHATSAPP",
"mms_credentials": {"account_id": "string",
"api_key": "string",
"basic_auth": {"password": "string",
"username": "string"
}
},
"kakaotalk_credentials": {"kakaotalk_plus_friend_id": "string",
"kakaotalk_sender_key": "string"
},
"static_bearer": {"claimed_identity": "string",
"token": "string"
},
"static_token": {"token": "string"
},
"telegram_credentials": {"token": "{{TELEGRAM_BOT_TOKEN}}"
},
"line_credentials": {"token": "{{LINE_TOKEN}}",
"secret": "{{LINE_SECRET}}"
},
"wechat_credentials": {"app_id": "{{WECHAT_APPID}}",
"app_secret": "{{WECHAT_APPSECRET}}",
"token": "{{WECHAT_TOKEN}}",
"aes_key": "{{WECHAT_AESKEY}}"
}
}
],
"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",
"smart_conversation": {"enabled": false
},
"queue_stats": {"outbound_size": 0,
"outbound_limit": 0
}
}

Security Privacy Legal & Compliance Cookie Statement

App

List all apps for a given project

path Parameters

Response Schema: application/json

Create an app

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Get an app

path Parameters

Response Schema: application/json

Delete an app

path Parameters

Response Schema: application/json

Update an app

path Parameters

query Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Request Body schema: application/json
required

Request Body schema: application/json
required