# 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.

Endpoint: POST /v1/projects/{project_id}/apps
Version: 1.0
Security: Basic, oAuth2

## Path parameters:

  - `project_id` (string, required)
    The unique ID of the project. You can find this on the Sinch Dashboard.

## Request fields (application/json):

  - `display_name` (string, required)
    The display name for the app.
    Example: "Sinch Conversation API Demo App 001"

  - `channel_credentials` (array, required)
    An array of channel credentials. The order of the credentials defines the app channel priority.

  - `channel_credentials.callback_secret` (string)
    The secret used to verify the channel callbacks
for channels which support callback verification.
The callback verification is not needed for Sinch-managed
channels because the callbacks are not leaving
Sinch internal networks.
Max length is 256 characters.
Note: leaving channel_callback_secret empty for channels with
callback verification will disable the verification.

  - `channel_credentials.channel` (string)
    The identifier of the channel you want to include. Must be one of the enum values.
    Enum: "WHATSAPP", "RCS", "SMS", "MESSENGER", "VIBERBM", "MMS", "INSTAGRAM", "TELEGRAM", "KAKAOTALK", "KAKAOTALKCHAT", "LINE", "WECHAT", "APPLEBC"

  - `channel_credentials.credential_ordinal_number` (integer)
    The ordinal number of the credential. This field is used when the application supports multiple credential integrations per channel. Currently, this is only applicable to the LINE channel. For other channels, this value will always be set to 0. In the case in which there are multiple credential integrations per channel on a single app, this field must have a unique value for each multi-credential channel entry.

  - `conversation_metadata_report_view` (string)
    NONE - Omit metadata.
