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:

example.js

const userData = {
  id: '1234',
  name: 'John Doe',
  email: '[e-mail]'
};

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.

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:

command-bar.js

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
      }
    },
  },
])

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:

oauth.js

async function authenticateWithOAuth() {
  try {
    // 1. Initiate OAuth flow
    const response = await Missive.initiateCallback('https://your-auth-endpoint')

    // 2. Response will contain query params from the OAuth redirect
    const { access_token } = response

    // 3. Store the token for future use
    await Missive.storeSet('oauth_token', access_token)
  } catch (error) {
    console.error('OAuth flow failed:', error)
  }
}

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:

fetch-conversations.js

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

Param *required	Default	Description
ids*	[]	Array of message IDs

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: '[e-mail]',
  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.

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()

Closes the current conversation.

reopen()

Reopens the current conversation.

assign(userIds)

Assigns users to the current conversation.

Param *required	Default	Description
userIds*	[]	Array of user ids — Empty array removes all assignees

addAssignees(userIds)

Adds assignees to the current conversation.

Param *required	Default	Description
userIds*	[]	Array of user ids

removeAssignees(userIds)

Removes assignees from the current conversation.

Param *required	Default	Description
userIds*	[]	Array of user ids

setColor(color)

Sets current conversation color.

Param *required	Default	Description
color*	""	Color in HEX format

setDescription(description)

Sets current conversation description.

Param *required	Default	Description
description*	""	Description of the conversation

setSubject(subject)

Sets current conversation subject.

Param *required	Default	Description
subject*	""	Subject of the conversation — Empty or null resets the subject

Composer methods

compose(options)

Creates a new draft in a new conversation.

Param *required	Default	Description
options	{}
deliver	false	Instantly deliver newly created draft
mailto	{}
subject	""	Draft subject
body	""	Draft body
to_fields	[]	Array of AddressField objects
cc_fields	[]	Array of AddressField objects
bcc_fields	[]	Array of AddressField objects

composeInConversation()

Creates a new draft in current conversation.

Same params as compose.

reply(options)

Replies to current conversation latest message.

Param *required	Default	Description
options	{}
deliver	false	Instantly deliver newly created reply
mailto	{}	See compose method above

forward(options)

Forwards current conversation latest message.

Param *required	Default	Description
options	{}
private	false	Create draft in a new private conversation
deliver	false	Instantly deliver newly created draft
mailto	{}	See compose method above

insertText(text)

Inserts content as text in the currently selected composer.

Param *required	Default	Description
text	""	Text content

insertHtml(text)

Inserts content as HTML in the currently selected composer.

Param *required	Default	Description
text	""	HTML content

Helper methods

isToday(date)

Tests if date is today.

=> Boolean

Param *required	Default	Description
date*		Date object

isTomorrow(date)

Tests if date is tomorrow.

=> Boolean

Param *required	Default	Description
date*		Date object

isPast(date)

Tests if date is past.

=> Boolean

Param *required	Default	Description
date*		Date object

isInLessThan(date, options)

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

=> Boolean

Param *required	Default	Description
date*		Date object
options	{}
hours	0	Hours in the future
minutes	0	Minutes in the future
seconds	0	Seconds in the future

getMonth(index, options)

Returns the month name of a given index.

=> String

Param *required	Default	Description
index*		0-11 index of the month
options	{}
short	false	Returns the short version of the month — i.e. "Jan"

getEmailAddresses(conversations)

Returns all the email addresses found in conversations.

=> Array(AddressField)

Param *required	Default	Description
conversations*	[]	Array of Conversation object

getPhoneNumbers(conversations)

Returns all the phone numbers found in conversations.

=> Array(PhoneField)

Param *required	Default	Description
conversations*	[]	Array of Conversation object

formatTimestamp(timestamp, options)

Formats given timestamp.

=> { date, formatted }

Param *required	Default	Description
timestamp*		Unix timestamp in seconds or milliseconds — i.e. 1550586350
options	{}
today	false	Displays "Today" when date is today
tomorrow	false	Displays "Tomorrow" when date is tomorrow
year	false	Forces the year to be displayed — Year is not displayed by default when current year
time	false	Displays the hours and minutes
until		Unix timestamp — When date spans over multiple days

formatDate(string, options)

Formats given date.

=> { date, formatted }

Param *required	Default	Description
string*	""	Date string — i.e. "2018-10-19 17:32:45 GMT"
options	{}	See formatTimestamp options above

formatContact(contact)

Formats given contact.

=> { letters, formatted }

Param *required	Default	Description
contact*		AddressField object

capitalize(string)

Capitalizes given string.

=> String

Param *required	Default	Description
string*	""	String to be capitalized

classNames(classes)

Converts object to CSS class names.

=> String

Param *required	Default	Description
classes*	{}	Object of CSS classes definitions and assertions — i.e. { foo: true, bar: true, baz: false }

