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 user properties (see below).

Sunshine Conversations’ native chat SDKs allow developers to act on metadata attached to the message and 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).
const apiInstance = new SunshineConversationsApi.MessagesApi();
const data = new SunshineConversationsApi.MessagePost();
data.author = {
    type: 'business'
};
data.content = {
    type: 'text',
    text: 'Do you currently own a Widget™?',
    actions:
    [{
        type: 'reply',
        text: 'Yes',
        payload: 'yes',
        metadata: {
            productOwner: true,
            otherInfo: 'information'
        }
    },
    {
        type: 'reply',
        text: 'No',
        payload: 'no',
        metadata: {
            productOwner: false,
            otherInfo: 'information'
        }
    }]
};

apiInstance.postMessage(appId, conversationId, data)
    .then(response => /* success */)
    .catch(error => /* failure */);
  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.
 {
    app: { id: '<APP_ID>' },
    webhook: {
        id: "<WEBHOOK_ID>",
        version': 'v2'
    },
    events: [
        {
            id: "<EVENT_ID>",
            createdAt: '2020-10-14T14:29:43.211Z',
            type: "conversation:message",
            payload: {
                conversation: {
                    id: '<CONVERSATION_ID>',
                    type: 'personal'
                },
                message: {
                    id: '<MESSAGE_ID>',
                    received: '2020-10-14T14:29:43.211Z',
                    author: {
                        userId: '<USER_ID>',
                        ...
                    },
                    content: {
                        type: 'text',
                        text: 'No',
                        payload: 'no'
                    },
                    metadata: {
                        otherInfo: 'information',
                        productOwner: false
                    },
                    source: {
                        ...
                    }
                }
            }
        }
    ]
}
  1. In the agent system, there is a service listening specifically for conversation:message 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 filterUserMessages(req, res) {
    const events = req.body.events.filter(
        (e) =>
            e.type === 'conversation:message' && e.payload.message.author.type === 'user' && e.payload.message.metadata
    );

    events.forEach((e) => {
        const userId = e.payload.message.author.userId;
        const appId = req.body.app.id;
        const apiInstance = new SunshineConversationsApi.UsersApi();
        const data = new SunshineConversationsApi.UserUpdateBody();
        data.metadata = e.payload.message.metadata;

        apiInstance
            .updateUser(appId, userId, data)
            .then((response) => console.log(response))
            .catch((error) => console.log(error));
    });
}

Types of Metadata

Action Metadata

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

const apiInstance = new SunshineConversationsApi.MessagesApi();
const data = new SunshineConversationsApi.MessagePost();
data.author = {
    type: 'business'
};
data.content = {
    type: 'text',
    text: 'How was your Messenging experience?',
    actions: [{
        type: 'reply',
        text: '😎',
        payload: '10',
        metadata: {
            npsScore: '10',
            agent: '3450'
        }
    },{
        type: 'reply',
        text: '😐',
        payload: '5',
        metadata: {
            npsScore: '5',
            agent: '3450'

        }
    }]
};

apiInstance.postMessage(appId, conversationId, data)
    .then(response => /* success */)
    .catch(error => /* failure */);

User Metadata

The user object has a key called metadata 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.

const apiInstance = new SunshineConversationsClient.UsersApi();
const data = new SunshineConversationsClient.UserUpdateBody();

data.metadata = {
    newClient: false,
    otherSalientInfo: 'important customer-related information'
};

apiInstance.updateUser(appId, userIdOrExternalId, data)
    .then(response => /* success */)
    .catch(error => /* failure */);

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

Message Metadata

const apiInstance = new SunshineConversationsClient.MessagesApi();
const data = new SunshineConversationsClient.MessagePost();
data.author = {
    type: 'business'
};
data.content = {
    text: 'Just put some vinegar on it',
    type: 'text',
    metadata: {
        important: 'stuff'
    }
};

apiInstance.updateUser(appId, conversationId, data)
    .then(response => /* success */)
    .catch(error => /* failure */);

App Metadata

var apiInstance = new SunshineConversationsClient.AppsApi();
var data = new SunshineConversationsClient.AppUpdateBody();
data = {
    displayName: 'My New App',
    settings: {
        maskCreditCardNumbers: false
    },
    metadata: {
        foo: 'bar'
    }
};

apiInstance.updateApp(appId, data)
    .then(response => /* success */)
    .catch(error => /* failure */);

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.