Versioning

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.

API versioning

When making calls to the Sunshine Conversations API you specify the version you want to use directly in the endpoint URL.

For example:

POST /v1/apps will call the v1 Create App API
POST /v1.1/apps will call the v1.1 Create App API

Webhook versioning

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 webhook creation.

When creating a Webhook via the API use the corresponding endpoint. For example, to create a Webhook with the v1.1 API call:

POST /v1.1/apps/{appId}/webhooks

When creating a Webhook via the Sunshine Conversations dashboard select the desired version from the version dropdown.

webhook version selector

Backwards compatible changes

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:

Additive changes

  • Adding new fields or HTTP headers to existing API responses and webhook payloads
  • Adding new optional fields, query parameters, or HTTP headers to existing API request payloads
  • Adding new API endpoints or adding new methods on existing endpoints e.g. adding support for HTTP PUT to an existing API path
  • Introducing new types of messages, integrations or any other typed entity without changing the behavior of existing types (e.g. introducing a new message type of location or a new integration type of twitter. For any code that processes entities with a type property, unknown types should be gracefully handled or ignored.)
  • Introducing new webhook triggers and client platforms (e.g. introducing a new conversation:start webhook trigger, or a new client platform kakao. When handling webhook events your code should gracefully handle or ignore unknown webhook triggers or client platforms.)
  • Sending existing platform webhook triggers and message types as channels adopt new capabilities (e.g. to begin delivering conversation:read webhooks for Twitter clients as soon as the channel adopts the read notification capability

Formatting changes

  • Changing the format or length of primary id fields and keys without exceeding 255 characters (e.g. changing the string format or character length of appUser._id or key.secret)
  • Changing the order of fields in existing API responses and webhook payloads

Relaxing restrictions

  • Increasing the size or length restrictions on arrays or strings, or allowing certain characters which were previously disallowed
  • Accepting upload and transmission of new file and media types that had been previously rejected

Error handling

  • Changing the string content of friendly error descriptions (e.g. changing the message in error.description or equivalent. Error handling behavior should be done based on error.code.)
  • Changing the validation precedence of invalid HTTP requests (e.g. when sending a request that is both malformed and with invalid auth credentials, we may return either a status code of 400 Bad Request or 401 Unauthorized)
  • Promoting unclassified errors into categorized errors (e.g. when code is unhandled_error or uncategorized_error
  • Introducing new classifications of errors (e.g. in error.code or equivalent. Your code should be able to gracefully handle unknown error.code values)
  • Changing the HTTP status code of unhandled API errors (e.g. changing 500 Internal Server Error to something more specific like 400 Bad Request or 401 Unauthorized)

Changelog

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.

Upgrade Guide

Upgrading to v1.1 from v1

Before you can start using API v1.1, please make sure of the following:

API Requests

  • If you are using the post message API, make sure that you are including the type property in the body. To learn more about our message types, go to our API reference.
  • If you are using the channel linking API, make sure that you are including the confirmation property in the body.
  • If you are using the create webhook API, make sure that you are including the triggers property in the body. To learn more about our webhook triggers, go to our API reference.

Webhooks

  • message:appUser webhooks will now send user file messages from OTT channels. Previous API versions sent a text fallback instead. Make sure that your system handles sending and receiving file messages.
  • All events will now send the truncated app user schema that include app user information. Previous API versions sent the full app user schema for postback, conversation:start, message:appUser and message:appMaker events. Make sure that your system doesn’t rely on the webhook payload for detailed app user info such as its clients. If you do, use the get app user API instead.

  • For webhooks that subscribe to delivery:success or delivery:failure, you will need to transition them to the new delivery events.

    • Instead of expecting a messages key in the webhook payload, you should only expect a message key that represents the truncated message instead of the full message. Use the Message Events to get the full message.
    • delivery:success is replaced by message:delivery:channel. The payload is equivalent to v1 delivery events except that you will now receive delivery events for messages sent to SDKs.
    • delivery:failure is replaced by message:delivery:failure. Also, this webhook will trigger in more occasions than before, for example if Twilio accepts the message but subsequently fails to deliver the SMS message to the intended user.
    • message:delivery:user can be sent following a message:delivery:channel when isFinalEvent is false.

See the webhooks upgrade guide for recommendations on how to upgrade webhooks to v1.1 without downtime.

API Libraries

If you are using one of our API libraries, you’ll need to update to the following version in order to start using the v1.1 API:

  • JavaScript: >= 8.0.0 < 9.0.0
  • Ruby: 4.0.0
  • Python: 4.0.0
  • Java: >= 4.0.0 & < 6.0.0

Upgrading Webhooks Without Downtime

To avoid missing messages for apps used in production, follow the steps below to upgrade your Webhooks to a new version.

  1. Modify your code to support the breaking changes mentioned in the Upgrade Guide. You can use the version property 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.
  2. Once changes from step (1) are deployed, create a webhook with the new version with the equivalent triggers as the webhook you wish to upgrade either by using the create webhook API or from the webhook integration page.
  3. With both webhooks running, write and deploy code to accept payloads with the new version and ignore those with the old version.
  4. Once you are satisfied with the webhook upgrade, remove the webhook with the old version either by using the delete webhook API or from the webhook integration page.
  5. At this point you may remove code specific to the old version.

Steps 2-5 should be tested in a non-production environment before they are applied to your production environment.