v2 API Changelog

Introduction

This document provides an exhaustive list of changes between the v1.1 and v2 API suites. The full v2 API specification can be found here.

• Revision history
• API changes
• Schema changes

Revision history

This document is continuously updated as backward compatible changes are made to the v2 API and new endpoints are added. Below you can see when the document was last edited:

• 2020-03-31 - Initial Version
• 2020-07-22 - Added new webhook event conversation:create
• 2020-05-28 - Added the Apps and App Keys APIs
• 2020-08-06 - Added new webhook event conversation:postback
• 2020-08-06 - Added the new format for API errors
• 2020-08-13 - Added forecasted changes
• 2020-08-21 - Published this new changelog. All changes will be tracked from here now.
• 2020-08-25 - Added webhook endpoints
• 2020-08-30 - Added changes to author schema and conversation schema
• 2020-09-03 - Added new webhook delivery events
• 2020-09-15 - Added attachments API
• 2020-09-29 - Added users API
• 2020-10-01 - GA release. Removes early access mentions
• 2021-09-28 - Added new webhook events: client:add, client:update and client:remove
• 2021-09-28 - Updated the user:merge webhook event
• 2022-03-23 - Added the user:updatewebhook event
• 2022-07-28 - Added the conversation:referral webhook event
• 2022-09-01 - The Switchboard passControl action is now idempotent

API changes

The v2 API is a new set of APIs with extended capabilities to the v1 suite. Many of the existing v1 API endpoints have equivalent v2 API endpoints, however many request and response payloads have been significantly modified in the new API. A summary of the biggest differences is provided below. For more details, consult the documentation of each specific endpoint.

General

• The _id field has been renamed to id
• JWT scope of appUser is no longer supported for server-to-server calls
• Support for implicit paths to access app resources (e.g. /v1.1/appusers/{id}) has been removed. All app resources are now only accessible with paths including the app ID (/v2/apps/:appId/…)
• Standardized dates and timestamps on various objects into a single common format. All date-related fields should now be returned as strings with the format YYYY-MM-DDThh:mm:ss.SSSZ
• When the API returns an error, it now provides an errors array in the response instead of an error object
• Offset-based pagination has been replaced by cursor-based pagination for all endpoints that support pagination. See details here (under “Cursor pagination”)
• Calls to modify a resource now use the PATCH HTTP verb instead of PUT. The behaviour remains unchanged between PUT and PATCH

Apps

• The metadata field now allows partial updates. Values within metadata can now be unset with null
• The List Apps API now uses cursor-based pagination instead of offset-based pagination. See details here (under “Cursor pagination”)
• The serviceAccountId query parameter used to return only the apps that the service account has access to was replaced by filter[serviceAccountId]

App Keys

• The Get App JWT API has been removed

Attachments

• Instead of passing an appUserId or a userId in the query parameters it is now replaced with conversationId
• mediaUrl and mediaType in the response body have been moved under a top-level object attachment to match the style of other API responses

Clients

• The List Clients API now uses cursor-based pagination instead of offset-based pagination. See details here (under “Cursor pagination”)

Conversations

• Conversation-related APIs are now pathed under /conversations instead of /appusers, and a conversation ID must be supplied instead of a user ID
• Added support for multiple conversations per user, including new endpoints to create, list and delete conversations for a user
• The concept of participant has been introduced to track a user’s membership in a conversation, and which of a user’s clients have been subscribed to receive messages in that conversation
• Added support for conversations between multiple users, including new endpoints to create, list and delete participants for a conversation
• The message schema has changed significantly when creating and retrieving messages. The previous message structure has been re-organized and composed into multiple top-level objects including author, source, and content. See the message schema changes below for more details
• The Post Message API now returns an array of messages rather than a single message object and an array of extraMessages
• The List Messages and Post Message APIs no longer return a conversation object
• Post Activity API now requires an author object in the body, rather than the previous role field
• The Reset Unread Count API has been removed in favor of Post Activity API with author.role: 'user'