writeToClipboard(text)

Write text to the user’s clipboard.

Param *required	Default	Description
text	""	String to copy to the 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)

Payload	Description
id	Use fetchMessages to fetch the data of the message.

change:conversations

Triggered when selected conversation(s) change.

=> (ids)

Payload	Description
ids	Array of the selected Conversation IDs. Use fetchConversations to fetch the data of newly selected conversation(s).

change:users

Triggered when users change.

=> ()

Use fetchUsers to fetch users data.

Glossary

Action

{ label: 'New task', callback: () => {} }

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

Param *required	Default	Description
contexts	[]	Contexts where the action will be available in the Missive UI. Any of draft, conversations, conversation, message, tel, comment, comment_box, swipe, command_bar, setting — All when omitted.
label*	""	Action name
emoji	""	Emoji ID of the emoji used as the action icon in the Missive UI. You can find the ID of a specific emoji on this page. For instance, for this 🧹 emoji the ID is :broom:.
swipe_id	""	Unique string per swipe action — i.e. new-task — Required for swipe context
callback*	null	Action callback — Receives an object with either conversations, conversation, message, tel, comment, comment_box as keys depending on the context the action was triggered. Callbacks for the command_bar context take an event object with either a load, search, execute type as well as a messageId. The callback can be used to send commands that will be displayed in the Command Bar. See the respondToMessage method for more details.
swipe_color	"#aaa"	Background color of the swipe action
layout	"list"	The layout of the commands inside the Command Bar when using the command_bar context. It can be either list or grid.
placeholder	""	Placeholder of the Command Bar input

AddressField

{ address: '[e-mail]', name: 'Frodo Baggins' }

{ address: '[e-mail]' }

Param *required	Default	Description
address*	""	Email address
name	""	Contact name

FormField

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

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

Param *required	Default	Description
type*	""	Field type — Any of input, textarea, select, calendar, duration, progress, html
scope	{}	Dynamically filter out fields not matching this scope — i.e. { project_id: 12345 } — Would only show this field when project 12345 is selected
data*	{}	Data available for all types — See following FormField(type:) for specific types data
name*	""	Name of the field — As you would normally use inside a <form>
value*	""	Default value of the field
placeholder*	""	Field placeholder
required	false	Form won’t submit unless user fills this field

FormField(type:input)

Param *required	Default	Description
data	{}
type*	{}	Input type — Any of text, number, hidden
focus	false	Auto focus the input
disabled	false	Make the input non-editable
precision		Format number to specific precision — For number input type only
options	{}
prefix	false	Make the placeholder always visible
thin	false	Render a smaller input — For text input type only

FormField(type:textarea)

Param *required	Default	Description
data	{}
rows	4	Number of visible rows
focus	false	Auto focus the textarea

FormField(type:select)

Param *required	Default	Description
data	{}
value		Value of the selected option
options	[]	Array of Option objects
multiple	false	Allow selecting multiple options

FormField(type:calendar)

Param *required	Default	Description
data	{}
value	{ timestamp, all_day }	Unix timestamp and boolean — i.e. { timestamp: 1550586350, all_day: true }
allow_past	false	Allow setting a date in the past
allow_all_day	false	Allow setting a full-day date

FormField(type:duration)

Param *required	Default	Description
data	{}
value	""	HH:MM duration — i.e. "00:30"

FormField(type:progress)

Param *required	Default	Description
data	{}
value		Value of the selected step
steps	[]	Array of Step objects

FormField(type:html)

Param *required	Default	Description
data	{}
value	""	HTML string — i.e. "<br> <p>Hey <b>there</b>!</p><br> <p>How <span style="color: red">are you</span>?</p><br>"

FormComment

Example:

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

Param *required	Default	Description
content*	""	Comment body
authorAvatar	""	Author avatar URL
authorName	""	Author name
date	""	Date string with format of your choosing — i.e. "Feb 18, 2019"

FormNote

Examples:

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

Param *required	Default	Description
message*	""	Note body
url	""	Turn the note into a clickable link

FormButton

Examples:

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

Param *required	Default	Description
type*	""	Button type — Any of submit, cancel
label	""	Button label

Option

Examples:

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

Param *required	Default	Description
label*	""	Option label
value*	""	Option value
disabled	false	Make the option non-clickable
color	""	Color in HEX format — Add a color pin to the option
colorRadius	"100%"	Specify the radius of the color pin
callback	null	Option callback — For openContextMenu options

PhoneField

Examples:

{ phoneNumber: '[phone]', name: 'Frodo Baggins' }
{ phoneNumber: '[phone]' }

Param *required	Default	Description
phoneNumber*	""	Phone number
name	""	Contact name

Step

Examples:

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

Param *required	Default	Description
label*	""	Step label
value*	""	Step value

---

Related guides

• ⚙️ Custom Channels

Need more specific answers? Contact us