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 Static Bearer Authentication (object) or Static Token Authentication (object) or MMS (object) or KakaoTalk (object) or Telegram (object) or LINE (object) or LINE Enterprise (object) or WeChat (object) or Instagram (object) or Apple Business Chat (object) or KakaoTalkChat (object) (ConversationChannelCredentials)
conversation_metadata_report_view
string (ConversationMetadataReportView)
Default: "NONE"

NONE - Omit metadata. FULL - Include all metadata assigned to the conversation.

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 (Retention policy for messages and conversations)

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)
Default: "CONVERSATION"

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

Enum Value 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)
object (CallbackSettings)

This object contains additional settings related to callback processing.

object (DeliveryReportBasedFallback)

This object contains additional settings related to delivery report based fallback. Note that this paid functionality is available for open beta testing.

object (MessageRetrySettings)

This object contains settings related to message retry mechanism.

400

Malformed request. See common error responses for more information.

401

Incorrect credentials. See common error responses for more information.

403

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

500

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

501

Something went wrong on our end, try again with exponential back-off. See common error responses for more information.

get/v1/projects/{project_id}/apps
Request samples 
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.


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 Static Bearer Authentication (object) or Static Token Authentication (object) or MMS (object) or KakaoTalk (object) or Telegram (object) or LINE (object) or LINE Enterprise (object) or WeChat (object) or Instagram (object) or Apple Business Chat (object) or KakaoTalkChat (object) (ConversationChannelCredentialRequest) 
An array of channel credentials. The order of the credentials defines the app channel priority.


 
conversation_metadata_report_view
string (ConversationMetadataReportView) 
 Default:  "NONE"
NONE - Omit metadata.
FULL - Include all metadata assigned to the conversation.


 Enum: "NONE" "FULL"  
object (Retention policy for messages and conversations) 
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) 
 Default:  "CONVERSATION"
Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.


 Enum Value 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.


 
object (MessageRetrySettings) 
This object contains settings related to message retry mechanism.


 
object (DeliveryReportBasedFallback) 
This object contains additional settings related to delivery report based fallback. Note that this paid functionality is available for open beta testing.


 
Responses 
200
A successful response.


Response Schema: application/json
Array of Static Bearer Authentication (object) or Static Token Authentication (object) or MMS (object) or KakaoTalk (object) or Telegram (object) or LINE (object) or LINE Enterprise (object) or WeChat (object) or Instagram (object) or Apple Business Chat (object) or KakaoTalkChat (object) (ConversationChannelCredentials) 
 
conversation_metadata_report_view
string (ConversationMetadataReportView) 
 Default:  "NONE"
NONE - Omit metadata.
FULL - Include all metadata assigned to the conversation.


 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 (Retention policy for messages and conversations) 
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) 
 Default:  "CONVERSATION"
Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.


 Enum Value 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) 
 
object (CallbackSettings) 
This object contains additional settings related to callback processing.


 
object (DeliveryReportBasedFallback) 
This object contains additional settings related to delivery report based fallback. Note that this paid functionality is available for open beta testing.


 
object (MessageRetrySettings) 
This object contains settings related to message retry mechanism.


 
400
Malformed request. See common error responses for more information.


401
Incorrect credentials. See common error responses for more information.


403
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


500
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


501
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.


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",
  • "smart_conversation": {
    • "enabled": false
    },
  • "queue_stats": {
    • "outbound_size": 0,
    • "outbound_limit": 0
    },
  • "callback_settings": {
    • "secret_for_overridden_callback_urls": "pa$$word"
    },
  • "delivery_report_based_fallback": {
    • "enabled": false,
    • "delivery_report_waiting_time": 0
    },
  • "message_retry_settings": {
    • "retry_duration": 3600
    }
}
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 Static Bearer Authentication (object) or Static Token Authentication (object) or MMS (object) or KakaoTalk (object) or Telegram (object) or LINE (object) or LINE Enterprise (object) or WeChat (object) or Instagram (object) or Apple Business Chat (object) or KakaoTalkChat (object) (ConversationChannelCredentials) 
 
conversation_metadata_report_view
string (ConversationMetadataReportView) 
 Default:  "NONE"
