Embedding the Inbox

This guide focuses specifically on embedding the Recrubo Inbox component into your application using iframes, which involves essential steps for authentication and initialization.

You can find the full list of available components in the Available Embeddables section.

You can find the component reference for the Recrubo Inbox here.

Authentication

To grant a user access to the functionality within the iframes an authentication token is required. Ensure your systems user has a corresponding user record within the Recrubo system see User for more information.

Using the following request you can create/retrieve an authentication token for the user by posting to the following path: public/v2/embed/authenticate. This route expects your request to have the following body:

{
    "userId": "<recrubo_user_record_id>",
    "originUrl": "<origin_of_iframe_request>",
}

When requesting an authentication token for a user this should always be done from a server side application so the API_KEY never ends up on the client.

Initialization

Now that you have acquired an authentication token you can initialize the inbox or any other Recrubo iframe component. Initialization is carried out using the postMessage API, which allows your application to communicate the token and settings to Recrubo's app.

If you are working with our staging environment, replace the following:

https://api.recrubo.app/* -> https://api-staging.recrubo.app/* https://recrubo.app/* -> https://demo.recrubo.app/*

<iframe id="inboxFrame" src="https://api.recrubo.app/public/v2/embed/component/inbox"></iframe>

<!-- A script to communicate the user token as soon as the iframe is loaded -->
<script type="text/javascript">
const inbox = document.querySelector('#inboxFrame')

inbox.onload = (evt) => {
    const inboxSettings = {
        action: 'initialize',
        token: 'XX-XX-XX-XX-XX'
    }

    // second argument is the origin of the target window, in this case the production url of the Recrubo webapp
    inbox.contentWindow.postMessage(inboxSettings, 'https://recrubo.app')
}
</script>

Even though the iframe source points to api.recrubo.app, the second argument in postMessage should be recrubo.app since the components in the api subdomain redirect to our main domain which serves the webapp.

Settings

The Recrubo Inbox component can be configured using the settings key in the initialization object. The settings object contains a key per Component listed in Available Embeddables.

Theme and Styling

Aside from component specific settings you can override almost all colors used within our application, you do this by providing the theme key in the first level of the settings object. The default theme is as follows:

const theme = {
    primaryLight: '#79addc',
    primary: '#0267c1',
    primaryDark: '#0a365c',
    secondary: '#388bd9',
    secondaryLight: '#f0f4f9',
    tertiary: '#e89900',
    accent: '#9c27b0',
    dark: '#1d1d1d',
    menuBase: '#0b71d0',
    positive: '#21ba45',
    negative: '#e5513c',
    negativeDark: '#ffbfbf',
    info: '#31ccec',
    warning: '#f2c037',

    builderStepBackground: '#D6E6F5',
    builderStepSelectedBorder: '#0267c1',
    builderStepBackgroundHover: '#e0ecf7',

    builderEndStepBackground: '#fcf2e0',
    builderEndStepSelectedBorder: '#9b6600',
    builderEndStepBackgroundHover: '#f6eacb'
}

Example

This example overrides some of the default settings provided for the Inbox as well as a method to change the active conversation. Looking at the settings we disable the conversation select panel on the left (showTabPanel) as well as the candidate information on the right (candidateDetails). We also disable all functions that would allow the user to send a message or continue/pause the ongoing conversation. This is effectively a read-only mode of a single conversation. We also set the primary color in the theme to a bright red.

<iframe id="inboxFrame" src="https://api.recrubo.app/public/v2/embed/component/inbox"></iframe>

<script type="text/javascript">
const inbox = document.querySelector('#inboxFrame')

inbox.onload = (evt) => {
    const inboxSettings = {
        action: 'initialize',
        token: 'XX-XX-XX-XX-XX',
        settings: {
            theme: {
                primary: '#ff0000'
            },
            inbox: {
                showTabPanel: false,
                showSendMessage: false,
                showCandidateDetails: false,
                showPauseChatbot: false
            }
        }
    }

    inbox.contentWindow.postMessage(inboxSettings, 'https://recrubo.app')
}
</script>

Actions

Like initialize there are more actions to execute; some of these are global but most will be component specific.

These actions are available with every component embedded through our V2 API:

• updateSettings

• getSettingsFor