• Updated validation on certain fields when posting messages

  1. The actions array now has has a max size of 10, and a minimum size of 1. The field remains optional if no actions are desired for the message
  2. mediaType can no longer be specified when posting a message. The type of the file will always be inferred from the mediaUrl
  3. Extra channel options webview_height_ratio and fallback_url are no longer considered for webview in Facebook Messenger. Use the size and fallback properties of the webview action instead
  4. When specifying a destination, integration types apn and fcm have been replaced by ios and android, respectively
  5. Shorthand syntax will only be parsed in text type messages. Syntax passed in the text field of other message types will be ignored
  6. A more specific invalidFile error will replace the generic badRequest error when invalid media is sent
• The List Conversations API now uses cursor-based pagination instead of offset-based pagination. See details here (under “Cursor pagination”)

Deployments

Not migrated to v2 yet

Integrations

• Integrations of type fcm have been replaced by the new type android. The senderId and serverKey properties are no longer required when creating an android integration
• Integrations of type apn have been replaced by the new type ios. The certificate property is no longer required when creating an ios integration
• The new integration type custom has been introduced to replace the functionality of the previous webhooks API suite. All existing webhooks have been automatically upgraded to belong to custom integrations in the API
• The Create Integration API now supports creating multiple instances of a channel (including all SDKs and third-party channels)
• When creating or updating an integration, the displayName property (if passed) now has a minimum length of 1
• The signingKey is now required when creating an integration of type messagebird
• The List Integrations API now uses cursor-based pagination instead of offset-based pagination. See details here (under “Cursor pagination”)
• The types query parameter used to return only integrations of a specific type was replaced by filter[types]

Messages

• The List Messages API now follows the v2 style for cursor-based pagination input and output parameters. See details here (under “Cursor pagination”)
• The List Messages API now uses message IDs instead of timestamps as the pagination cursor

Persistent Menus

Removed in v2

• App-level persistent menu has been removed as a feature of the platform. Integration-level persistent menus can still be configured

Service Accounts

Not migrated to v2 yet

Templates

Not migrated to v2 yet

Users

• The concept of appUser has been renamed to user in all API paths and request/response bodies
• Clients of type android, ios and web are now unified under a single client with type sdk. Existing clients have been converted to devices
• Introduced the concept of devices to replace the per-device tracking of metadata and push notification tokens that used to be handled by SDK clients
• The /channels APIs have been removed in favor of Create/List/Remove Client APIs
• The List Clients API must now be used to fetch the list of clients for a given user, and includes both linked clients and pending clients
• The DELETE /profile endpoint has been renamed to DELETE /personalinformation
• The metadata field now allows unsetting all its values at once with null

• Updated validation on certain fields when creating / updating users:

  • The externalId, givenName, surname, email, avatarUrl and signedUpAt fields are validated in regards to their type and length

Webhooks

• Webhooks are now a sub-property of a new integration type custom. Existing webhooks have been automatically upgraded to belong to custom integrations in the API
• Integrations of type custom can be created with the integrations API /integrations, and require a webhooks array to be passed in the request. Once the custom integration is created, webhooks can be managed with the webhooks API /integrations/:integrationId/webhooks
• Every webhook will be assigned a unique id different from the custom integration id, which can be used to retrieve, update or delete the webhook

Schema changes

App

• The name field has been renamed to displayName
• Removed appToken field

App Key

• The name field has been renamed to displayName

Client

• platform has been renamed to type
• A new status of pending has been introduced to distinguish clients that have not been confirmed yet (previously called pendingClients)
• Removed fields blocked and active which were marked as deprecated in v1.1. Use status instead
• Removed fields id, deviceId, pushNotificationToken and appVersion. These are now properties of the device schema
• The primary property is removed. To know the primary client of a user in relation to a conversation, use the List Participants API. The first item of a participant’s clientAssociations array represents the primary client

Conversation

