Using Metadata

Using metadata is a great way to extend your use of the Sunshine Conversations API. You can use it to pass custom data back to the agent system, as well as add it to the user profile by updating the app user properties (see below).

Sunshine Conversations’ native chat SDKs allow developers to act on metadata attached to the message and app user objects to filter and modify messages, implement a custom chat UI, or take any other action based on the custom data provided.

Common Use Case

Adding customer information to the user record based on message actions

It is possible to receive metadata based on a user’s response and then populate the user record with custom properties. This can help “individualize” the user based on your needs.

Example

  1. Ask the user if they already own a company product. This will present as two buttons Yes and No. (See a detailed example of quick replies).
smooch.appUsers.sendMessage({
    appId: '<APP_ID>',
    userId: '<APP_USER_ID>',
    message: {
        text: 'Do you currently own a Widget™?',
        role: 'appMaker',
        type: 'text',
        actions: [
            {
                type: 'reply',
                text: 'Yes',
                payload: 'yes',
                metadata: {
                    productOwner: true,
                    otherInfo: 'information'
                }
            },
            {
                type: 'reply',
                text: 'No',
                payload: 'no',
                metadata: {
                    productOwner: false,
                    otherInfo: 'information'
                }
            }
        ]
    }
});
  1. The user replies and the metadata that is included in the reply is sent back to Sunshine Conversations along with the user’s response. It is then sent along in any webhooks you have set up to receive it in your system. The payload that is received contains the metadata exactly how it was set in the quick reply.
    {
        trigger: 'message:appUser',
        app: { _id: '<APP_ID>' },
        messages:[{
            text: 'Yes',
            metadata: {
                productOwner: true,
                otherInfo: 'information'
            },
            type: 'text',
            role: 'appUser',
            payload: 'yes',
            name: 'Soft Hummingbird',
            _id: '5b4ca3c920a1f900223f7840',
            ...
        }],
        appUser: {
            _id: '<APP_USER_ID>',
            properties: {},
            ...
        }
    }
  1. In the agent system, there is a service listening specifically for message:appuser and checks if there is any metadata included in the message. If there is, it can then set the user properties in the user record.
async function filterAppUserMessages(req, res) {
    const {
        messages,
        appUser: { _id: userId }
    } = req.body;
    const { metadata } = messages[0] || {};

    // Whenever there is metadata, update userProps.
    if (metadata) {
        const newProperties = {
            properties: { ...metadata }
        };

        // Send that back to
        await smooch.appUsers.update(appId, userId, newProperties);
    }
}

Types of Metadata

Action Metadata

Add metadata to each quick reply to store more information on that reply and/or the user.

    smooch.appUsers.sendMessage({
        appId: '<APP_ID>',
        userId: '<APP_USER_ID>',
        message: {
            text: 'How was your Messenging experience?',
            type: 'reply',
            actions: [{
                type: 'reply',
                text: '😎',
                payload: '10',
                metadata: {
                    npsScore: '10',
                    agent: '3450'
                }
            },{
                type: 'reply',
                text: '😐',
                payload: '5',
                metadata: {
                    npsScore: '5',
                    agent: '3450'

                }
            ...
            }]
        }
    }).then(() => {
        // async code
    });

App User Metadata

The app user object has a key called properties to which you can add metadata. This object is preserved for the life of the userId and can be modified and added to as much as needed (within the 4kb restriction). See also the update user API doc.

smooch.appUsers
    .update({
        appId: '<APP_ID>',
        userId: '<APP_USER_ID>',
        props: {
            properties: {
                newClient: false,
                otherSalientInfo: 'important customer-related information'
            }
        }
    })
    .then((response) => {
        // async code
    });

It is also possible for the web SDK to update the user properties via the Smooch.updateUser() method.

Message Metadata

smooch.appUsers
    .sendMessage({
        appId: '<APP_ID>',
        userId: '<APP_USER_ID>',
        message: {
            text: 'Just put some vinegar on it',
            role: 'appMaker',
            type: 'text',
            metadata: {
                important: 'stuff'
            }
        }
    })
    .then((response) => {
        // async code
    });

App Metadata

smooch.apps
    .update('<APP_ID>', {
        name: 'My New App',
        settings: {
            maskCreditCardNumbers: false
        },
        metadata: {
            foo: 'bar'
        }
    })
    .then((response) => {
        // async code
    });

SDKs and Metadata

The Sunshine Conversations SDKs can also use/act on and modify message metadata using delegate methods.

Adding metadata

  • iOS: Use the conversation:willSendMessage delegate method.
  • Android: Use the beforeSend delegate method.
  • Web: Use the beforeSend delegate method.

Using metadata

  • iOS: Use the conversation:didReceiveMessages delegate method.
  • Android: Use the onMessagesReceived delegate method.
  • Web: Use the message:received event.