Changelog: Twilio Chat iOS SDK

Latest releases for the Programmable Chat iOS SDK

We recommend using these links in your projects. As we patch bugs, these links will automatically be updated with the fixes.

Programmable Chat iOS v2.0

Access Manager iOS v1.0.0

Migrating from Beta to GA

Programmable Chat is now in GA. A number of breaking changes were introduced as part of the GA release. To see what has changed and to migrate from the latest Beta SDK to the new GA SDK, please read the GA Migration Guide for iOS.

Migrating from IP Messaging to Programmable Chat

Programmable Chat is the new name of what was previously called IP Messaging. If you are an existing IP Messaging user, you will want to follow the Migration Guide for iOS.

If you are looking for the archived IP Messaging iOS changelog, it can be found here.

Change Logs

Links are provided to specific patch versions here. We don't recommend using these links unless you have a specific need for a certain patch of a release.

Programmable Chat iOS 2.0.0 (September 18, 2017)

Important: The behavior of not-present optional data, such as friendlyName, uniqueName, etc, has changed with this release of Programmable Chat iOS to match the REST API and improve usability in Swift. We no longer return an empty string on missing data, returning instead nil. If you are relying on the previous behavior of empty string to be able to directly display these values in your application, you will need to check for the value instead.

With 2.x, we are moving Programmable Chat iOS releases to the global CocoaPods repository. We will no longer be posting non-beta releases for this SDK to the location. If you already have the global CocoaPods source in your Podfile no changes are necessary. If you do not have it, you will need to add source '' or remove the Twilio specific source line. No changes are necessary if you use manual integration of this SDK.


  • Added Multimedia Messaging (beta) API (see Media Support for more information). Note: Sending media messages on existing instances requires adding a new permission in your channel roles.
  • With the addition of support for iOS 11, we are deprecating support for iOS 8 in Programmable Chat iOS 2.x
  • chatClient:channel:updated: will no longer notify on TCHChannelUpdateSynchronizationStatus changes - see the chatClient:channel:synchronizationStatusUpdated: delegate call for these updates
  • Creation of new messages is no longer a two-step process, createMessageWithBody: is deprecated from TCHMessages. You now build a new message using the TCHMessageOptions object and send with sendMessageWithOptions:completion:


    TCHMessage *message = [channel.messages createMessageWithBody:@"hello"];
    [channel.messages sendMessage:message completion:^(TCHResult *result) { }];


    TCHMessageOptions *options = [[TCHMessageOptions new] withBody:@"hello"];
    [channel.messages sendMessageWithOptions:options completion:^(TCHResult *result, TCHMessage *message) { }];
  • Nullability hints and behavior have changed for the sdk. SDK methods will accept either nil or an empty string as an argument for clearing data but will consistently return nil when there is no data set for an optional field to improve usability. This applies to dates and user, channel and message attributes as well.

Interface Changes

Changes to nullability hints throughout entire public interface.


  • TCHChannelUpdateSynchronizationStatus (REMOVED - see chatClient:channel:synchronizationStatusUpdated:)

TCHMessageType (ADDED)

  • TCHMessageTypeText
  • TCHMessageTypeMedia

TCHMediaOnStarted (ADDED)

TCHMediaOnProgress (ADDED)

TCHMediaOnCompleted (ADDED)


  • messageType (ADDED)
  • mediaSid (ADDED)
  • mediaSize (ADDED)
  • mediaType (ADDED)
  • mediaFilename (ADDED)
  • -hasMedia (ADDED)
  • -getMediaWithOutputStream:onStarted:onProgress:onCompleted:completion: (ADDED)


  • -createMessageWithBody: (REMOVED)
  • -sendMessage:completion: migrated to -sendMessageWithOptions:completion: - completion now provides a handle to the new TCHMessage

Access Manager iOS 1.0.0 (September 18, 2017)


With 1.x, we are moving Access Manager releases to the global CocoaPods repository. We will no longer be posting non-beta releases for this SDK to the location. If you already have the global CocoaPods source in your Podfile no changes are necessary. If you do not have it, you will need to add source '' or remove the Twilio specific source line. No changes are necessary if you use manual integration of this component.

Programmable Chat iOS 1.0.8 (September 15, 2017)


  • Resolved issue when updating token on chat client after token expiry.

Programmable Chat iOS 1.0.7 (August 9, 2017)


  • Performance enhancements
  • Resolved possible crash during client creation if initialization takes an especially long time

Programmable Chat iOS 1.0.6 (July 25, 2017)


  • Completion handler for TCHChannel's join method will be delayed until the channel is fully synchronized, guaranteeing availability of members and messages objects.

