UI/iFrame integrations

JavaScript API

App methods

reload()

Reloads the iframe.

search(text)

Initiates a new search.

alert(options)

Displays an error modal. It only has a “Got it” action.

navigate(options)

Navigate to a conversation.

on(event, callback, options)

Registers an event callback.

openForm(data)

Displays a form popup. Multiple forms can be stacked over each other.
=> Promise(Object)
    ⮑ Resolves with Field objects

closeForm()

Closes the last open form popup.

openSelf()

Opens the integration sidebar if closed and selects the integration.

closeSelf()

Closes the integration sidebar if opened.

openURL(url)

Opens the URL in a new tab on desktop. Opens in native browser or in-app browser depending on user settings on mobile.

openContextMenu(data)

Opens a context menu

setActions(actions)

Actions are available throughout the app as an option in context menus or swipe action.

setAsUtility()

Mark the integration as an utility integration. It will not display the iframe in the integration sidebar. Useful for integrations that only display actions in context menus.

setPermissions(permissions)

Make Missive requests certain media permissions. Required on macOS for integrations that require Camera or Microphone usage. You may need to reload the integration once Missive has been granted access.

storeGet(key)

Retrieve data that has been previously stored using storeSet. The data is persistent between page reloads and app reloads.

storeSet(key, data)

Store data that remains consistent between page reloads and app reloads.

Example usage:

const userData = {
  id: '1234',
  name: 'John Doe',
  email: 'john.doe@example.com'
};

Missive.storeSet('userData', userData);

Missive.storeGet('userData')
  .then(data => {
    console.log(data);
  });

respondToMessage(data)

The respondToMessage method can be used to send commands to the Command Bar inside the Action callback of the command_bar context.

Example usage:

Missive.setActions([
  {
    label: `My command bar action`,
    contexts: ['command_bar'],
    placeholder: "Command Bar's input placeholder",
    callback: async (event, messageId) => {
      if (event.type === 'load') {
        Missive.respondToMessage(messageId, {
          commands: [
            {
              id: 'command-id',
              iconUrl: 'https://via.placeholder.com/64',
              label: 'command-text',
              payload: {},
              closeOnExecute: true,
            },
          ],
        })

        return
      }

      if (event.type === 'search') {
        const commands = searchCommands(event.value)
        Missive.respondToMessage(messageId, { commands })

        return
      }

      if (event.type === 'execute') {
        executeCommand(event.payload)

        return
      }
    },
  },
])

fetchConversations(ids)

Fetches attributes for the given conversation IDs.
=> Promise(Array)
    ⮑ Resolves with Conversation objects

Example usage:

Missive.on('change:conversations', (ids) => {
  Missive.fetchConversations(ids).then((conversations) => {
    if (conversations.length != 1) {
      // Do nothing if multiple conversations are selected.
      return
    }

    var message = conversations[0].latest_message
    if (!message || !message.from_field) {
      // Do nothing if conversation has no message (only chat comments) or if
      // message has no From field.
      return
    }

    var from = message.from_field
    console.log('Message from:', from.name, from.address)
    console.log('Message subject:', message.subject)
  })
})

Available attributes for conversations:

// Conversation
{
  id: '2b3db130-e94e-43fa-970a-63bae8cb10ee',
  color: '#ff0000',
  subject: 'Keep it secret, keep it safe',
  users: [ /* Array of User objects */ ],
  assignees: [ /* Array of User objects */ ],
  authors: [ /* Array of AddressField object */ ],
  messages_count: 1,
  messages: [/* Array of Message object (see below) */],
  latest_message: {
    id: 'daa5e30e-490b-4d54-ba7b-63f19b529ab7',
    from_field: { /* AddressField */ },
    to_fields: [ /* Array of AddressField objects */ ],
    cc_fields: [ /* Array of AddressField objects */ ],
    bcc_fields: [ /* Array of AddressField objects */ ],
    reply_to_fields: [ /* Array of AddressField objects */ ],
    subject: 'Keep it secret, keep it safe',
    preview: 'Where is it? --Gandalf',
    body: '<p>Where is it?</p><p>--<br>Gandalf</p>',
    delivered_at: 1550698870,
  },
  link: 'https://mail.missiveapp.com/#inbox/conversations/37c8d757-2a20-45f6-9aa1-dbe815d27cb0',
}

fetchMessages(ids)

Fetches attributes for the given message IDs.
=> Promise(Array)
    ⮑ Resolves with Message objects

Available attributes for messages:

// Message
{
  id: 'daa5e30e-490b-4d54-ba7b-63f19b529ab7',
  from_field: { /* AddressField */ },
  to_fields: [ /* Array of AddressField objects */ ],
  cc_fields: [ /* Array of AddressField objects */ ],
  bcc_fields: [ /* Array of AddressField objects */ ],
  reply_to_fields: [ /* Array of AddressField objects */ ],
  subject: 'Keep it secret, keep it safe',
  preview: 'Where is it? --Gandalf',
  body: '<p>Where is it?</p><p>--<br>Gandalf</p>',
  delivered_at: 1550698870,
}

fetchUsers()

Fetches attributes for all users.
=> Promise(Array)
    ⮑ Resolves with User objects