NONE - Omit metadata.
FULL - Include all metadata assigned to the conversation.


 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 (Retention policy for messages and conversations) 
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) 
 Default:  "CONVERSATION"
Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.


 Enum Value 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) 
 
object (CallbackSettings) 
This object contains additional settings related to callback processing.


 
object (DeliveryReportBasedFallback) 
This object contains additional settings related to delivery report based fallback. Note that this paid functionality is available for open beta testing.


 
object (MessageRetrySettings) 
This object contains settings related to message retry mechanism.


 
400
Malformed request. See common error responses for more information.


401
Incorrect credentials. See common error responses for more information.


403
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


500
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


501
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.


get/v1/projects/{project_id}/apps/{app_id}
Request samples 
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",
  • "smart_conversation": {
    • "enabled": false
    },
  • "queue_stats": {
    • "outbound_size": 0,
    • "outbound_limit": 0
    },
  • "callback_settings": {
    • "secret_for_overridden_callback_urls": "pa$$word"
    },
  • "delivery_report_based_fallback": {
    • "enabled": false,
    • "delivery_report_waiting_time": 0
    },
  • "message_retry_settings": {
    • "retry_duration": 3600
    }
}
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.


400
Malformed request. See common error responses for more information.


401
Incorrect credentials. See common error responses for more information.


403
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


500
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


501
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.


delete/v1/projects/{project_id}/apps/{app_id}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "message": "Malformed request",
  • "status": "INVALID_REQUEST",
  • "details": [ ]
}
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
Array of strings
The set of field mask paths.


 
Request Body schema: application/json
required
The updated app.


Array of Static Bearer Authentication (object) or Static Token Authentication (object) or MMS (object) or KakaoTalk (object) or Telegram (object) or LINE (object) or LINE Enterprise (object) or WeChat (object) or Instagram (object) or Apple Business Chat (object) or KakaoTalkChat (object) (ConversationChannelCredentialRequest) 
An array of channel credentials. The order of the credentials defines the app channel priority.


 
conversation_metadata_report_view
string (ConversationMetadataReportView) 
 Default:  "NONE"
NONE - Omit metadata.
FULL - Include all metadata assigned to the conversation.


 Enum: "NONE" "FULL"  
display_name
string
The display name for the app.


 
object (Retention policy for messages and conversations) 
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) 
 Default:  "CONVERSATION"
Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.


 Enum Value 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.


 
object (MessageRetrySettings) 
This object contains settings related to message retry mechanism.


 
object (DeliveryReportBasedFallback) 
This object contains additional settings related to delivery report based fallback. Note that this paid functionality is available for open beta testing.


 
Responses 
200
A successful response.


Response Schema: application/json
Array of Static Bearer Authentication (object) or Static Token Authentication (object) or MMS (object) or KakaoTalk (object) or Telegram (object) or LINE (object) or LINE Enterprise (object) or WeChat (object) or Instagram (object) or Apple Business Chat (object) or KakaoTalkChat (object) (ConversationChannelCredentials) 
 
conversation_metadata_report_view
string (ConversationMetadataReportView) 
 Default:  "NONE"
NONE - Omit metadata.
FULL - Include all metadata assigned to the conversation.


 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 (Retention policy for messages and conversations) 
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) 
 Default:  "CONVERSATION"
Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.


 Enum Value 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) 
 
object (CallbackSettings) 
This object contains additional settings related to callback processing.


 
object (DeliveryReportBasedFallback) 
This object contains additional settings related to delivery report based fallback. Note that this paid functionality is available for open beta testing.


 
object (MessageRetrySettings) 
This object contains settings related to message retry mechanism.


 
400
Malformed request. See common error responses for more information.


401
Incorrect credentials. See common error responses for more information.


403
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


500
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


501
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.


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",
  • "smart_conversation": {
    • "enabled": false
    },
  • "queue_stats": {
    • "outbound_size": 0,
    • "outbound_limit": 0
    },
  • "callback_settings": {
    • "secret_for_overridden_callback_urls": "pa$$word"
    },
  • "delivery_report_based_fallback": {
    • "enabled": false,
    • "delivery_report_waiting_time": 0
    },
  • "message_retry_settings": {
    • "retry_duration": 3600
    }
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.