• Added a new type field. Possible values are personal and sdkGroup
• Removed fields unreadCount and lastRead. Use the equivalent fields of each participant instead
• Introduced new properties metadata, lastUpdatedAt, displayName and description
• appMakerLastRead is now a stringified date instead of a unix timestamp
• appMakerLastRead property was renamed to businessLastRead

Custom Integration Key

• Change name property to displayName

Destination

• type has been renamed to integrationType
• Payloads with a destination object must include either integrationId or integrationType, not both

Device

• Added device schema

Errors

• description has been renamed to title

Integration

• Introduced new types ios, android, and custom
• Removed apn and fcm as supported types, they are now exposed as ios and android

Message

• messageSchema has been renamed to schema
• received is now a stringified date instead of a unix timestamp
• authorId has been renamed to userId and is no longer returned for business messages
• appUser role has been renamed to user
• Removed email field when posting a message. Use avatarUrl instead

• The previous message structure has been re-organized and composed into multiple top-level objects

  • A new author object has been introduced replacing the top-level properties role, name, authorId and avatarUrl. See the Messages section of the v2 API spec for more details
  • id, received, source, destination, metadata, deleted, override, schema, and quotedMessage remain at the root of the message object
  • All other fields have been moved under a content object
• The values api and notifications for a message’s source.type have been changed to api:conversations and api:notifications respectively
• Sub-objects within content no longer include an _id (i.e. actions or items)

Participant

• Added participant schema

Source

• New fields client and device may now be included in webhook payloads when includeFullSource is enabled for the webhook
• originalMessageTimestamp is now a stringified date instead of a unix timestamp

User

• userId has been renamed to externalId
• properties has been renamed to metadata
• Removed top-level fields clients and pendingClients. Use the List Clients API instead
• Removed conversationStarted field
• The user will now contain a profile sub-object that holds the givenName, surname, avatarUrl (this is a new property) and email properties
• The legacy credentialRequired field is no longer accepted

Webhook

• No longer an app-level concept. Webhooks are now a sub-property of integrations of type custom, or integrations created via Sunshine Conversations Connect
• version can have a new value v2
• includeFullAppUser has been renamed to includeFullUser
• includeClient has been renamed to includeFullSource
• Removed support for the wildcard trigger (*). Triggers must all be individually selected
• Updated the schema of all the existing webhooks to pave the way for supporting batching several events in the same webhook call. See the Webhook Payloads of the v2 API spec for more details
• Reorganized and renamed the available triggers. Many v1.x triggers don’t have a v2 equivalent yet, but we plan on adding the most critical ones before v2 is globally available. Note that v1 webhooks can still be used in combination with the v2 API/webhooks if you need a trigger that has not yet been migrated

v1.x trigger	Equivalent v2 trigger	Notes
merge:appUser	user:merge
message:appUser	conversation:message	Subscribes to both user and business messages
message:appMaker	conversation:message	Subscribes to both user and business messages
message:delivery:channel	conversation:message:delivery:channel
message:delivery:failure	conversation:message:delivery:failure
message:delivery:user	conversation:message:delivery:user
conversation:read	conversation:read
typing:appUser	conversation:typing
conversation:start	conversation:create	Now triggers when a conversation is created for any reason, not just in response to a start conversation event. The creationReason may be used to determine why the conversation was created.
conversation:referral	conversation:referral	Now this is triggered for everytime when conversation:referral and conversation:start used to be triggered, except when conversation:create is triggered.
postback	conversation:postback	The message and action linked to a postback event are no longer included in the webhook payload.
client:add	client:add	This event is now triggered for the following reasons: upon initiating a channel link, when logging in the sdk for the first time and when initiating an SDK device with an authCode .
client:block	client:update	The payload will include a reason with the value blocked .
client:remove	client:remove	The payload now includes the conversation whenever it is available.
link:failure	client:remove	The payload will include a reason with either linkCancelled or linkFailure .
link:success	client:update	The payload will include a reason field with the value confirmed .
link:match	client:update	The payload will include a reason field with the value matched .