Programmable Chat iOS 1.0.5 (July 17, 2017)


  • Fixed issues related to thread management, which in many cases should lead to significant performance gains.
  • Fixed crashes possible during client shutdown.

Programmable Chat iOS 1.0.4 (June 21, 2017)


  • Fix bug where TCHChannel’s chatClient:channel:synchronizationStatusUpdated: delegate method was not called.
  • Added channel synchronization status method to chat client delegate.
  • Trigger channel’s synchronization status delegate method every time a channel delegate is assigned for convenience.
  • Resolved issue where TCHMessages' getLastMessagesWithCount:completion: could hang.

Programmable Chat iOS 1.0.3 (June 8, 2017)


  • Fixed a bug whereby client initialization did not completed correctly - i.e. no success nor failure callback was received for client creation. This was for cases not fixed in the previous release.
  • Fixed an issue whereby the SDK could crash in some cases when creating a new Chat Client instance.

Programmable Chat iOS 1.0.2 (June 2, 2017)


  • Fixed a bug whereby client initialization did not completed correctly - i.e. no success nor failure callback was received for client creation
  • Fixed a bug whereby some commands did not correctly complete - i.e. no success callback nor failure was received

Programmable Chat iOS 1.0.1 (May 24, 2017)


  • Fixed a bug whereby after a call to the client's shutdown sometimes caused New Message push registrations to be lost for the endpoint.

Programmable Chat iOS 1.0.0 (May 2, 2017)




  • userInfo migrated to user
  • chatClientWithToken:properties:delegate: migrated to chatClientWithToken:properties:delegate:completion:
  • updateToken: migrated to updateToken:completion:
  • users (ADDED)
  • registerWithToken: migrated to registerWithNotificationToken:completion:
  • deregisterWithToken: migrated to deregisterWithNotificationToken:completion:
  • handleNotification: migrated to handleNotification:completion:

TCHTwilioClientCompletion (ADDED)


  • synchronizationStrategy (REMOVED)
  • initialMessageCount (REMOVED)


  • chatClient:connectionStateChanged: renamed to chatClient:connectionStateUpdated:
  • chatClient:synchronizationStateChanged: renamed to chatClient:synchronizationStateUpdated:
  • chatClient:channelChanged: migrated to chatClient:channel:updated:
  • chatClient:channel:synchronizationStatusChanged:
  • chatClient:channel:memberChanged: renamed to chatClient:channel:member:updated:
  • chatClient:channel:messageChanged: migrated to chatClient:channel:message:updated:
  • chatClientToastSubscribed: (REMOVED)
  • chatClient:toastRegistrationFailedWithError: (REMOVED)
  • chatClient:toastReceivedOnChannel:message: migrated to chatClient:notificationNewMessageReceivedForChannelSid:messageIndex:
  • chatClient:user:updated: (ADDED)
  • chatClient:userSubscribed: (ADDED)
  • chatClient:userUnsubscribed: (ADDED)


  • synchronizeWithCompletion: (REMOVED)

TCHChannelDelegate (CHANGED)

  • chatClient:channelChanged: migrated to chatClient:channel:updated:
  • chatClient:channel:synchronizationStatusChanged: renamed to chatClient:channel:synchronizationStatusUpdated:
  • chatClient:channel:memberChanged: renamed to chatClient:channel:member:updated:
  • chatClient:channel:messageChanged: migrated to chatClient:channel:message:updated:
  • chatClient:channel:member:userInfo:updated: migrated to chatClient:channel:member:user:updated:
  • chatClient:channel:member:userSubscribed: (ADDED)
  • chatClient:channel:member:userUnsubscribed: (ADDED)


  • userChannelsWithCompletion: (REMOVED)
  • subscribedChannels (ADDED)
  • userChannelDescriptorsWithCompletion: (ADDED)
  • publicChannelsWithCompletion: renamed to publicChannelDescriptorsWithCompletion:

TCHChannelUpdate (ADDED)


  • TCHChannelStatusUnknown (ADDED)

TCHChannelPaginator -> TCHChannelDescriptorPaginator (RENAMED)

TCHChannelPaginatorCompletion (REMOVED)


  • userInfo migrated to identity
  • userDescriptorWithCompletion: (ADDED)
  • subscribedUserWithCompletion: (ADDED)

TCHMemberUpdate (ADDED)

