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 and how to safely upgrade to new versions.
When making calls to the API you specify the version you want to use directly in the endpoint URL.
Webhooks naturally follow the same version and payload schema as the API. You specify which version 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:
When creating a Webhook via the 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 ‘s 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
error.descriptionor equivalent. Error handling behavior should be done based on
error.codeor equivalent. Your code should be able to gracefully handle unknown
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 can start using API v1.1, please make sure of the following:
typeproperty in the body. To learn more about our message types, go to our API reference.
confirmationproperty in the body.
triggersproperty in the body. To learn more about our webhook triggers, go to our API reference.
message:appUserwebhooks will now send user
filemessages from OTT channels. Previous API versions sent a text fallback instead. Make sure that your system handles sending and receiving
truncated app user schemathat include app user information. Previous API versions sent the full app user schema for
message:appMakerevents. 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:failure, you will need to transition them to the new delivery events.
messageskey in the webhook payload, you should only expect a
messagekey that represents the truncated message instead of the full message. Use the Message Events to get the full
delivery:successis replaced by
message:delivery:channel. The payload is equivalent to
v1delivery events except that you will now receive delivery events for messages sent to SDKs.
delivery:failureis 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:usercan be sent following a
See the webhooks upgrade guide for recommendations on how to upgrade webhooks to
v1.1 without downtime.
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.