### Step Examples (JavaScript) Source: https://missiveapp.com/docs/docs/developers/ui-iframe-integrations/javascript-api Illustrates the structure of Step objects, used for representing stages or progress. Examples show a 'Completed' step and an 'In Progress' step, each with a label and value. ```javascript { label: 'In Progress', value: 1 } ``` ```javascript { label: 'Completed', value: 2 } ``` -------------------------------- ### FormButton Examples (JavaScript) Source: https://missiveapp.com/docs/docs/developers/ui-iframe-integrations/javascript-api Illustrates the creation of FormButton objects for user interactions. Examples include a 'cancel' button and a 'submit' button, each with a specified type and label. ```javascript { type: 'cancel', label: 'Cancel' } ``` ```javascript { type: 'submit', label: 'Create' } ``` -------------------------------- ### Option Examples (JavaScript) Source: https://missiveapp.com/docs/docs/developers/ui-iframe-integrations/javascript-api Provides examples of Option objects, used for selectable items in lists or dropdowns. Demonstrates basic label-value pairs, and options with added color and styling. ```javascript { label: 'My Project', value: 12345 } ``` ```javascript { label: 'My Tag', value: 54321, color: '#F00' } ``` -------------------------------- ### Incoming Webhook Payload Example Source: https://missiveapp.com/docs/docs/developers/custom-channels/setup This is an example of the JSON payload received when a new message arrives via a Missive webhook. ```APIDOC ## Incoming Webhook Payload Example ### Description This is an example of the JSON payload received when a new message arrives via a Missive webhook. Your server is responsible for processing this payload as needed, such as sending the message via a third-party API. ### Request Body Example ```json { "body": "Hi, my name is Phil! How can I help you?", "from_field": { "id": null, "name": "My custom account", "username": "My custom account" }, "to_fields": [ { "id": "12345", "name": "Philippe Lehoux", "username": "@plehoux" } ], "external_id": null, "attachments": [], "author": { "id": "af577bfa-076f-4ff0-bcc0-9b2d578fc601", "email": "philippe@conferencebadge.com", "name": "Philippe Lehoux", "avatar_url": "https://missive.cdn.com/814942a3-ae65-4da5-b1ab-bd5266336ef4/philippe.png" }, "conversation": { "id": "15ff3085-4654-488d-a18f-aced2cc7dcc9", "subject": null, "latest_message_subject": "Message from Philippe Lehoux", "organization": null, "color": null, "assignees": [], "users": [ { "id": "af577bfa-076f-4ff0-bcc0-9b2d578fc601", "name": "Philippe Lehoux", "email": "philippe@conferencebadge.com", "unassigned": false, "closed": false, "archived": false, "trashed": false, "junked": false, "assigned": false, "flagged": false, "snoozed": false } ], "attachments_count": 0, "messages_count": 2, "authors": [ { "name": "My custom account", "address": null }, { "name": "Philippe Lehoux", "address": null } ], "drafts_count": 0, "send_later_messages_count": 0, "tasks_count": 0, "completed_tasks_count": 0, "web_url": "https://mail.missiveapp.com/#inbox/conversations/15ff3085-4654-488d-a18f-aced2cc7dcc9", "app_url": "missive://mail.missiveapp.com/#inbox/conversations/15ff3085-4654-488d-a18f-aced2cc7dcc9", "assignee_names": "", "assignee_emails": "", "shared_label_names": "", "shared_labels": [] } } ``` ``` -------------------------------- ### PhoneField Examples (JavaScript) Source: https://missiveapp.com/docs/docs/developers/ui-iframe-integrations/javascript-api Shows how to represent phone number data using PhoneField objects. Examples include a basic phone number and one with an associated contact name. ```javascript { phoneNumber: '+11231231234', name: 'Frodo Baggins' } ``` ```javascript { phoneNumber: '+11231231234' } ``` -------------------------------- ### API POST Request Example with JSON Body Source: https://missiveapp.com/docs/docs/developers/rest-api This example shows a POST request to the /v1/drafts endpoint, including the necessary Content-Type header for JSON and an example JSON payload. ```http POST /v1/drafts Host: public.missiveapp.com Authorization: Bearer missive_pat-26pApm_QTmyhLLbA...FwoFGmJ6x-6fikpQ Content-Type: application/json {"drafts":{}} ``` -------------------------------- ### FormNote Examples (JavaScript) Source: https://missiveapp.com/docs/docs/developers/ui-iframe-integrations/javascript-api Shows two examples of FormNote objects: one for a simple status message and another that includes a URL to create a clickable link. Useful for status updates or quick notes. ```javascript { message: '✓ Completed on Feb 18' } ``` ```javascript { message: 'View on Missive', url: 'https://missiveapp.com' } ``` -------------------------------- ### AddressField Object Structure Examples Source: https://missiveapp.com/docs/docs/developers/ui-iframe-integrations/javascript-api Illustrates the structure of the AddressField object, which can include an email address and an optional contact name. These examples show different ways to instantiate the AddressField. ```json { "address": "frodo@missiveapp.com", "name": "Frodo Baggins" } ``` ```json { "address": "sam@missiveapp.com" } ``` -------------------------------- ### API Authentication Example Request Source: https://missiveapp.com/docs/docs/developers/rest-api This example demonstrates how to authenticate API requests by including the user token as a Bearer token in the Authorization HTTP header. ```http POST /v1/drafts Host: public.missiveapp.com Authorization: Bearer missive_pat-26pApm_QTmyhLLbA...FwoFGmJ6x-6fikpQ ``` -------------------------------- ### Task Response Example (JSON) Source: https://missiveapp.com/docs/docs/developers/rest-api/endpoints An example of the JSON response structure when listing multiple tasks. Each task object contains details such as ID, title, state, timestamps, assignees, and type. It also shows the structure for nested conversation or team objects. ```JSON { "tasks": [ { "id": "75ad834a-9bd6-4008-b9e6-fc9fa2e7770b", "conversation": null, "title": "Review pull request", "description": "Please review PR #123", "state": "todo", "started_at": null, "closed_at": null, "assignees": ["1ce8117e-ae42-4304-b953-c81656da4bd1"], "team": "0e24f298-965d-4475-9220-b32636a1e2c3", "due_at": 1692371867, "type": "task", "last_activity_at": 1692371900 }, { "id": "a5d2aa1c-3828-4f90-bbd8-3dffaadda97e", "conversation": null, "title": "Follow up with client", "description": null, "state": "in_progress", "started_at": 1692371000, "closed_at": null, "assignees": ["74f91030-39b8-4627-9835-9cfbce9d67c1"], "team": null, "due_at": null, "type": "conversation", "last_activity_at": 1692371800 } ] } ``` -------------------------------- ### Create Team Request Payload (Full Example) - JSON Source: https://missiveapp.com/docs/docs/developers/rest-api/endpoints This JSON payload provides a comprehensive example of creating a team, including optional attributes like emoji, color, business hours, and various behavior configurations for mentions and replies. ```json { "teams": [ { "name": "Support", "organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92", "emoji": ":dart:", "color": "#2266ED", "active_members": [ "1ce8117e-ae42-4304-b953-c81656da4bd1", "74f91030-39b8-4627-9835-9cfbce9d67c1" ], "observers": ["a41a00fd-453d-49d7-a487-9765c35a3b70"], "business_hours": { "tz": "America/Montreal", "t": [ { "d": 1, "s": [32400, 61200] }, { "d": 2, "s": [32400, 61200] }, { "d": 3, "s": [32400, 61200] }, { "d": 4, "s": [32400, 61200] }, { "d": 5, "s": [32400, 61200] } ] }, "inactivity_period": 604800, "team_mention_behavior": "only_active_members", "user_reply_behavior": "assign_user", "received_reply_behavior": "show_in_assignee_inbox", "team_sidebar_behavior": "show_team_space", "team_inbox_enabled": true, "chat_room_enabled": true } ] } ``` -------------------------------- ### Single Task Response Example (JSON) Source: https://missiveapp.com/docs/docs/developers/rest-api/endpoints An example of the JSON response structure when retrieving a single task by its ID. This response provides detailed information, including nested objects for assignees and team members, offering more context than the list view. ```JSON { "tasks": { "id": "75ad834a-9bd6-4008-b9e6-fc9fa2e7770b", "conversation": null, "title": "Review pull request", "description": "Please review PR #123", "state": "todo", "started_at": null, "closed_at": null, "assignees": [ { "id": "1ce8117e-ae42-4304-b953-c81656da4bd1", "name": "John Doe", "email": "john@example.com", "avatar_url": "https://..." } ], "team": { "id": "0e24f298-965d-4475-9220-b32636a1e2c3", "name": "Engineering", "organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92" }, "due_at": 1692371867, "type": "task" } } ``` -------------------------------- ### POST /v1/drafts Source: https://missiveapp.com/docs/docs/developers/rest-api Example of creating a draft using the Missive API, demonstrating authentication and the request body structure. ```APIDOC ## POST /v1/drafts ### Description Creates a new draft in Missive. ### Method POST ### Endpoint `https://public.missiveapp.com/v1/drafts` ### Headers - **Authorization** (string) - Required - Bearer token for authentication. - **Content-Type** (string) - Required - `application/json` ### Request Body - **drafts** (object) - Required - Contains the draft details. - *Details of the `drafts` object are not provided in the source text.* ### Request Example ```http POST /v1/drafts Host: public.missiveapp.com Authorization: Bearer missive_pat-26pApm_QTmyhLLbA...FwoFGmJ6x-6fikpQ Content-Type: application/json {"drafts":{}} ``` ### Response #### Success Response (201) No body is returned for a successful creation. #### Error Response Responses are formatted as JSON, including errors. ``` -------------------------------- ### GET /v1/conversations/:id/comments API Response Example Source: https://missiveapp.com/docs/docs/developers/rest-api/endpoints This JSON object represents a successful response from the GET /v1/conversations/:id/comments API endpoint. It contains a list of comment objects, each with details such as ID, body, creation timestamp, mentions, author information, and an optional attached file or associated task. ```json { "comments": [ { "id": "3fa4bcf5-e57e-47a4-9422-de2cce5f802e", "body": "This is a comment", "created_at": 1563806347, "mentions": [ { "id": "1ce8117e-ae42-4304-b953-c81656da4bd1", "index": 0, "length": 8 } ], "author": { "id": "dc3c4104-eced-4206-b532-ef84b331778a", "name": "Chad Zemlak", "email": "chad@example.com", "avatar_url": "https://..." }, "attachment": { "id": "81eed561-4908-4738-9a9f-2da886b1de43", "filename": "document.pdf", "extension": "pdf", "url": "https://...", "media_type": "application", "sub_type": "pdf", "size": 114615 }, "task": { "description": "Follow up with client", "state": "in_progress", "due_at": 1692371867, "started_at": 1691812800, "closed_at": null, "assignees": [ { "id": "1ce8117e-ae42-4304-b953-c81656da4bd1", "name": "Phil Smith", "email": "phil@example.com", "avatar_url": "https://..." } ], "team": { "id": "0e24f298-965d-4475-9220-b32636a1e2c3", "name": "Support", "organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92" } } } ] } ``` -------------------------------- ### Event: main_action Source: https://missiveapp.com/docs/docs/developers/ui-iframe-integrations/javascript-api Triggered when the user presses the 'Integrations main action' shortcut. ```APIDOC ## Event: main_action ### Description Triggered when user press the “Integrations main action” shortcut. ### Payload This event does not carry any payload. ### Example (No payload) ``` -------------------------------- ### FormComment Example (JavaScript) Source: https://missiveapp.com/docs/docs/developers/ui-iframe-integrations/javascript-api Demonstrates the structure of a FormComment object, including content, author information, and optional date. It's used for adding comments with rich text or basic messages. ```javascript { content: 'I will take the Ring, though I do not know the way.', authorName: 'Frodo Baggins', authorAvatar: 'https://gravatar.com/avatar/014bcc1f9c5920c658a198e6649cd20b', } ``` -------------------------------- ### Initialize Missive Chat Widget (HTML) Source: https://missiveapp.com/docs/docs/core-features/connected-accounts/other-channels/live-chat/setup This snippet demonstrates how to initialize the Missive Live Chat widget on a webpage using HTML and JavaScript. It includes the necessary configuration, such as the account ID and the `onReady` callback, which is crucial for executing chat-related functions. ```html ``` -------------------------------- ### Get a Response (GET /v1/responses/:id) Source: https://missiveapp.com/docs/docs/developers/rest-api/endpoints Fetches a single response by its unique identifier. This endpoint is used to retrieve the full details of a specific response. ```http GET /v1/responses/:id ``` -------------------------------- ### GET /v1/conversations/:id - Get a Conversation Source: https://missiveapp.com/docs/docs/developers/rest-api/endpoints Fetches a specific conversation using its unique identifier. Note that the returned conversation ID might differ if conversations have been merged. ```APIDOC ## GET /v1/conversations/:id ### Description Fetch a specific conversation using the conversation `id`. {% hint style="info" %} The returned conversation may have a different `id`. This happens when conversations get merged; passing an old conversation `id` will keep working, but the new conversation `id` will be returned. {% endhint %} ### Method GET ### Endpoint /v1/conversations/:id ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the conversation to retrieve. ### Response #### Success Response (200) - **conversations** (array) - An array containing the conversation object(s). - **id** (string) - The unique identifier of the conversation. - **subject** (string/null) - The subject of the conversation. - **latest_message_subject** (string) - The subject of the latest message in the conversation. - **organization** (object) - Information about the organization the conversation belongs to. - **id** (string) - The organization's ID. - **name** (string) - The organization's name. - **color** (string/null) - The color associated with the conversation. - **assignees** (array) - A list of users assigned to the conversation. - **users** (array) - A list of users involved in the conversation. - **id** (string) - The user's ID. - **name** (string) - The user's name. - **email** (string) - The user's email address. - **unassigned** (boolean) - **closed** (boolean) - **archived** (boolean) - **trashed** (boolean) - **junked** (boolean) - **assigned** (boolean) - **flagged** (boolean) - **snoozed** (boolean) - **attachments_count** (integer) - The number of attachments in the conversation. - **messages_count** (integer) - The total number of messages in the conversation. - **authors** (array) - A list of authors of the messages in the conversation. - **name** (string) - The author's name. - **address** (string) - The author's email address. - **drafts_count** (integer) - The number of drafts for the conversation. - **send_later_messages_count** (integer) - **tasks_count** (integer) - **completed_tasks_count** (integer) - **web_url** (string) - The URL to view the conversation in a web browser. - **app_url** (string) - The URL to open the conversation in the application. - **assignee_names** (string) - **assignee_emails** (string) - **shared_label_names** (string) - **last_activity_at** (integer) - Timestamp of the last activity. - **team** (object) - Information about the team the conversation belongs to. - **id** (string) - The team's ID. - **name** (string) - The team's name. - **organization** (string) - The organization's ID. - **shared_labels** (array) #### Response Example ```json { "conversations": [ { "id": "6d3c9b1c-7067-4a28-8ea6-ea91340b67cc", "subject": null, "latest_message_subject": "Question?", "organization": { "id": "96cafdc6-ec6a-4439-9b0c-f55a1133b1e7", "name": "Conference Badge" }, "color": null, "assignees": [], "users": [ { "id": "dc3c4104-eced-4206-b532-ef84b331778a", "name": "Chad Zemlak", "email": "chad@conferencebade.com", "unassigned": false, "closed": false, "archived": false, "trashed": false, "junked": false, "assigned": false, "flagged": true, "snoozed": false } ], "attachments_count": 0, "messages_count": 1, "authors": [ { "name": "Samwise Gamgee", "address": "sam@fellowship.org" } ], "drafts_count": 0, "send_later_messages_count": 0, "tasks_count": 0, "completed_tasks_count": 0, "web_url": "https://mail.missiveapp.com/#inbox/conversations/6d3c9b1c-7067-4a28-8ea6-ea91340b67cc", "app_url": "missive://mail.missiveapp.com/#inbox/conversations/6d3c9b1c-7067-4a28-8ea6-ea91340b67cc", "assignee_names": "", "assignee_emails": "", "shared_label_names": "", "last_activity_at": 1654544954, "team": { "id": "f36b7570-078e-408e-9cb8-2b4441ad93c0", "name": "Team 1", "organization": "96cafdc6-ec6a-4439-9b0c-f55a1133b1e7" }, "shared_labels": [] } ] } ``` ``` -------------------------------- ### Get Contact by ID (GET /v1/contacts/:id) Source: https://missiveapp.com/docs/docs/developers/rest-api/endpoints This endpoint retrieves a single contact identified by its unique ID. If the contact does not exist or has been deleted, a 404 Not Found response will be returned. This is useful for fetching the complete details of a specific contact. ```HTTP GET /v1/contacts/:id ``` -------------------------------- ### Webhook Setup and Configuration Source: https://missiveapp.com/docs/docs/developers/webhooks This section details how to set up webhook rules within Missive and the requirements for your endpoint to handle incoming requests. ```APIDOC ## Webhook Setup Missive allows applications to be notified of certain actions (incoming emails, outgoing emails, label changes, etc.) in the form of an HTTP `POST` payload sent to a registered URL. ### How to Setup 1. **Create a webhook rule**: Navigate to **Settings** > **Rules**, create a new rule, and select **Webhook** as the action. Upon saving the rule, your configured endpoint will receive a validation `POST` request. 2. **Ensure your endpoint handles requests correctly**: * The endpoint must accept `POST` requests. * It must respond within 15 seconds. For longer tasks, implement background job solutions. **Note**: Organization admins or owners on the [Productive plan](https://missiveapp.com/pricing) or [Business plan](https://missiveapp.com/pricing) can create rules. ```