New in Smooch this month: Smooch API v1.1 is here along with our new API versioning framework. The first major release of this new API version includes new delivery events to provide you with more details around message delivery. We’ve also made some tweaks to our SDKs and APIs.

What’s new 🎉

API versioning is here!

Interacting with third-party APIs is part of our DNA at Smooch. We value stability, predictability and consistency in APIs and those same attributes sit at the top of our priorities when developing our own. Since the introduction of the Smooch API, we’ve been able to add new concepts and features while keeping the interface backwards compatible. However, there comes a point in the life of an API where backward incompatible changes need to be introduced so that considerable new capabilities can see the light.

Today, we are excited to introduce a new API versioning mechanism on the Smooch platform. This new mechanism allows us to launch new features and make API improvements that require backwards incompatible changes while allowing you to opt in to these new capabilities on your own schedule.

How it works

When making calls to the Smooch API you simply specify the version in the endpoint URL. Webhook payloads are also versioned, following the same version progression as the API. You can specify which version Smooch should be using when calling your server during the webhook creation.

v1.1 is now available

Our first version update introduces a few API enhancements and new message delivery webhooks including delivery confirmation events from third-party channels (more on that 👇). You can read up about changes introduced to v1.1 and follow our upgrade guide to adopt this new API version.

Learn more about how our API versioning framework works on our blog.

New delivery confirmation events

The Smooch API v1.1 introduces new delivery confirmation webhook triggers. Whereas v1 simply indicated if a message was successfully delivered to a channel or had failed, v1.1 allows for a more complete delivery trace when made available by the channel where the message is being delivered.

A message delivery can now emit three possible webhook events:

• message:delivery:channel indicates the message was delivered to the channel (eg. WhatsApp), but may not have been received by the user yet.
• message:delivery:user indicates the message was successfully delivered to the end-user (note that this delivery confirmation is only supported by certain channels).
• In case a message can’t be delivered to a channel or an end-user, message:delivery:failure will be fired and will include all the details about the failure.

These three events can be integrated into a conversation user interface to provide in-depth delivery information or they can be used for troubleshooting purposes. The message:delivery:user trigger is useful to detect failures where the delivery flow of a channel is more complex.

For example, SMS providers might accept a message (triggering a message:delivery:channel event), but then fail to deliver the message to the end-user because a carrier rejected the message later on. In that case, this would trigger a subsequent message:delivery:failure event.

Check out our Delivery Events Guide where we cover how we handle differences between channels and how delivery events behave for end-users connected to multiple channels. You’ll also notice that we’ve updated each of our channel guides with a section on delivery events. Here’s an example for WhatsApp.

Other API & SDK updates ⚙

• WhatsApp channel update: WhatsApp API Clients can now be integrated with Smooch Apps via the Integration API. This can be done whether Smooch is hosting API Clients for you or you’re hosting your own. A quick reminder that the WhatsApp Business API is still in limited availability and that brands and customer service platforms need to be approved by the WhatsApp team. We’ve also released a business profile API enabling you to configure key business information, including a profile picture for each of your approved WhatsApp numbers.
• File size limit for attachments: The size limit for files hosted by Smooch has been raised from 10MB to 25MB.
• iOS SDK: We shipped v6.11.0 which adds support for the metadata field in SKTMessageItem. This will help those of you who need a way to attach and process metadata on individual message items.