TCHMessageUpdate (ADDED)


  • resultCode (ADDED)
  • resultText (ADDED)


  • userDescriptorsForChannel:completion:
  • userDescriptorWithIdentity:completion:
  • subscribedUserWithIdentity:completion:
  • subscribedUsers


  • isSubscribed (ADDED)
  • unsubscribe (ADDED)

TCHUserInfo -> TCHUserDescriptor (MIGRATED)

  • subscribeWithCompletion: (ADDED)
  • setAttributes:completion: (REMOVED)
  • setFriendlyName:completion: (REMOVED)

TCHUserCompletion (ADDED)

TCHUserDescriptorCompletion (ADDED)

TCHUserDescriptorPaginatorCompletion (ADDED)

TCHUserInfoUpdate -> TCHUserUpdate (CHANGED)

Programmable Chat iOS 0.17.3 (May 19, 2017)


  • Fix for absence of channel added delegate when a private channel is created from a separate endpoint.

Programmable Chat iOS 0.17.2 (April 3, 2017)


  • The iOS SDK now supports badging when enabled on your Chat instance for clients you have registered for push notifications. Badges will indicate the number of unread 1:1 channels the user has.
  • Resolved an issue where the client creation call and updateToken calls may perform a network operation on the calling thread, blocking it. These operations now occur in the background and the calls once again return immediately.
  • Introduced callback for badge updates on iOS. This delegate method will be called as a result of the chat library processing a notification via TwilioChatClient’s handleNotification: method where the badge count updates. When your application is foregrounded, iOS will not automatically update the springboard badge count on its own so your application must manually update it. If your application receives its badge updates through a mechanism other than Twilio, you can omit this delegate method and handle this event in another way. See chatClient:notificationUpdatedBadgeCount: in the SDK docs or [demo application] for more information including a sample implementation.

Programmable Chat iOS 0.17.1 (February 23, 2017)


  • The endpoint_id identifier specified in access tokens is now automatically generated and persisted in the keychain. The following should be observed with this change:
    • endpoint_id is no longer a required identifier in your generated access tokens, you may omit it from this build forward
    • endpoint_id will be ignored if specified with your access token
    • When running in the iOS simulator only, the automatically generated endpoint_id may not persist between runs to the simulator keychain without this [work-around]
  • If a client is initially created with an invalid access token, creation will fail and nil will be returned for the client instance
  • Resolved an issue where APNS registrations for the user may be lost after shutdown of the client. Ensure when you are logging a user fully out of an application that registers for push notifications you call deregisterWithToken: with the device's token prior to shutdown to prevent messages continuing to be delivered to the device.
  • Resolved an issue where crashes could occur during client shutdown, in particular while in the background
  • Security enhancements

Access Manager iOS 0.1.3 (February 14, 2017)


  • Resolved issue where invalid tokens could cause a crash when foregrounding the application after being in the background.

Programmable Chat iOS 0.16.1 (January 30, 2017)


  • Resolved potential incompatibility with other Twilio SDKs in the same project
  • Fix for channel added events not occurring with synchronization strategy .ChannelList

Access Manager iOS 0.1.2 (December 6, 2016)


  • Resolved issue with Framework short version string

Programmable Chat iOS 0.16.0 (November 21, 2016)


  • TwilioIPMessagingClient -> TwilioChatClient
  • All TWM class prefixes to TCH
  • AccessManager is removed from the SDK and provided as a stand-alone helper library
  • Channels are now split between Public and User channels list.
    • Unjoined public channels no longer fire channel added/removed/changed events
  • Migration to asynchronous-only access to most entities within system
    • Includes addition of paging to User and Public channels list as well as channel Members


TwilioChatClient (CHANGED)

  • updateToken method


  • createdBy property
  • memberWithIdentity method
  • getUnconsumedMessagesCountWithCompletion:
  • getMessagesCountWithCompletion:
  • getMembersCountWithCompletion:


  • allObjects
  • userChannelsWithCompletion:
  • publicChannelsWithCompletion:
  • channelWithId:
  • channelWithUniqueName:
  • channelWithSidOrUniqueName:completion:

TCHChannelDescriptorPaginatorCompletion (ADDED) TCHChannelPaginatorCompletion (ADDED) TCHMemberPaginatorCompletion (ADDED) TCHChannelCompletion (ADDED)

TCHChannelDescriptor (ADDED) TCHChannelDescriptorPaginator

TCHChannelPaginator (ADDED)

TCHMemberPaginator (ADDED)


  • allObjects
  • membersWithCompletion:


  • allObjects
  • getMessageWithIndex:
  • getMessageWithIndex:completion:
  • messageForConsumptionIndex:
  • messageForConsumptionIndex:completion:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.