DOCSEARCHbyAlgolia
Submit Docs

Smooch API Reference

website·Indexed 38 days ago

https://docs.smooch.io/guide/v1/

Technical documentation for the Smooch SDK, featuring comprehensive API references for Android and iOS. Includes detailed class hierarchies, interfaces, and enums for core messaging functionality, conversation list management, and UI components such as NotificationActivity and SKTMessageItem.

Tokens
65K
Snippets
411
Records
585
Agent score
69%

What's inside Smooch

  1. Overview of Smooch iOS SDK Core Classes

    The Smooch iOS SDK allows developers to integrate multi-channel messaging directly into an iOS application. The SDK architecture relies on several key classes to manage the conversation lifecycle:

    • SDK Initialization: The primary SDK class (referenced as the initialization class) is used to start the SDK and display the conversation interface.
    • Configuration: A settings object is passed to the _initWithSettings:completionHandler: method to configure the SDK with essential parameters such as the appId, accent color, and notification display time.
    • User Properties: A specific class is provided to attach custom user properties to conversations, allowing for personalized user data tracking.
    • Message Management: A dedicated class handles the sending and retrieval of messages and supports a delegate pattern to respond to messaging events.
    • Message Data: A message-specific class provides metadata for individual messages, including the message text and the author's name.

  2. Access analytics and customer interfaces in Sunshine Conversations

    Sunshine Conversations does not provide a native customer-facing interface or built-in analytics. Instead, it integrates with external business systems (e.g., Front, HelpScout) where performance analytics and communication interfaces are managed. Users can also explore the integrations directory for third-party analytics tools.

  3. Handle notification delivery webhooks

    v1
    The notification:delivery:channel webhook reports the success of handing off a notification to a channel (e.g., MessageBird, Twilio, or WhatsApp). The payload includes a matchResult object that provides details about the appUser, conversation, and client associated with the notification.
    {
    "trigger": "notification:delivery:channel",
    "destination": {
        "type": "whatsapp",
        "integrationId": "5b354bdab42a1d61143ccc26",
        "destinationId": "+15145555555"
    },
    "isFinalEvent": false,
    "notification": { "_id": "e361392f-7dd3-4bdb-8844-d0d002ac7f72" },
    "matchResult": {
        "appUser": { "_id": "5b354bdab42a1d61143ccc26" },
        "conversation": { "_id": "075354bdab42a1d61143cc362" },
        "client": { "id": "e6eb2653-e143-4c1a-be58-bdd6afgh35ff", "platform": "whatsapp" }
    }
}

  4. Interact with a user conversation using the Conversation interface

    The Conversation interface (extending ConversationDetails) is used to interact with a user's conversation in the Android SDK. Before performing any actions on a conversation, it must be made active using Smooch.loadConversation(String, SmoochCallback). Additionally, Smooch.init(Application, Settings, SmoochCallback) must be called before retrieving any conversation object.

  5. Understand how the Sunshine Conversations Slack integration works

    The Slack integration uses a two-tier channel system:

    1. Dispatch Channel: A designated channel that notifies your team whenever a new conversation is created with a user. This channel cannot be used to reply to customers directly.
    2. Conversation Channels: Separate channels created for each user, prefixed with #sk-. These are where the actual conversations between your team and the user take place. Team members can join these by clicking the link provided in the dispatch channel.

  6. Get conversation and participant details

    The ConversationDetails interface and Participant class provide metadata about conversations:

    • ConversationDetails.getMessages(): Returns the list of messages in the conversation.
    • ConversationDetails.getParticipants(): Returns the list of participants.
    • ConversationDetails.getLastUpdatedAt(): Returns the date the conversation was last updated.
    • ConversationDetails.getMetadata(): Returns an optional flat object containing additional conversation properties.
    • Participant.getLastRead(): Returns the date when the participant last read messages in the conversation.

  7. Handle message delivery failure errors in webhooks

    v1

    In message:delivery:failure events, the error object provides details about why a message failed to deliver. If an error cannot be categorized, the code field will be set to uncategorized_error. Otherwise, a specific error code is provided.

    Error Schema Fields:

    • code: A string representing the error code.
    • underlyingError (optional): An object containing raw error data returned by the destination channel.
    • message (optional): A human-readable description of the error.

  8. Detect when the conversation view controller is presented

    The willShowViewController method is called during the viewWillAppear: phase of the conversation view controller, notifying the delegate that the conversation is about to be presented.
    - (void)conversation:(nonnull SKTConversation *)conversation willShowViewController:(id)viewController;

  9. Handle Smooch push notifications with FcmService

    The io.smooch.core.FcmService class extends FirebaseMessagingService and is used to receive push notification messages from Firebase Cloud Messaging (FCM). This service is automatically registered when using the AAR library.

  10. Understand messaging channels in Sunshine Conversations

    Sunshine Conversations distinguishes between 'messaging channels' and 'business systems'. A messaging channel is any end-user facing interface that customers use to reach a business, such as Web Messenger, Mobile Messenger, Facebook Messenger, or LINE.

  11. Manage Sunshine Conversations account closure and team access

    Sunshine Conversations does not currently support formal account closure; instead, users should disable integrations from the overview page. Additionally, the platform does not support individual team member accounts for configuration management; teammates must share the same account or be added via supported business systems like Slack or HelpScout.

  12. Interact with the current user's conversation using SKTConversation

    The SKTConversation class provides the interface to interact with the current user's conversation. To obtain a shared instance, use [Smooch conversation]. Note that +initWithSettings:completionHandler: must be called before retrieving the shared conversation object.