// User
{
  id: '6b52b6b9-9b51-46ad-a4e3-82ef3c45512c',
  avatar_url: 'https://gravatar.com/avatar/014bcc1f9c5920c658a198e6649cd20b',
  email: 'frodo@fellowship.org',
  first_name: 'Frodo',
  last_name: 'Baggins',
  display_name: 'You',
  me: true,
}

fetchLabels()

Fetches attributes for all shared labels.
=> Promise(Array)
    ⮑ Resolves with Label objects

// Label
{
  avatar_url: "https://…",
  color: "#000"
  description: null
  emoji: null
  id: "93c1010b-8a43-4325-a2af-b3f2d7bedfd3"
  name: "GitHub"
  organization_id: "555abd43-5d6c-426b-bcb0-84180689bc86"
  parent_id: null
  share_with_organization: true
  share_with_team_id: null
  share_with_user_ids: []
  type: "shared_label"
  visibility: "organization"
}

Conversation methods

createConversation(options)

Creates a new conversation.

archive()

Archives current conversation.

trash()

Trashes current conversation.

moveToInbox()

Moves current conversation to Inbox.

comment(body)

Creates a comment in the current conversation.

createTask(body, completed)

Creates a task in the current conversation.

addLabels(labelIds)

Adds labels to the current conversation.

removeLabels(labelIds)

Removes labels from the current conversation.

close()

Closes the current conversation.

reopen()

Reopens the current conversation.

assign(userIds)

Assigns users to the current conversation.

addAssignees(userIds)

Adds assignees to the current conversation.

removeAssignees(userIds)

Removes assignees from the current conversation.

setColor(color)

Sets current conversation color.

setSubject(subject)

Sets current conversation subject.

Composer methods

compose(options)

Creates a new draft in a new conversation.

composeInConversation()

Creates a new draft in current conversation.
Same params as #compose

reply(options)

Replies to current conversation latest message.

forward(options)

Forwards current conversation latest message.

insertText(text)

Inserts content as text in the currently selected composer.

insertHtml(text)

Inserts content as HTML in the currently selected composer.

Helper methods

isToday(date)

Tests if date is today.
=> Boolean

isTomorrow(date)

Tests if date is tomorrow.
=> Boolean

isPast(date)

Tests if date is past.
=> Boolean

isInLessThan(date, options)

Tests if date is in less than X hours / minutes / seconds.
=> Boolean

getMonth(index, options)

Returns the month name of a given index.
=> String

getEmailAddresses(conversations)

Returns all the email addresses found in conversations.
=> Array(AddressField)

getPhoneNumbers(conversations)

Returns all the phone numbers found in conversations.
=> Array(PhoneField)

formatTimestamp(timestamp, options)

Formats given timestamp.
=> { date, formatted }

formatDate(string, options)

Formats given date.
=> { date, formatted }

formatContact(contact)

Formats given contact.
=> { letters, formatted }

capitalize(string)

Capitalizes given string.
=> String

classNames(classes)

Converts object to CSS class names.
=> String

writeToClipboard(text)

Write text to the user’s clipboard.

Events

main_action

Triggered when user press the “Integrations main action” shortcut.
=> ()

message_sent

Triggered when a user sends a message, or when a message is scheduled to be sent. Be careful as once triggered, the user can still cancel the delivery of the message within a short period (Undo).
=> (id)

change:conversations

Triggered when selected conversation(s) change.
=> (ids)

change:users

Triggered when users change.
=> ()

Use #fetchUsers to fetch users data.

Glossary

Action

{ label: 'New task', callback: () => {} }
{ label: 'Forward', contexts: ['message'], callback: () => {} }

AddressField

{ address: 'frodo@missiveapp.com', name: 'Frodo Baggins' }
{ address: 'sam@missiveapp.com' }

FormField

{ type: 'input', data: { … }, options: { … } }
{ type: 'calendar', data: { … } }

FormField(type:input)

{ type: 'input', data: { … }, options: { … } }

FormField(type:textarea)

{ type: 'textarea', data: { … } }

FormField(type:select)

{ type: 'select', data: { … } }

FormField(type:calendar)

{ type: 'calendar', data: { … } }

FormField(type:duration)

{ type: 'duration', data: { … } }

FormField(type:progress)

{ type: 'progress', data: { … } }

FormField(type:html)

{ type: 'html', data: { … } }

FormComment

{
  content: 'I will take the Ring, though I do not know the way.',
  authorName: 'Frodo Baggins',
  authorAvatar: 'https://gravatar.com/avatar/014bcc1f9c5920c658a198e6649cd20b',
}

FormNote

{ message: '✓ Completed on Feb 18' }
{ message: 'View on Missive', url: 'https://missiveapp.com' }

FormButton

{ type: 'cancel', label: 'Cancel' }
{ type: 'submit', label: 'Create' }

Option

{ label: 'My Project', value: 12345 }
{ label: 'My Tag', value: 54321, color: '#F00' }

PhoneField

{ phoneNumber: '+11231231234', name: 'Frodo Baggins' }
{ phoneNumber: '+11231231234' }

Step

{ label: 'In Progress', value: 1 }
{ label: 'Completed', value: 2 }