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>",
}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.
<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, ...],
}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.
<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>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>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 }
]
}
}
}Last updated