JavaScript API

Complete JavaScript API reference for Missive iFrame integrations: methods, events, and objects.

App methods

reload()

Reloads the iframe.

search(text)

Initiates a new search.

Param (* required)

Default

Description

text*

""

Search term

alert(options)

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

Param (* required)

Default

Description

options

{}

title

"Error in “Your Integration” integration"

Error title

message

""

Error description

note

""

Error note

navigate(options)

Navigate to a conversation.

Param (* required)

Default

Description

options

{}

conversationId

""

Conversation ID

on(event, callback, options)

Registers an event callback.

Param (* required)

Default

Description

event*

""

Event to register

callback*

Callback function

options

{}

retroactive

false

Triggers the callback immediately if the event has occurred before the callback is registered

openForm(data)

Displays a form popup. Multiple forms can be stacked over each other.

=> Promise(Object) — Resolves with Field objects

Param (* required)

Default

Description

data

{}

name

""

Form title

fields

[]

Array of FormField objects

comments

[]

Array of FormComment objects

notes

[]

Array of FormNote objects

buttons

[]

Array of FormButton objects

options

{}

autoClose

true

Close the popup on submit

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.

Param (* required)

Default

Description

url*

""

URL string

openContextMenu(data)

Opens a context menu

Param (* required)

Default

Description

data*

{}

top

0

Top position of the menu — Menu will be below that point — Note: do not set if data.bottom is provided

bottom

null

Top position of the menu — Menu will be above that point — Note: do not set if data.top is provided

left

0

Left position of the menu — Menu will be to the right of that point — Note: do not set if data.right is provided

right

null

Right position of the menu — Menu will be to the left of that point — Note: do not set if data.left is provided

options*

[]

Array of Option objects

setActions(actions)

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

Param (* required)

Default

Description

actions

[]

Array of Action objects

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.

Param (* required)

Default

Description

permissions

{}

camera

false

Request permission to use camera

microphone

false

Request permission to use microphone

storeGet(key)

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

Param (* required)

Default

Description

key*

""

A unique identifier used when storing the data using storeSet(key, data).

storeSet(key, data)

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

Param (* required)

Default

Description

key*

""

A unique identifier for the data to be stored. This key is used to retrieve the data later using storeGet(key).

data*

{}

The data (String, Array or Object) to be stored.

Example usage:

respondToMessage(data)

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

Param (* required)

Default

Description

data*

{}

commands*

{}

List of commands that are rendered in the command bar

id*

""

Unique identifier of the command

picture

{}

An image displayed alongside the command using the grid layout

src*

""

Path to the image

webp

""

Optional WEBP image path that is used when the browser supports it

alt

""

Alt attribute for the image tag

iconUrl

""

Icon displayed alongside the command using the list layout

label

""

Text displayed with the command using the list layout

payload

{}

An object returned to the callback event of type execute

closeOnExecute

false

Specifies whether or not the Command Bar should close when the command is executed

Example usage:

initiateCallback(url)

Initiates an OAuth flow by opening the authentication URL in a new browser tab. This method helps work around iframe OAuth limitations and is compatible with iOS.

=> Promise(Object) — Resolves with query parameters from the OAuth redirect

Param (* required)

Default

Description

url*

""

Authentication endpoint URL that will receive a redirectTo parameter

Example usage:

How it works:

Missive opens the auth URL in a new browser tab
Adds a redirectTo parameter to your URL
After OAuth completion, redirect to the provided redirectTo URL with your tokens/data as query params
The browser tab closes automatically
Your integration receives the data in the response object

Fetch methods

fetchConversations(ids)

Fetches attributes for the given conversation IDs.

=> Promise(Array) — Resolves with Conversation objects

Param (* required)

Default

Description

ids*

[]

Array of conversation IDs

Example usage:

Available attributes for conversations:

fetchMessages(ids)

Fetches attributes for the given message IDs.

=> Promise(Array) — Resolves with Message objects

Param (* required)

Default

Description

ids*

[]

Array of message IDs

Available attributes for messages:

fetchUsers()

Fetches attributes for all users.

=> Promise(Array) — Resolves with User objects

fetchLabels()

Fetches attributes for all shared labels.

The scope of returned labels depends on how the integration is installed. When an integration is shared with an organization, fetchLabels() returns labels from that organization only. When the integration is personal (private), it returns labels from all organizations the user belongs to. If you need labels across multiple orgs, have each user install the integration privately via Settings > Integrations instead of sharing it at the org level.

=> Promise(Array) — Resolves with Label objects

Conversation methods

createConversation(options)

Creates a new conversation.

Param (* required)

Default

Description

options

{}

select

true

Navigate to the newly created conversation(s)

count

1

Number of conversations to create

archive()

Archives current conversation.

trash()

Trashes current conversation.

moveToInbox()

Moves current conversation to Inbox.

comment(body)

Creates a comment in the current conversation.

Param (* required)

Default

Description

body*

""

Body of the comment

createTask(body, completed)

Creates a task in the current conversation.

Param (* required)

Default

Description

body*

""

Body of the task

completed

false

Mark task as completed

addLabels(labelIds)

Adds labels to the current conversation.

Param (* required)

Default

Description

labelIds*

[]

Array of label ids

removeLabels(labelIds)

Removes labels from the current conversation.

Param (* required)

Default

Description

labelIds*

[]

Array of label ids

close()

subject*

""