We believe versioning is a crucial part of our offering. By providing a consistent versioning scheme for our API & Webhooks we are able to help you manage and predict how our changes will impact your usage. When we have to change the API in a backwards-incompatible way, we release a new version to avoid breaking your integration. You can opt-in to the new version whenever you’re ready to upgrade.
This guide covers how versioning works at Sunshine Conversations and how to safely upgrade to new versions.
When making calls to the Sunshine Conversations API you specify the version you want to use directly in the endpoint URL.
POST /v1.1/appswill call the v1.1 Create App API
POST /v2/appswill call the v2 Create App API
Webhooks naturally follow the same version and payload schema as the API. You specify which version Sunshine Conversations should be using when calling your webhook endpoint during the custom integration’s creation.
When creating a custom integration via the API use the corresponding endpoint. For example, to create a custom integration with the
v2 API call:
When creating a Webhook via the Sunshine Conversations dashboard select the desired version from the version dropdown.
We consider the following types of changes to be backwards compatible. In other words, these types of changes do not require a new version of the API. When writing code against Sunshine Conversations APIs and webhook payloads, take care to ensure that the types of changes listed below would not break any assumptions you make in your code. Your JSON parsing logic should be configured not to throw an error when an unexpected key is found, or when an enum contains a previously unknown value. Assume also that any JSON field returned as an array may contain multiple items in the future.
The list below applies to our REST API, webhook events, the SDK public API, and our API libraries:
conversation:startwebhook trigger, or a new client platform
kakao. When handling webhook events your code should gracefully handle or ignore unknown webhook triggers or client platforms.)
conversation:readwebhooks for Twitter clients as soon as the channel adopts the read notification capability
nullto unset a field such as
titleor equivalent. Error handling behavior should be done based on error
codeor equivalent. Your code should be able to gracefully handle unknown error
500 Internal ServerError to something more specific like
400 Bad Requestor
We maintain a changelog of backward incompatible change as part of our API reference documentation.
We also have a platform wide changelog that covers the API, Web and Mobile SDKs, Integrations, and the Web dashboard available here.
Before you start using a new API version, please make sure you are aware of the following:
If you are using one of our API libraries, you’ll need to update to the following version in order to start using the
To avoid missing messages for apps used in production, follow the steps below to upgrade your Webhooks to a new version.
versionproperty included in all event payloads to conditionally execute code based on the webhook version. Your code is now capable of receiving both webhook versions, while ignoring the newer version for now.
Steps 2-5 should be tested in a non-production environment before they are applied to your production environment.