### Install SDK via CDN Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Include the SDK directly in HTML files for projects without a module bundler. ```html ``` -------------------------------- ### Install SDK via npm Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Add the SDK to your project dependencies using the npm package manager. ```bash npm install --save @pipedrive/app-extensions-sdk ``` -------------------------------- ### Get Metadata Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Retrieve metadata about the main Pipedrive window, including dimensions for responsive layout calculations. ```APIDOC ## Get Metadata ### Description Retrieve metadata about the main Pipedrive window, including dimensions for responsive layout calculations. ### Method `POST` (Implicit via `sdk.execute`) ### Endpoint `/` (Internal SDK command) ### Parameters None ### Request Example ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); const { windowWidth, windowHeight } = await sdk.execute(Command.GET_METADATA); console.log(`Window dimensions: ${windowWidth}x${windowHeight}px`); // Responsive layout based on available space if (windowWidth < 1200) { await sdk.execute(Command.RESIZE, { width: 300 }); } else { await sdk.execute(Command.RESIZE, { width: 450 }); } ``` ### Response #### Success Response (200) - **windowWidth** (number) - The current width of the Pipedrive window in pixels. - **windowHeight** (number) - The current height of the Pipedrive window in pixels. ### Response Example ```json { "windowWidth": 1440, "windowHeight": 900 } ``` ``` -------------------------------- ### Get Metadata Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Retrieves dimensions of the main Pipedrive window, useful for responsive layout adjustments. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); const { windowWidth, windowHeight } = await sdk.execute(Command.GET_METADATA); console.log(`Window dimensions: ${windowWidth}x${windowHeight}px`); // Responsive layout based on available space if (windowWidth < 1200) { await sdk.execute(Command.RESIZE, { width: 300 }); } else { await sdk.execute(Command.RESIZE, { width: 450 }); } ``` -------------------------------- ### Get signed token Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Generates a new JWT valid for 5 minutes, containing Pipedrive user and company IDs for server-side verification. ```javascript const { token } = await sdk.execute(Command.GET_SIGNED_TOKEN); ``` -------------------------------- ### Initialize SDK via CDN Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Include the SDK via jsDelivr CDN for environments without a module bundler. ```html ``` ```html ``` -------------------------------- ### Initialization Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Initializes the SDK to enable communication between the custom UI extension and Pipedrive. ```APIDOC ## Initialization ### Description Initializes the SDK instance. The SDK attempts to read the identifier from the URL query, but it can also be provided manually. ### Parameters #### Request Body - **identifier** (string) - Optional - The unique identifier for the extension. - **size** (object) - Optional - Custom UI size configuration (e.g., { height: 500 }). ### Request Example ```javascript const sdk = await new AppExtensionsSDK({ identifier: '123abc' }) .initialize({ size: { height: 500 } }); ``` ``` -------------------------------- ### Initialize Pipedrive App Extensions SDK Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Initialize the SDK using the constructor. The identifier can be detected automatically from the URL or provided manually. ```javascript import AppExtensionsSDK from '@pipedrive/app-extensions-sdk'; // SDK detects identifier from URL and uses default custom UI size const sdk = await new AppExtensionsSDK().initialize(); // Pass in id manually and provide custom UI size const sdk = await new AppExtensionsSDK({ identifier: '123abc' }) .initialize({ size: { height: 500 } }); ``` -------------------------------- ### Initialize the SDK Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Establish communication with Pipedrive. The SDK can automatically detect the identifier from the URL or accept manual configuration. ```javascript import AppExtensionsSDK from '@pipedrive/app-extensions-sdk'; // Basic initialization - SDK detects identifier from URL automatically const sdk = await new AppExtensionsSDK().initialize(); // Advanced initialization with manual identifier and custom size const sdk = await new AppExtensionsSDK({ identifier: '123abc' }) .initialize({ size: { height: 500, width: 400 } }); // Access user settings after initialization console.log('Current theme:', sdk.userSettings.theme); // 'light' or 'dark' ``` -------------------------------- ### Handle SDK Command Errors with Try-Catch Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Use async/await with try-catch blocks to gracefully handle errors when executing SDK commands. Ensure the SDK is initialized before attempting command execution. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Using async/await with try-catch try { await sdk.execute(Command.SHOW_SNACKBAR, { message: 'Operation completed' }); } catch (error) { console.error('Command failed:', error.message); } ``` ```javascript // Check initialization before executing commands function safeExecute(sdk, command, args) { try { return sdk.execute(command, args); } catch (error) { if (error.message === 'SDK is not initialized') { console.error('Please initialize SDK before executing commands'); } throw error; } } ``` -------------------------------- ### Open New Activity Modal with Prefill Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Use this command to open the new activity modal. Prefill fields like subject, due date, deal, and organization for a more streamlined user experience. ```javascript const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.ACTIVITY, prefill: { subject: 'Follow-up phone call', dueDate: '2022-12-18', dueTime: '13:00', duration: '00:30', note: 'Ask about deal next steps', description: 'Discussion about deal specifics', deal: 10, organization: 2, }, }); ``` -------------------------------- ### Command.SHOW_FLOATING_WINDOW Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens a floating window and triggers the VISIBILITY event. ```APIDOC ## SHOW_FLOATING_WINDOW ### Description Opens a floating window and triggers `Event.VISIBILITY` with an optional `context` parameter. ### Parameters #### Request Body - **context** (Object) - Optional - Object to be passed as JSON to event handler ### Request Example ```javascript await sdk.execute(Command.SHOW_FLOATING_WINDOW, { context: { person_id: 42, }, }); ``` ``` -------------------------------- ### Open Organization Creation Modal Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Opens the native organization creation modal with an optional prefilled name. ```javascript import AppExtensionsSDK, { Command, Modal } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.ORGANIZATION, prefill: { name: 'Global Enterprises Ltd' } }); if (status === 'submitted') { console.log('Organization created with ID:', id); } ``` -------------------------------- ### Open New Organization Modal with Prefill Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens the new organization modal, allowing prefilling of the organization name. The `id` of the added organization is returned upon submission. ```javascript const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.ORGANIZATION, prefill: { name: 'Some organization', }, }); ``` -------------------------------- ### Open New Person Modal with Prefill Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens the new person modal, enabling prefilling of name and organization. The `id` of the added person is returned upon submission. ```javascript const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.PERSON, prefill: { name: 'Some name', organization: 'Some organization', }, }); ``` -------------------------------- ### OPEN_MODAL (Activity) Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens a new activity modal with optional prefilled data. ```APIDOC ## OPEN_MODAL (Activity) ### Description Opens a new activity modal. Allows prefilling fields such as subject, date, time, duration, notes, description, and linked entity IDs. ### Parameters #### Request Body - **type** (Modal) - Required - Must be set to Modal.ACTIVITY - **prefill** (Object) - Optional - Object containing fields to prefill - **prefill.subject** (String) - Optional - Activity subject - **prefill.dueDate** (String) - Optional - Activity due date in yyyy-MM-dd format (UTC) - **prefill.dueTime** (String) - Optional - Activity due time in HH:mm format - **prefill.duration** (String) - Optional - Activity duration in HH:mm format - **prefill.note** (String) - Optional - Note, supports HTML tags (ul, li, b, u, i) - **prefill.description** (String) - Optional - Activity description, supports HTML tags (ul, li, b, u, i) - **prefill.deal** (Number) - Optional - Deal ID to connect - **prefill.organization** (Number) - Optional - Organization ID to connect ### Response - **status** (String) - Indicates if modal was submitted or closed - **id** (Number) - ID of added activity if submitted ### Request Example ```javascript const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.ACTIVITY, prefill: { subject: 'Follow-up phone call', dueDate: '2022-12-18', dueTime: '13:00', duration: '00:30', note: 'Ask about deal next steps', description: 'Discussion about deal specifics', deal: 10, organization: 2, }, }); ``` ``` -------------------------------- ### Implement Theme-Aware CSS Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Apply styling based on user theme preferences using SDK events and data attributes. ```javascript import AppExtensionsSDK, { Event } from '@pipedrive/app-extensions-sdk'; // Initialize and apply current theme immediately const sdk = new AppExtensionsSDK(); document.documentElement.setAttribute('data-theme', sdk.userSettings.theme); await sdk.initialize(); // React to theme changes sdk.listen(Event.USER_SETTINGS_CHANGE, ({ data }) => { document.documentElement.setAttribute('data-theme', data.theme); }); ``` ```css /* Theme-aware CSS styles */ [data-theme="light"] body { background-color: #ffffff; color: #333333; } [data-theme="dark"] body { background-color: #1e1e1e; color: #f5f5f5; } [data-theme="dark"] .card { background-color: #2d2d2d; border-color: #404040; } ``` -------------------------------- ### Open Deal Creation Modal Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Opens the native deal creation modal with optional prefilled fields. Returns the submission status and the new deal ID. ```javascript import AppExtensionsSDK, { Command, Modal } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Open deal modal with prefilled data const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.DEAL, prefill: { title: 'Enterprise Software License', organization: 'Acme Corporation', person: 'John Smith' } }); if (status === 'submitted') { console.log('Deal created with ID:', id); await sdk.execute(Command.SHOW_SNACKBAR, { message: `Deal #${id} created!` }); } else { console.log('Deal creation cancelled'); } ``` -------------------------------- ### Command.GET_METADATA Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Retrieves metadata information about the main window. ```APIDOC ## GET_METADATA ### Description Retrieves metadata information about the main window. ### Response #### Success Response (200) - **windowHeight** (Number) - Height of the main window (px). - **windowWidth** (Number) - Width of the main window (px). ### Response Example ```javascript const { windowWidth, windowHeight } = await sdk.execute(Command.GET_METADATA); ``` ``` -------------------------------- ### Show or hide floating window with SDK commands Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Use these commands to toggle the visibility of the floating window. The context object is optional and passed to the event handler. ```javascript await sdk.execute(Command.SHOW_FLOATING_WINDOW, { context: { person_id: 42, }, }); ``` ```javascript await sdk.execute(Command.HIDE_FLOATING_WINDOW, { context: { person_id: 42, }, }); ``` -------------------------------- ### Command: Show Snackbar Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Displays a snackbar notification to the user with an optional link. ```APIDOC ## Command: SHOW_SNACKBAR ### Description Shows a snackbar with a provided message and an optional link. ### Method execute ### Parameters #### Request Body - **message** (string) - Required - Message displayed in the snackbar. - **link** (object) - Optional - Link displayed next to the message. - **url** (string) - Required - URL for the link. - **label** (string) - Required - Label for the link. ### Request Example ```javascript await sdk.execute(Command.SHOW_SNACKBAR, { message: 'Action completed', link: { url: 'https://app.pipedrive.com', label: 'View', }, }); ``` ``` -------------------------------- ### Show Floating Window Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Display your app's floating window and trigger a visibility event. Pass optional context data to the window's event handler. ```APIDOC ## Show Floating Window ### Description Display your app's floating window and trigger a visibility event. Pass optional context data to the window's event handler. ### Method `POST` (Implicit via `sdk.execute`) ### Endpoint `/` (Internal SDK command) ### Parameters #### Request Body - **context** (object) - Optional - Context data to pass to the floating window's event handler. - **person_id** (number) - Example context field. - **action** (string) - Example context field. - **phone** (string) - Example context field. ### Request Example ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); await sdk.execute(Command.SHOW_FLOATING_WINDOW, { context: { person_id: 42, action: 'call', phone: '+1-555-0123' } }); ``` ### Response None (Command execution) ### Response Example None ``` -------------------------------- ### Show Snackbar Command Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Display a snackbar with a message and an optional link. ```javascript await sdk.execute(Command.SHOW_SNACKBAR, { message: 'Action completed', link: { url: 'https://app.pipedrive.com', label: 'View', }, }); ``` -------------------------------- ### Execute SDK Commands Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Commands are invoked via the execute method, which returns a promise. ```javascript sdk.execute(/* ... */) .then((data) => { // handle data }) .catch((err) => { // handle error }); try { const data = await sdk.execute(/* ... */); } catch (err) { // handle error } ``` -------------------------------- ### Open Activity Creation Modal Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Opens the native activity modal with support for dates, times, duration, and linked entities. ```javascript import AppExtensionsSDK, { Command, Modal } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.ACTIVITY, prefill: { subject: 'Follow-up phone call', dueDate: '2024-12-18', // yyyy-MM-dd format (UTC) dueTime: '14:30', // HH:mm format duration: '00:45', // HH:mm format note: 'Discuss contract terms and pricing options', description: 'Quarterly review call with stakeholders', deal: 12345, // Link to deal ID organization: 67890 // Link to organization ID } }); if (status === 'submitted') { console.log('Activity scheduled with ID:', id); } ``` -------------------------------- ### Open New Deal Modal with Prefill Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens the new deal modal, allowing prefilling of fields like title, organization, and person. The `id` of the created deal is returned upon submission. ```javascript const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.DEAL, prefill: { title: 'Important deal', }, }); ``` -------------------------------- ### Listen to User Settings Changes Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Monitor changes to user settings, such as theme preference updates. ```javascript import AppExtensionsSDK, { Event } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Set initial theme document.documentElement.setAttribute('data-theme', sdk.userSettings.theme); // Listen for theme changes sdk.listen(Event.USER_SETTINGS_CHANGE, ({ data }) => { console.log('New theme:', data.theme); // 'light' or 'dark' document.documentElement.setAttribute('data-theme', data.theme); // Update your app's styling updateAppTheme(data.theme); }); ``` -------------------------------- ### Redirect To View Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Redirect the user to a specific Pipedrive view or entity detail page, with optional context data for custom settings pages. ```APIDOC ## Redirect To View ### Description Redirect the user to a specific Pipedrive view or entity detail page, with optional context data for custom settings pages. ### Method `POST` (Implicit via `sdk.execute`) ### Endpoint `/` (Internal SDK command) ### Parameters #### Request Body - **view** (string) - Required - The Pipedrive view to redirect to (e.g., `View.DEALS`, `View.SETTINGS`). - **id** (number) - Optional - The ID of the entity to display (e.g., a specific deal ID). - **context** (object) - Optional - Context data for custom settings pages. - **tab** (string) - Optional - The specific tab within settings. - **action** (string) - Optional - An action to perform within the settings tab. ### Request Example ```javascript import AppExtensionsSDK, { Command, View } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Redirect to deals list view await sdk.execute(Command.REDIRECT_TO, { view: View.DEALS }); // Redirect to specific deal detail page await sdk.execute(Command.REDIRECT_TO, { view: View.DEALS, id: 12345 }); // Redirect to app settings with context await sdk.execute(Command.REDIRECT_TO, { view: View.SETTINGS, context: { tab: 'integrations', action: 'configure' } }); ``` ### Response None (Command execution) ### Response Example None ``` -------------------------------- ### New Person Modal Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens the modal to create a new person, with optional pre-filled fields. ```APIDOC ## New Person Modal ### Description Opens the Pipedrive new person creation modal. ### Parameters #### Request Body - **type** (Modal) - Required - Must be Modal.PERSON - **prefill** (Object) - Optional - Object to prefill person fields - **prefill.name** (String) - Optional - Person name - **prefill.organization** (String) - Optional - Organization name ### Response - **status** (String) - Indicates if modal was submitted or closed - **id** (Number) - Optional - ID of added person if submitted ### Request Example { "type": "Modal.PERSON", "prefill": { "name": "Some name", "organization": "Some organization" } } ``` -------------------------------- ### Show Floating Window Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Displays the app's floating window and triggers a visibility event. Context data can be passed to the event handler. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Show floating window with context data await sdk.execute(Command.SHOW_FLOATING_WINDOW, { context: { person_id: 42, action: 'call', phone: '+1-555-0123' } }); ``` -------------------------------- ### Listen to Visibility Events Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Subscribe to panel collapse/expand or floating window visibility changes. The callback provides visibility state and context data. ```javascript import AppExtensionsSDK, { Event } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); const stopListening = sdk.listen(Event.VISIBILITY, ({ error, data }) => { if (error) { console.error('Visibility event error:', error); return; } console.log('Visible:', data.is_visible); console.log('Invoker:', data.context?.invoker); // 'user' or 'command' console.log('Context:', data.context); if (data.is_visible) { // Refresh data when panel becomes visible refreshPanelData(); } }); // Later: stop receiving visibility events stopListening(); ``` -------------------------------- ### New Organization Modal Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens the modal to create a new organization, with optional pre-filled fields. ```APIDOC ## New Organization Modal ### Description Opens the Pipedrive new organization creation modal. ### Parameters #### Request Body - **type** (Modal) - Required - Must be Modal.ORGANIZATION - **prefill** (Object) - Optional - Object to prefill organization fields - **prefill.name** (String) - Optional - Organization name ### Response - **status** (String) - Indicates if modal was submitted or closed - **id** (Number) - Optional - ID of added organization if submitted ### Request Example { "type": "Modal.ORGANIZATION", "prefill": { "name": "Some organization" } } ``` -------------------------------- ### SHOW_CONFIRMATION Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Displays a confirmation dialog to the user with customizable text and button colors. ```APIDOC ## SHOW_CONFIRMATION ### Description Shows a confirmation dialog with a title, description, and configurable buttons. ### Parameters - **title** (String) - Required - The title of the dialog. - **description** (String) - Optional - A longer description of what is being confirmed. - **okText** (String) - Optional - Text for the confirm button (default: "OK"). - **cancelText** (String) - Optional - Text for the cancel button (default: "Cancel"). - **okColor** (Color) - Optional - Color of the confirmation button (Color.PRIMARY, Color.SECONDARY, Color.NEGATIVE). ### Response - **confirmed** (Boolean) - Result of the user's confirmation. ### Response Example { "confirmed": true } ``` -------------------------------- ### Apply Theme Styles Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Use the userSettings property to apply theme-specific CSS to the iframe. ```css [data-theme="dark"] body { // custom CSS for dark theme } ``` ```javascript import AppExtensionsSDK from '@pipedrive/app-extensions-sdk'; const sdk = new AppExtensionsSDK(); document.documentElement.setAttribute('data-theme', sdk.userSettings.theme); await sdk.initialize(); ``` -------------------------------- ### Open Custom Modal with Data Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Use this to open a custom modal. The `data` object is stringified JSON and should be used with caution due to potential length limitations. ```javascript const { status } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.CUSTOM_MODAL, action_id: 'Open settings', data: { item: 'xyz', }, }); ``` -------------------------------- ### Listen for user settings changes Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Registers a listener for the USER_SETTINGS_CHANGE event to track theme preference updates. ```javascript sdk.listen(Event.USER_SETTINGS_CHANGE, ({ data }) => { // handle data }); ``` -------------------------------- ### Event.VISIBILITY Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Subscribe to visibility changes triggered by the user or SDK commands. ```APIDOC ## Event.VISIBILITY ### Description Subscribe to visibility changes that are triggered by the user or an SDK command. ### Response - **is_visible** (Boolean) - Required - Specifies if the extension is visible to the user - **context** (Object) - Optional - Contains properties specific to extension - **context.invoker** (String) - Optional - Describes if the event was triggered by an SDK command or the user ### Response Example ```javascript sdk.listen(Event.VISIBILITY, ({ error, data }) => { // handle event }); ``` ``` -------------------------------- ### Redirect to Deals View Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Redirect the user to the Deals view, optionally specifying a particular deal ID and passing context for custom settings pages. ```javascript await sdk.execute(Command.REDIRECT_TO, { view: View.DEALS, id: 1, context: { foo: 'bar' } }); ``` -------------------------------- ### Subscribe to SDK events Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md General pattern for listening to events. The returned function should be called to unsubscribe. ```javascript const stopReceivingEvents = sdk.listen(event, ({ error, data }) => { // if error is present, handle error // handle data }); stopReceivingEvents(); // Call this function to stop receiving events ``` -------------------------------- ### New Deal Modal Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens the modal to create a new deal, with optional pre-filled fields. ```APIDOC ## New Deal Modal ### Description Opens the Pipedrive new deal creation modal. ### Parameters #### Request Body - **type** (Modal) - Required - Must be Modal.DEAL - **prefill** (Object) - Optional - Object to prefill deal fields - **prefill.title** (String) - Optional - Deal title - **prefill.organization** (String) - Optional - Organization name - **prefill.person** (String) - Optional - Person name ### Response - **status** (String) - Indicates if modal was submitted or closed - **id** (Number) - Optional - ID of created deal if submitted ### Request Example { "type": "Modal.DEAL", "prefill": { "title": "Important deal" } } ``` -------------------------------- ### REDIRECT_TO Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Redirects the user to a specified view within Pipedrive. ```APIDOC ## REDIRECT_TO ### Description Redirects user to a specified view. Supported views include DEALS, LEADS, ORGANIZATIONS, CONTACTS, CAMPAIGNS, PROJECTS, and SETTINGS. ### Parameters #### Request Body - **view** (View) - Required - The target view - **id** (String/Number) - Optional - ID of the entity to redirect to - **context** (Object) - Optional - Context object for custom settings redirects ### Request Example ```javascript await sdk.execute(Command.REDIRECT_TO, { view: View.DEALS, id: 1, context: { foo: 'bar' } }); ``` ``` -------------------------------- ### Handle SDK Command Errors with Promise Rejection Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Utilize promise chains with .catch() handlers to manage errors during asynchronous SDK operations like fetching tokens. This pattern is useful for sequential operations. ```javascript // Using promise chains sdk.execute(Command.GET_SIGNED_TOKEN) .then(({ token }) => { console.log('Token received:', token); return authenticateWithBackend(token); }) .catch((error) => { console.error('Authentication failed:', error.message); }); ``` -------------------------------- ### Show Confirmation Dialog Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Trigger a modal dialog that returns a promise based on user interaction. Use this for critical actions requiring confirmation. ```javascript import AppExtensionsSDK, { Command, Color } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Basic confirmation dialog const { confirmed } = await sdk.execute(Command.SHOW_CONFIRMATION, { title: 'Delete Contact', description: 'Are you sure you want to delete this contact? This action cannot be undone.' }); if (confirmed) { console.log('User confirmed deletion'); // Proceed with delete operation } else { console.log('User cancelled'); } // Confirmation with custom button text and colors const result = await sdk.execute(Command.SHOW_CONFIRMATION, { title: 'Archive Deal', description: 'This will move the deal to your archive.', okText: 'Archive', cancelText: 'Keep Active', okColor: Color.PRIMARY // Green button (Color.NEGATIVE for red, Color.SECONDARY for white) }); ``` -------------------------------- ### Listen for visibility changes Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Subscribes to events triggered when the extension visibility changes via user action or SDK command. ```javascript sdk.listen(Event.VISIBILITY, ({ error, data }) => { // handle event }); ``` -------------------------------- ### Listen to Page Visibility State Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Detect when the extension's page becomes visible or hidden in the browser tab. ```javascript import AppExtensionsSDK, { Event } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); const stopListening = sdk.listen(Event.PAGE_VISIBILITY_STATE, ({ data }) => { console.log('Page state:', data.state); // 'visible' or 'hidden' if (data.state === 'visible') { // Resume real-time updates when tab becomes active startPolling(); } else { // Pause updates when tab is in background stopPolling(); } }); // Stop listening when no longer needed stopListening(); ``` -------------------------------- ### Retrieve main window metadata Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Fetches the current dimensions of the main window. ```javascript const { windowWidth, windowHeight } = await sdk.execute(Command.GET_METADATA); ``` -------------------------------- ### OPEN_MODAL Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens various types of modals including JSON modals and standard Pipedrive entity modals. ```APIDOC ## OPEN_MODAL ### Description Opens a JSON modal, custom modal, or standard Pipedrive entity modal. ### Parameters - **type** (Modal) - Required - The type of modal to open. - **action_id** (String) - Required - The JSON modal action ID or name. ### Response - **status** (String) - Indicates if the modal was submitted or closed. ### Response Example { "status": "submitted" } ``` -------------------------------- ### Open Person Creation Modal Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Opens the native contact creation modal. Returns the submission status and the new person ID. ```javascript import AppExtensionsSDK, { Command, Modal } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); const { status, id } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.PERSON, prefill: { name: 'Jane Doe', organization: 'Tech Startup Inc' } }); if (status === 'submitted') { console.log('Person created with ID:', id); } ``` -------------------------------- ### Open JSON Modal Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Opens a modal configured via the Marketplace Manager using a JSON action ID. ```javascript import AppExtensionsSDK, { Command, Modal } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); const { status } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.JSON_MODAL, action_id: 'quick-settings' }); console.log('JSON modal closed with status:', status); ``` -------------------------------- ### Redirect to Pipedrive Views Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Navigates the user to specific Pipedrive views or entity detail pages. Supports optional context data for settings pages. ```javascript import AppExtensionsSDK, { Command, View } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Redirect to deals list view await sdk.execute(Command.REDIRECT_TO, { view: View.DEALS }); // Redirect to specific deal detail page await sdk.execute(Command.REDIRECT_TO, { view: View.DEALS, id: 12345 }); // Redirect to app settings with context await sdk.execute(Command.REDIRECT_TO, { view: View.SETTINGS, context: { tab: 'integrations', action: 'configure' } }); // Available views: View.DEALS, View.LEADS, View.ORGANIZATIONS, // View.CONTACTS, View.CAMPAIGNS, View.PROJECTS, View.SETTINGS ``` -------------------------------- ### Open Custom Modal Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Opens a custom modal defined in the app configuration, allowing data to be passed to the iframe. ```javascript import AppExtensionsSDK, { Command, Modal } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Open custom modal with data payload const { status } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.CUSTOM_MODAL, action_id: 'settings-modal', data: { userId: '12345', mode: 'advanced' } }); console.log('Modal status:', status); // 'submitted' or 'closed' ``` -------------------------------- ### Show confirmation dialog Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Displays a confirmation dialog to the user and returns the confirmation result. ```javascript const { confirmed } = await sdk.execute(Command.SHOW_CONFIRMATION, { title: 'Confirm', description: 'Are you sure you want to complete this action?', }); ``` -------------------------------- ### RESIZE Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Resizes the custom UI extension (panel, modal, or floating window) within specified constraints. ```APIDOC ## RESIZE ### Description Resizes the custom UI extension. Constraints vary based on the UI type (Custom panel, modal, or floating window). ### Parameters - **height** (Number) - Optional - Height of the custom UI extension. - **width** (Number) - Optional - Width of the custom UI extension. ``` -------------------------------- ### USER_SETTINGS_CHANGE Event Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Subscribe to updates when user settings, such as the interface theme, are modified. ```APIDOC ## USER_SETTINGS_CHANGE ### Description This event triggers when any user settings have changed. ### Response - **theme** (String) - The selected theme interface preference. Possible values: light, dark. ### Request Example ```javascript sdk.listen(Event.USER_SETTINGS_CHANGE, ({ data }) => { // handle data }); ``` ``` -------------------------------- ### Resize Custom UI Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Adjust the dimensions of the extension panel, modal, or floating window dynamically. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Resize panel height only (panels: 100-750px height) await sdk.execute(Command.RESIZE, { height: 400 }); // Resize modal with both dimensions (modals: min 320x120px, max limited by browser) await sdk.execute(Command.RESIZE, { height: 600, width: 800 }); // Resize floating window (height: 70-700px, width: 200-800px) await sdk.execute(Command.RESIZE, { height: 350, width: 450 }); ``` -------------------------------- ### Open JSON modal Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens a modal window based on the provided modal type and action ID. ```javascript const { status } = await sdk.execute(Command.OPEN_MODAL, { type: Modal.JSON_MODAL, action_id: 'Open settings', }); ``` -------------------------------- ### Command.SET_FOCUS_MODE Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Enables or disables focus mode for floating windows. ```APIDOC ## SET_FOCUS_MODE ### Description Enables or disables focus mode. When enabled, the close button in the window header is hidden. ### Request Example ```javascript await sdk.execute(Command.SET_FOCUS_MODE, true); ``` ``` -------------------------------- ### PAGE_VISIBILITY_STATE Event Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Subscribe to changes in the page visibility state to determine if the app extension is in the foreground or background. ```APIDOC ## PAGE_VISIBILITY_STATE ### Description Subscribe to the page visibility event that is triggered when the value of the visibilityState property changes. ### Parameters - **state** (String) - Required - Indicates if the page is visible for the user. Possible values: 'visible' (page is foreground tab), 'hidden' (page is background tab or minimized). ### Request Example ```javascript const stopReceivingPageStateEvent = sdk.listen(Event.PAGE_VISIBILITY_STATE, ({ data }) => { // handle data }); stopReceivingPageStateEvent() // Call this function to stop receiving event ``` ``` -------------------------------- ### GET_SIGNED_TOKEN Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Generates a new JWT valid for 5 minutes for server-side verification. ```APIDOC ## GET_SIGNED_TOKEN ### Description Generates a new JSON Web Token (JWT) containing Pipedrive user and company IDs, valid for 5 minutes. ### Response - **token** (String) - The generated JWT. ### Response Example { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` -------------------------------- ### Custom Modal Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Opens a custom modal window with a specific action ID and optional data payload. ```APIDOC ## Custom Modal ### Description Opens a custom modal window identified by an action_id. ### Parameters #### Request Body - **type** (Modal) - Required - Must be Modal.CUSTOM_MODAL - **action_id** (String) - Required - Custom modal id or name - **data** (Object) - Optional - Object to be passed as stringified JSON to iframe ### Response - **status** (String) - Indicates if modal was submitted or closed ### Request Example { "type": "Modal.CUSTOM_MODAL", "action_id": "Open settings", "data": { "item": "xyz" } } ``` -------------------------------- ### Command.SET_NOTIFICATION Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Displays or removes a notification badge in the apps dock. ```APIDOC ## SET_NOTIFICATION ### Description Display or remove notifications badge in apps dock. Not specifying the number or setting it to 0 removes the badge. ### Parameters #### Request Body - **number** (Number) - Optional - Number of notifications ### Request Example ```javascript await sdk.execute(Command.SET_NOTIFICATION, { number: 3, }); ``` ``` -------------------------------- ### Listen for custom modal closure Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Subscribes to events triggered when a custom modal is closed by the user or the CLOSE_MODAL command. ```javascript sdk.listen(Event.CLOSE_CUSTOM_MODAL, () => { // handle event }); ``` -------------------------------- ### Subscribe to page visibility state Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Registers a listener for the PAGE_VISIBILITY_STATE event and provides a function to unsubscribe. ```javascript const stopReceivingPageStateEvent = sdk.listen(Event.PAGE_VISIBILITY_STATE, ({ data }) => { // handle data }); stopReceivingPageStateEvent() // Call this function to stop receiving event ``` -------------------------------- ### Command.HIDE_FLOATING_WINDOW Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Closes a floating window and triggers the VISIBILITY event. ```APIDOC ## HIDE_FLOATING_WINDOW ### Description Closes a floating window and triggers `Event.VISIBILITY` with an optional `context` parameter. ### Parameters #### Request Body - **context** (Object) - Optional - Object to be passed as JSON to event handler ### Request Example ```javascript await sdk.execute(Command.HIDE_FLOATING_WINDOW, { context: { person_id: 42, }, }); ``` ``` -------------------------------- ### Resize custom UI extension Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Adjusts the dimensions of the custom UI extension. Constraints on height and width vary by extension type. ```javascript await sdk.execute(Command.RESIZE, { height: 500 }); ``` -------------------------------- ### Hide Floating Window Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Hide the floating window and trigger a visibility event with optional context data. ```APIDOC ## Hide Floating Window ### Description Hide the floating window and trigger a visibility event with optional context data. ### Method `POST` (Implicit via `sdk.execute`) ### Endpoint `/` (Internal SDK command) ### Parameters #### Request Body - **context** (object) - Optional - Context data to pass to the visibility event. - **call_ended** (boolean) - Example context field. - **duration** (number) - Example context field. ### Request Example ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); await sdk.execute(Command.HIDE_FLOATING_WINDOW, { context: { call_ended: true, duration: 245 } }); ``` ### Response None (Command execution) ### Response Example None ``` -------------------------------- ### Listen to Custom Modal Close Events Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Subscribe to events triggered when a custom modal is closed by the user or programmatically. ```javascript import AppExtensionsSDK, { Event } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); sdk.listen(Event.CLOSE_CUSTOM_MODAL, () => { console.log('Custom modal was closed'); // Refresh parent panel data after modal closes refreshPanelData(); }); ``` -------------------------------- ### Set Focus Mode Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Enable or disable focus mode for floating windows. When enabled, the close button is hidden to prevent accidental closure during critical operations like phone calls. ```APIDOC ## Set Focus Mode ### Description Enable or disable focus mode for floating windows. When enabled, the close button is hidden to prevent accidental closure during critical operations like phone calls. ### Method `POST` (Implicit via `sdk.execute`) ### Endpoint `/` (Internal SDK command) ### Parameters #### Request Body - **enabled** (boolean) - Required - `true` to enable focus mode (hide close button), `false` to disable (show close button). ### Request Example ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Enable focus mode (hide close button) await sdk.execute(Command.SET_FOCUS_MODE, true); // Disable focus mode (show close button) await sdk.execute(Command.SET_FOCUS_MODE, false); // Example: Call handling with focus mode async function startCall() { await sdk.execute(Command.SET_FOCUS_MODE, true); // ... call in progress } async function endCall() { await sdk.execute(Command.SET_FOCUS_MODE, false); await sdk.execute(Command.HIDE_FLOATING_WINDOW, { context: { call_completed: true } }); } ``` ### Response None (Command execution) ### Response Example None ``` -------------------------------- ### Show Snackbar Notification Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Display a temporary notification message at the bottom of the screen, optionally including a clickable link. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Simple snackbar with message only await sdk.execute(Command.SHOW_SNACKBAR, { message: 'Contact saved successfully' }); // Snackbar with message and action link await sdk.execute(Command.SHOW_SNACKBAR, { message: 'Deal created successfully', link: { url: 'https://app.pipedrive.com/deal/12345', label: 'View Deal' } }); ``` -------------------------------- ### Retrieve Signed JWT Token Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Use this to obtain a token for secure server-side verification. The token expires after 5 minutes and must be refreshed. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Get signed JWT token const { token } = await sdk.execute(Command.GET_SIGNED_TOKEN); // Use token in API requests for server-side verification const response = await fetch('https://your-api.com/data', { headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }); // Token refresh (call again when token expires after 5 minutes) async function getAuthenticatedData() { const { token } = await sdk.execute(Command.GET_SIGNED_TOKEN); return fetch('https://your-api.com/secure-endpoint', { headers: { 'Authorization': `Bearer ${token}` } }); } ``` -------------------------------- ### Close Modal with Pipedrive SDK Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Closes the active custom modal from within the iframe. Requires initialization of the AppExtensionsSDK. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Close modal after completing an action async function saveAndClose(data) { await saveDataToServer(data); await sdk.execute(Command.CLOSE_MODAL); } ``` -------------------------------- ### Enable focus mode for floating window Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Hides the close button in the window header to prevent accidental closure. The window must be visible before calling this. ```javascript await sdk.execute(Command.SET_FOCUS_MODE, true); ``` -------------------------------- ### Hide Floating Window Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Hides the floating window and triggers a visibility event. Optional context data can be included. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Hide floating window with context await sdk.execute(Command.HIDE_FLOATING_WINDOW, { context: { call_ended: true, duration: 245 } }); ``` -------------------------------- ### Close Active Modal Source: https://github.com/pipedrive/app-extensions-sdk/blob/master/README.md Call this command to close any currently open custom modal window. Ensure you are within a custom modal context when executing this. ```javascript await sdk.execute(Command.CLOSE_MODAL); ``` -------------------------------- ### Set Notification Badge Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Updates the notification badge on the app's dock icon. Setting the number to 0 removes the badge. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Show notification badge with count await sdk.execute(Command.SET_NOTIFICATION, { number: 5 }); // Remove notification badge await sdk.execute(Command.SET_NOTIFICATION, { number: 0 }); // Dynamic notification updates async function updateNotificationCount() { const unreadCount = await fetchUnreadMessages(); await sdk.execute(Command.SET_NOTIFICATION, { number: unreadCount }); } ``` -------------------------------- ### Set Focus Mode Source: https://context7.com/pipedrive/app-extensions-sdk/llms.txt Toggles focus mode for floating windows, which hides the close button to prevent accidental closure. ```javascript import AppExtensionsSDK, { Command } from '@pipedrive/app-extensions-sdk'; const sdk = await new AppExtensionsSDK().initialize(); // Enable focus mode (hide close button) await sdk.execute(Command.SET_FOCUS_MODE, true); // Disable focus mode (show close button) await sdk.execute(Command.SET_FOCUS_MODE, false); // Example: Call handling with focus mode async function startCall() { await sdk.execute(Command.SET_FOCUS_MODE, true); // ... call in progress } async function endCall() { await sdk.execute(Command.SET_FOCUS_MODE, false); await sdk.execute(Command.HIDE_FLOATING_WINDOW, { context: { call_completed: true } }); } ```