FULL - Include all metadata assigned to the conversation.
    Enum: "NONE", "FULL"

  - `retention_policy` (object)
    The retention policy configured for the app. For more information about retention policies, see [Retention Policy](https://developers.sinch.com/docs/conversation/keyconcepts/#retention-policy).

  - `retention_policy.retention_type` (string)
    Enum: "MESSAGE_EXPIRE_POLICY", "CONVERSATION_EXPIRE_POLICY", "PERSIST_RETENTION_POLICY"

  - `retention_policy.ttl_days` (integer)
    Optional. The days before a message or conversation is eligible for deletion.
Default value is 180. The ttl_days value has no effect when retention_type
is PERSIST_RETENTION_POLICY. The valid values for this field are [1 - 3650].
Note that retention cleanup job runs once every twenty-four hours
which can lead to delay i.e., messages and conversations are not deleted on
the minute they become eligible for deletion.

  - `dispatch_retention_policy` (object)
    The retention policy configured for messages in [Dispatch Mode](https://developers.sinch.com/docs/conversation/processing-modes/). Currently only MESSAGE_EXPIRE_POLICY is available. For more information about retention policies, see [Retention Policy](https://developers.sinch.com/docs/conversation/keyconcepts/#retention-policy).

  - `dispatch_retention_policy.ttl_days` (integer)
    Optional. The days before a message is eligible for deletion. The valid range is [0 - 7]. In the case of a 0 day TTL, messages aren't stored at all.
Note the retention cleanup job runs once every twenty-four hours, so messages are not deleted on the minute they become eligible for deletion.

  - `processing_mode` (string)
    Whether or not Conversation API should store contacts and conversations for the app. For more information, see [Processing Modes](https://developers.sinch.com/docs/conversation/processing-modes/).
    Enum: "CONVERSATION", "DISPATCH"

  - `smart_conversation` (object)
    This object is required for apps that subscribe to Smart Conversations features.

  - `smart_conversation.enabled` (boolean)
    Set to true to allow messages processed by this app to be analyzed by Smart Conversations.

  - `callback_settings` (object)
    This object contains additional settings related to callback processing.

  - `callback_settings.secret_for_overridden_callback_urls` (string)
    Optional. Secret can be used to sign contents of delivery receipts for a message that was sent with the default callback URL overridden (using the [callback_url field](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=callback_url&t=request)). You can then use the secret to verify the signature.

  - `message_retry_settings` (object)
    This object contains settings related to message retry mechanism.

  - `message_retry_settings.retry_duration` (integer)
    The maximum duration, in seconds, during which the system will retry sending a message in the event of a temporary processing failure. Time is counted after the first message processing failure. At least one retry is guaranteed. Subsequent retry instances are randomized with exponential backoff. If the next retry timestamp exceeds the configured time, one final retry will be performed on the cut-off time. The valid values for this field are [30 - 3600].

  - `delivery_report_based_fallback` (object)
    This object contains additional settings related to [delivery report based fallback](https://developers.sinch.com/docs/conversation/keyconcepts/#delivery-report-base-message-fallback). Note that this paid functionality is available for open beta testing.

  - `delivery_report_based_fallback.enabled` (boolean)
    Optional. A flag specifying whether this app has enabled fallback message delivery upon no positive delivery report. This feature is applicable only to messages which are sent to a recipient with more than one channel identity. Identities must be defined on channels which support at least the 'DELIVERED' message state. Please note that this functionality requires payment.

  - `delivery_report_based_fallback.delivery_report_waiting_time` (integer)
    Optional. The time, in seconds, after which a message without a positive delivery report will fallback to the next channel. The valid values for this field are [60 - 259200].

## Response 200 fields (application/json):

  - `channel_credentials` (array)

  - `channel_credentials.callback_secret` (string)
    The secret used to verify the channel callbacks
for channels which support callback verification.
The callback verification is not needed for Sinch-managed
channels because the callbacks are not leaving
Sinch internal networks.
Max length is 256 characters.
Note: leaving channel_callback_secret empty for channels with
callback verification will disable the verification.

  - `channel_credentials.channel` (string)
    The identifier of the channel you want to include. Must be one of the enum values.
    Enum: "WHATSAPP", "RCS", "SMS", "MESSENGER", "VIBERBM", "MMS", "INSTAGRAM", "TELEGRAM", "KAKAOTALK", "KAKAOTALKCHAT", "LINE", "WECHAT", "APPLEBC"

  - `channel_credentials.state` (object)
    State of the channel credentials integration.

  - `channel_credentials.state.status` (string, required)
    Status of the channel credentials integration
    Enum: "PENDING", "ACTIVE", "FAILING"

  - `channel_credentials.state.description` (string)
    Description in case the integration fails

  - `channel_credentials.channel_known_id` (string)
    Additional identifier set by the channel that represents an specific id used by the channel.

  - `channel_credentials.credential_ordinal_number` (integer)
    The ordinal number of the credential. This field is used when the application supports multiple credential integrations per channel. Currently, this is only applicable to the LINE channel. For other channels, this value will always be set to 0. In the case in which there are multiple credential integrations per channel on a single app, this field must have a unique value for each multi-credential channel entry.

  - `conversation_metadata_report_view` (string)
    NONE - Omit metadata.
FULL - Include all metadata assigned to the conversation.
    Enum: "NONE", "FULL"

  - `display_name` (string)
    The display name for the app.
    Example: "Sinch Conversation API Demo App 001"

  - `id` (string)
    The ID of the app. You can find this on the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps).
    Example: "{APP_ID}"

  - `rate_limits` (object)

  - `rate_limits.inbound` (integer)
    The number of inbound messages/events we process per second,
from underlying channels to the app.  The default rate limit is 25.

  - `rate_limits.outbound` (integer)
    The number of messages/events we process per second, from the
app to the underlying channels. Note that underlying channels may have other
rate limits.  The default rate limit is 25.

  - `rate_limits.webhooks` (integer)
    The rate limit of callbacks sent to the webhooks registered
for the app. Note that if you have multiple webhooks with shared triggers,
multiple callbacks will be sent out for each triggering event. The default rate limit is 25.

  - `retention_policy` (object)
    The retention policy configured for the app. For more information about retention policies, see [Retention Policy](https://developers.sinch.com/docs/conversation/keyconcepts/#retention-policy).

  - `retention_policy.retention_type` (string)
    Enum: "MESSAGE_EXPIRE_POLICY", "CONVERSATION_EXPIRE_POLICY", "PERSIST_RETENTION_POLICY"

  - `retention_policy.ttl_days` (integer)
    Optional. The days before a message or conversation is eligible for deletion.
Default value is 180. The ttl_days value has no effect when retention_type
is PERSIST_RETENTION_POLICY. The valid values for this field are [1 - 3650].
Note that retention cleanup job runs once every twenty-four hours
which can lead to delay i.e., messages and conversations are not deleted on
the minute they become eligible for deletion.

  - `dispatch_retention_policy` (object)
    The retention policy configured for messages in [Dispatch Mode](https://developers.sinch.com/docs/conversation/processing-modes/). Currently only MESSAGE_EXPIRE_POLICY is available. For more information about retention policies, see [Retention Policy](https://developers.sinch.com/docs/conversation/keyconcepts/#retention-policy).

  - `dispatch_retention_policy.ttl_days` (integer)
    Optional. The days before a message is eligible for deletion. The valid range is [0 - 7]. In the case of a 0 day TTL, messages aren't stored at all.
Note the retention cleanup job runs once every twenty-four hours, so messages are not deleted on the minute they become eligible for deletion.

  - `processing_mode` (string)
    Whether or not Conversation API should store contacts and conversations for the app. For more information, see [Processing Modes](https://developers.sinch.com/docs/conversation/processing-modes/).
    Enum: "CONVERSATION", "DISPATCH"

  - `smart_conversation` (object)
    This object is required for apps that subscribe to Smart Conversations features.

  - `smart_conversation.enabled` (boolean)
    Set to true to allow messages processed by this app to be analyzed by Smart Conversations.

  - `queue_stats` (object)

  - `queue_stats.outbound_size` (integer)
    The current size of the App's MT queue.

  - `queue_stats.outbound_limit` (integer)
    The limit of the App's MT queue. The default limit is 500000 messages.

  - `callback_settings` (object)
    This object contains additional settings related to callback processing.

  - `callback_settings.secret_for_overridden_callback_urls` (string)
    Optional. Secret can be used to sign contents of delivery receipts for a message that was sent with the default callback URL overridden (using the [callback_url field](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=callback_url&t=request)). You can then use the secret to verify the signature.

  - `delivery_report_based_fallback` (object)
    This object contains additional settings related to [delivery report based fallback](https://developers.sinch.com/docs/conversation/keyconcepts/#delivery-report-base-message-fallback). Note that this paid functionality is available for open beta testing.

  - `delivery_report_based_fallback.enabled` (boolean)
    Optional. A flag specifying whether this app has enabled fallback message delivery upon no positive delivery report. This feature is applicable only to messages which are sent to a recipient with more than one channel identity. Identities must be defined on channels which support at least the 'DELIVERED' message state. Please note that this functionality requires payment.

  - `delivery_report_based_fallback.delivery_report_waiting_time` (integer)
    Optional. The time, in seconds, after which a message without a positive delivery report will fallback to the next channel. The valid values for this field are [60 - 259200].

  - `message_retry_settings` (object)
    This object contains settings related to message retry mechanism.

  - `message_retry_settings.retry_duration` (integer)
    The maximum duration, in seconds, during which the system will retry sending a message in the event of a temporary processing failure. Time is counted after the first message processing failure. At least one retry is guaranteed. Subsequent retry instances are randomized with exponential backoff. If the next retry timestamp exceeds the configured time, one final retry will be performed on the cut-off time. The valid values for this field are [30 - 3600].

## Response 400 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 403 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 500 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 501 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)