• getActionsFor

Default actions, which are available on every component, are structured as follows:

const globalActionTemplate = {
    action: 'action-name',
    token: 'XX-XX-XX-XX-XX',
    arguments: [arg1, arg2, ...],
}

And component specific actions like so:

const specificActionTemplate = {
    action: {
        component: 'component-identifier',
        name: 'action-name'
    },
    token: 'XX-XX-XX-XX-XX',
    arguments: [arg1, arg2, ...],
}

Notice that all default actions are specified as a string value of the action key. When calling component specific actions this should be an object.

The arguments key needs to be present in the form of an array, even if there are no arguments to pass or just one.

Update Settings

The updateSettings action is the exact same as the initialize action in terms of payload. However behaviour wise it does not reauthenticate the user through their token, nor set all unspecified settings to their default values.

This action retains the already set settings and only updates the settings provided.

The postMessage payload is the exact same as the initialize action.

<script type="text/javascript">
const iframe = document.querySelector('#recruboIframe')

const updateSettingsPayload = {
    action: 'updateSettings',
    token: 'XX-XX-XX-XX-XX',
    settings: {
        theme: {
            primary: '#ff0000'
        },
        component: {
            settingA: true,
            settingB: false
        }
    }
}

iframe.contentWindow.postMessage(updateSettingsPayload, 'http://recrubo.app')
</script>

Get Settings For

Soon to be implemented

This is more of a debugging tool if anything. You provide the component identifier you are interested in as the first and only argument and then the component will respond by posting a message back containing the default settings for the requested component.

<script type="text/javascript">
const iframe = document.querySelector('#recruboIframe')

const getSettingsForPayload = {
    action: 'getSettingsFor',
    token: 'XX-XX-XX-XX-XX',
    arguments: ['inbox']
}

iframe.contentWindow.postMessage(getSettingsForPayload, 'http://recrubo.app')
</script>

Refer to the events section of this page to see how to receive the response.

The response posted back to the calling window will contain 3 keys, component, current and default.

Where current will contain the full settings object at the time of calling, and default contains the default settings.

// response for the inbox component
{
    component: 'inbox',
    current: {
        showTabPanel: false,
        showTabAssigned: true,
        showTabOpen: true,
        showTabClosed: true,
        showTabLive: true,
        showTopBar: true,

        showCandidateDetails: false,
        showCandidateDetailsEdit: true,
        showCandidateAssigneeEdit: true,
        showCandidateLabelsAdd: true,
        showCandidateNotesAdd: true,

        showSendMessage: true,
        showAddTemplateButton: true,
        showConversationSearch: true,
        showConversationFilter: true,
        showPauseChatbot: false,

        startingCandidate: 'some-candidate-id'
    },
    default: {
        showTabPanel: true,
        showTabAssigned: true,
        showTabOpen: true,
        showTabClosed: false,
        showTabLive: true,
        showTopBar: true,

        showCandidateDetails: false,
        showCandidateDetailsEdit: true,
        showCandidateAssigneeEdit: true,
        showCandidateLabelsAdd: true,
        showCandidateNotesAdd: true,

        showSendMessage: true,
        showAddTemplateButton: true,
        showConversationSearch: true,
        showConversationFilter: true,
        showPauseChatbot: false,

        startingCandidate: null
    }
}

Get Actions For

Soon to be implemented

Much like getDefaultFor this will mostly be used for debugging purposes and posts a message containing information about the actions available for the specified component, this again takes only one argument being the component identifier

<script type="text/javascript">
const iframe = document.querySelector('#recruboIframe')

const getSettingsForPayload = {
    action: 'getSettingsFor',
    token: 'XX-XX-XX-XX-XX',
    arguments: ['inbox']
}

iframe.contentWindow.postMessage(getSettingsForPayload, 'http://recrubo.app')
</script>

Refer to the events section of this page to see how to receive the response.

The posted response contains 2 keys; component and actions. Where actions is an object containing all component specific actions (therefor excluding the default actions) with their name as the key.

// example response for the inbox component
{
    component: 'inbox',
    actions: {
        setConversation: {
            description: 'Change the candidate displayed to the user',
            arguments: [
                { name: 'conversationId', type: 'string', index: 0 }
            ]
        }
    }
}