# OneClick > OneClick adds Buttons to Pipedrive. This is the documentation for OneClick, Interface Builder and the Partner Portal, and the Changelog. --- # Getting started Source: https://help.theoneclick.io/docs/getting-started.md ## What is OneClick OneClick is a Pipedrive app that adds Buttons to Pipedrive. An admin makes the Buttons in OneClick. A Pipedrive user presses a Button to start a process at the correct time. ## The problem that OneClick solves Pipedrive has no custom buttons. An automation must find out by itself when to start. It must read many Pipedrive webhooks or read a filter again and again. Most of these webhooks and reads do not start a process. The user also does not see if the process started, completed or stopped with an error. With OneClick, the user decides when the process starts. The user presses a Button, and OneClick shows the result to the user. ## Where the Buttons are The Panel is the OneClick area in the sidebar of a Pipedrive deal, person or organization. A Button in the Panel belongs to that record. ![The OneClick Panel in the sidebar of a Pipedrive deal, with a list of Buttons](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/getting-started/panel-with-buttons.png) The Floating window floats over Pipedrive and stays open when the user moves to another page. A Button in the Floating window belongs to no record. ## What a Button does OneClick has three Button types: - A **Workflow button** sends the data of the Pipedrive record to a URL. The URL can be a Make scenario, a Zapier Zap or your own server. The data can include field values, user data and deal products. - A **Link button** opens a URL that it makes from the Pipedrive field values. - An **Interface button** opens an Interface view. The admin builds the Interface view in Interface Builder. A Button can ask the user to fill in fields before OneClick sends the data. Required fields must have a value. Your automation can send messages back to the user, for example the status of the process. ## Steps to start 1. A Pipedrive global admin installs OneClick. See [Install OneClick as a global admin](/docs/getting-started/install). 2. The admin makes the Buttons in the OneClick settings. See [Buttons](/docs/buttons). 3. Each user installs OneClick. See [Install OneClick as a user](/docs/getting-started/install-as-a-user). 4. The users press the Buttons. See [Use Buttons](/docs/use-buttons). Pipedrive apps are user specific: each user installs OneClick for himself or herself. The Buttons and the settings apply to all users in the company. --- # Install OneClick as a global admin Source: https://help.theoneclick.io/docs/getting-started/install.md This page is for the Pipedrive global admin who installs OneClick first in the company. The first installation in a company must be done by a Pipedrive global admin. For the global permissions, see [Global user management](https://support.pipedrive.com/en/article/global-user-management#global-permissions) in the Pipedrive help. If a user who is not an admin installs OneClick first, OneClick shows the error **No privileges to do initial installation**. ## Install OneClick 1. Sign in to Pipedrive as a global admin. 2. Open the [OneClick page in the Pipedrive Marketplace](https://www.pipedrive.com/en/marketplace/app/one-click/de8c9f16a3a18391). 3. Click **Install now**. 4. If your Pipedrive user has access to more than one company, select the company for OneClick. 5. Read the permissions that OneClick asks for. 6. Click **Allow and install**. OneClick opens the **Terms and conditions** page. 7. Read the terms and conditions. 8. Click **Agree**. OneClick shows the page **Oneclick installed**. 9. Click **Back to Pipedrive**. 10. Open a deal, a person or an organization. The Panel shows in the sidebar. If the Panel does not show, refresh the Pipedrive page in your browser. The Panel has no Buttons after the installation. It shows **No buttons yet**. The **Settings** button is at the bottom of the Panel. ## Next steps 1. Make your Buttons. See [Buttons](/docs/buttons). 2. Tell the other users to install OneClick. Each user installs OneClick for himself or herself. See [Install OneClick as a user](/docs/getting-started/install-as-a-user). 3. Give a seat to each user who must use the Buttons. You do this on the **Users** tab of the OneClick settings. See [Users](/docs/settings/users). --- # Install OneClick as a user Source: https://help.theoneclick.io/docs/getting-started/install-as-a-user.md This page is for a Pipedrive user who is not a global admin. Pipedrive apps are user specific. Each user must install OneClick for himself or herself. The Buttons and the settings apply to all users in the company. Before you start, make sure that a Pipedrive global admin installed OneClick in your company. If no admin installed OneClick first, OneClick shows the error **No privileges to do initial installation**. See [Install OneClick as a global admin](/docs/getting-started/install). ## Install OneClick 1. Open the [OneClick page in the Pipedrive Marketplace](https://www.pipedrive.com/en/marketplace/app/one-click/de8c9f16a3a18391). 2. Click **Install now**. 3. If your Pipedrive user has access to more than one company, select the company for OneClick. 4. Read the permissions that OneClick asks for. 5. Click **Allow and install**. OneClick shows the page **Oneclick installed**. 6. Click **Back to Pipedrive**. 7. Open a deal, a person or an organization. The Panel shows in the sidebar. If the Panel does not show, refresh the Pipedrive page in your browser. ## If OneClick shows "Seat limit reached" You must have a seat to use OneClick. If OneClick gives no seat to you, it shows the error **Seat limit reached** after the installation. OneClick is installed, but you cannot use the Buttons. Ask your admin to give you a seat. The admin gives seats on the **Users** tab of the OneClick settings. The admin can also set OneClick to give a seat to each new user automatically. --- # Uninstall OneClick Source: https://help.theoneclick.io/docs/getting-started/uninstall.md Pipedrive apps are user specific. Each user must uninstall OneClick for himself or herself. Before you uninstall OneClick, tell us about missing details or features. Send your questions and comments to [support@theoneclick.io](mailto:support@theoneclick.io). ## Remove OneClick from Pipedrive 1. In Pipedrive, click your profile icon in the top right corner. 2. Click **Tools and apps**. 3. In the left menu, click **Installed apps**. The page **Marketplace apps** opens. 4. Click **OneClick**. 5. Click **Uninstall**. ## What happens to your data - An uninstall removes OneClick only for your Pipedrive user. The Buttons and settings of your company stay. - When the last user in your company uninstalls OneClick, OneClick keeps the Buttons and settings, but no user can use them. - When a global admin installs OneClick again, the Buttons and settings come back. - If no global admin in your company has OneClick installed, the other users can see the error **Missing admin user installation**. Ask a global admin to install OneClick again. --- # Use Buttons Source: https://help.theoneclick.io/docs/use-buttons.md This page is for Pipedrive users who press Buttons. Your admin makes the Buttons. For questions about the process that a Button starts, speak to your admin. ## The Panel The Panel is the OneClick area in the sidebar of a Pipedrive deal, person or organization. A Button in the Panel belongs to that record. When you press it, OneClick uses the data of that record. ![The OneClick Panel in the sidebar of a Pipedrive deal, with a list of Buttons](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/use-buttons/panel-with-buttons.png) If the Panel shows **Hover here to reveal buttons**, your admin turned on **Reveal on hover**. Move the mouse pointer over the Panel. OneClick then loads the Buttons. This setting decreases the number of Pipedrive API calls. ### Button groups Your admin can put Buttons in groups. A group has a header with the group name and the number of Buttons. - Click the group header to open or close the group. - To keep a group open, move the mouse pointer over the group header and click the pin icon. The pin applies only to your browser. ## The Floating window The Floating window floats over Pipedrive. It stays open when you move to another page in Pipedrive. A Button in the Floating window belongs to no record, so it does not use the data of a deal, person or organization. To open the Floating window, click the OneClick icon in the top bar of Pipedrive. To close it, click the **X** icon. ![The OneClick Floating window over a Pipedrive page, with two Buttons](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/use-buttons/floating-window.png) The Panel and the Floating window have different Buttons. You cannot press a Panel Button in the Floating window. ## The icons on a Button | Icon | Meaning | | ------------------------------------- | --------------------------------------------------------------------------------------------- | | Arrow (**>**) after the Button name | The Button has fields. See [Fill in the fields](/docs/use-buttons/fill-in-fields). | | Open-in-new icon after the Button name | In the Panel, this icon marks a Link button. It opens a page in a new tab or a pop-up window. | | Info icon (**i**) at the right | The Button has a description. See [Press a Button](/docs/use-buttons/press-a-button). | | Envelope icon at the right | The Button has messages. See [Read messages](/docs/use-buttons/messages). | | Layout icon at the right | Only admins see this icon on an Interface button. It opens Interface Builder. | ## Next steps - [Press a Button](/docs/use-buttons/press-a-button) - [Fill in the fields](/docs/use-buttons/fill-in-fields) - [Read messages](/docs/use-buttons/messages) - [Use an Interface view](/docs/use-buttons/use-an-interface-view) - [Why no Buttons show](/docs/use-buttons/no-buttons) --- # Press a Button Source: https://help.theoneclick.io/docs/use-buttons/press-a-button.md This page is for Pipedrive users who press Buttons. ## Press a Button 1. Open a deal, a person or an organization in Pipedrive. To use a Floating window Button, open the Floating window. 2. Find the Button in the Panel or in the Floating window. If the Panel shows **Hover here to reveal buttons**, move the mouse pointer over it. 3. Click the Button. What happens next depends on the Button type: - A **Workflow button** sends the data of the record to the process that your admin connected. The process starts. - A **Link button** opens a page in a new browser tab or in a pop-up window. The address of the page can contain values from the record. - An **Interface button** opens an Interface view. See [Use an Interface view](/docs/use-buttons/use-an-interface-view). ## Steps before OneClick sends the data A Workflow button can show one or more views before OneClick sends the data. Your admin sets these views. 1. **Fields.** The Button shows fields. Examine the values, fill in the empty fields and click the Button again. See [Fill in the fields](/docs/use-buttons/fill-in-fields). 2. **Confirmation.** The Button asks you to confirm the press. The default text is **Are you sure you want to trigger this button?** Click **Yes** to continue or **Cancel** to stop. Your admin can change these texts. 3. **Deal products.** On a deal, the Button can send the products of the deal. If the products are required and the deal has no products, OneClick shows **Deal products are required. Please add at least 1 product and try again.** Add a product to the deal in Pipedrive and press the Button again. To go back to the list of Buttons, click **Back**. ## Read the description of a Button A Button with an info icon (**i**) has a description. The description can tell you what the Button does and when to use it. 1. Click the info icon at the right of the Button. OneClick shows the description. 2. To press the Button, click the Button above the description. 3. To go back to the list of Buttons, click **Back**. ![The description of the Button Create invoice in the OneClick Panel, with Back and the Button above the description](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/use-buttons/press-a-button/description-view.png) ## The result of a press - While OneClick sends the data, the Button shows a loading indicator. - Your admin can set the Button to show the answer of the process. A green check mark on the Button means that the process accepted the data. The check mark goes away after 2 seconds. - A red exclamation mark on the Button means that the process did not accept the data. Click the exclamation mark. OneClick shows **Failed** and the message from the process. - Your admin can set the process to send messages to you. See [Read messages](/docs/use-buttons/messages). ## When you cannot press a Button A Button that you cannot press is gray. Move the mouse pointer over the Button to see the reason. - **Cooldown.** Your admin can block a Button for some seconds after a press. The Button then shows a circle that fills up. When the circle is full, you can press the Button again. - **Unread messages.** Your admin can block a Button until you read its messages or its error messages. Read the messages. See [Read messages](/docs/use-buttons/messages). - **Missing deal products.** The Button needs deal products, and the deal has none. If a Link button shows **The browser blocked the window. Allow pop-ups for OneClick and press again.**, allow pop-up windows for OneClick in your browser settings. Then press the Button again. --- # Fill in the fields Source: https://help.theoneclick.io/docs/use-buttons/fill-in-fields.md This page is for Pipedrive users who press Buttons. A Button with an arrow (**>**) after its name has fields. When you click the Button, OneClick shows the fields before it sends the data. You can then examine the data, and add data that the process needs. ![The fields of the Button Approve discount in the OneClick Panel, with the deal field ID](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/use-buttons/fill-in-fields/fields-view.png) ## Send the data with fields 1. Click the Button. OneClick gets the field values from Pipedrive and shows the fields. 2. Examine the values of the Pipedrive fields. 3. Fill in the fields that you can edit. 4. Click the Button at the top of the fields. OneClick examines the fields. If all fields are valid, OneClick sends the data. To go back to the list of Buttons without a press, click **Back**. ## The types of fields An icon at the left of the field name tells you where the value comes from: - **Deal icon**, **person icon** or **organization icon**: a Pipedrive field of the deal, the person or the organization. You cannot edit the value in OneClick. - **Circular arrow icon**: a disposable field. You fill in the value in OneClick. OneClick sends the value with this press only, and does not save it in Pipedrive. A disposable field can be text, a number, a date, an email address, a check box, a list of options, Pipedrive users or a Pipedrive filter. Your admin can give a field a default value. Your admin can also add headers, labels and dividers between the fields. These help you to read the fields. ## Change a Pipedrive field value You cannot edit a Pipedrive field in OneClick. 1. Change the value in the deal, the person or the organization in Pipedrive. 2. In OneClick, click the refresh icon at the left of the Button. OneClick gets the values from Pipedrive again. 3. Click the Button. ## Required fields and errors A field name with an asterisk (**\***) is a required field. A required field must have a value. When you click the Button, OneClick examines the fields. If a field is not valid, OneClick does not send the data. It shows a red border and an error message at the field. Move the mouse pointer over the Button to see **Some fields are invalid or incomplete**. A field is not valid in these cases: - A required field has no value. - A field must be empty, but it has a value. The default error message is **Field must be empty**. For example, a field that holds an invoice number must be empty, so that you do not make the same invoice two times. - The value does not agree with a rule of your admin, for example a number range or a date range. Your admin writes the error message for each rule. ![The fields of the Button Create invoice in the OneClick Panel: Invoice reference has a red border and the error message Type the invoice reference](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/use-buttons/fill-in-fields/field-error.png) If a rule applies to more than one field, OneClick shows the error message above the fields. If there is more than one error, click **Show more (N)** to see all errors. N is the number of the other errors. Correct the values and click the Button again. ## A Button with hidden fields Your admin can hide fields. If all fields are hidden and valid, OneClick does not show the fields. It shows **Sending...** and sends the data. If a hidden field is not valid, OneClick shows the field and its error message. --- # Read messages Source: https://help.theoneclick.io/docs/use-buttons/messages.md This page is for Pipedrive users who press Buttons. Your admin can set the process of a Button to send messages to you. A message can tell you the status of the process, for example that the process completed or stopped with an error. When a Button has messages, an envelope icon shows at the right of the Button. ## The envelope icon | Envelope icon | Meaning | | --------------------- | --------------------------------------------- | | Blue, with a dot | The Button has unread messages. | | Red, with a dot | The Button has unread error messages. | | Gray | You read all messages. | ## Read the messages 1. Click the envelope icon at the right of the Button. OneClick shows the messages of the Button. 2. Read the messages. OneClick marks a message as read when it shows on your screen. 3. If a message is long, click **[ show more ]** to see all of the text. 4. To go back to the list of Buttons, click **Back**. ![The messages of the Button Notify the team in the OneClick Panel: the message Ok with a blue dot, its date and time, and Mark All Read](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/use-buttons/messages/messages-view.png) Each message has a colored dot and the date and time of the message. The color of the dot tells you the type of the message: success, information or warning. An error message has a red error icon and a red background. An unread message has dark text. A read message has gray text. The list can also show the messages of other users who pressed the Button. These messages show as read. ## Mark all messages as read 1. Click the envelope icon at the right of the Button. 2. Click **Mark All Read**. OneClick marks all messages of the Button as read. ## Messages that block a Button Your admin can block a Button until you read its messages. The Button is then gray, and you cannot press it. Move the mouse pointer over the Button to see the reason: - **You cannot press the button because there are unread errors**: read the error messages. - **You cannot press the button because there are unread messages**: read all messages. Read the messages, or click **Mark All Read**. You can then press the Button again. ## A link in a message The process can send a link with a message. OneClick then opens the link in a new browser tab after the press. The message shows the link. --- # Use an Interface view Source: https://help.theoneclick.io/docs/use-buttons/use-an-interface-view.md This page is for Pipedrive users who press Buttons. An Interface button opens an Interface view. Your admin builds the Interface view in Interface Builder. An Interface view can show data in tables and text, and it can have forms that you fill in and send. The content of each Interface view is different. For questions about a view, speak to your admin. ## Open an Interface view 1. Open the deal, the person or the organization in Pipedrive. 2. Click the Interface button in the Panel. A window with the title **OneClick Interface** opens over Pipedrive and shows the Interface view. 3. Wait until the Interface view loads its data. ![The OneClick Interface window with the Interface view Group info for an organization, with a deal scope, yearly totals and a table](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/use-buttons/use-an-interface-view/interface-view.png) An Interface button in the Panel gives the Interface view the data of the record. An Interface button in the Floating window gives no record data to the Interface view. Its Interface view gets its data from other sources. ## Work in an Interface view - To fill in a form, type or select the values. Then click the button of the form that sends the values. - An Interface button can open more than one Interface view. A button or a link in one Interface view can open the next one. - To close the Interface view, click the **X** icon at the top right of the window. ## If the Interface view does not open - If the window shows **No interface found for this button**, the Button has no Interface view yet. Tell your admin. - In the Floating window, OneClick can show **Couldn’t refresh authentication. Please try again.** Press the Button again. ## For admins An admin sees a layout icon at the right of each Interface button in the Panel. Click the icon to open the Interface view in Interface Builder. See [Interface Builder](/docs/buttons/interface-button/interface-builder). --- # Why no Buttons show Source: https://help.theoneclick.io/docs/use-buttons/no-buttons.md This page is for Pipedrive users who press Buttons. ## "Nothing to see here" ![The OneClick Panel of a Pipedrive person with no Buttons: Nothing to see here and No buttons visible in this context](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/use-buttons/no-buttons/nothing-to-see-here.png) The Panel shows **Nothing to see here** and **No buttons visible in this context**. OneClick has Buttons, but no Button applies to this record or to you. Your admin can limit where a Button shows: - **Record type.** A Button can show only on deals, persons or organizations. For example, a deal Button does not show on an organization. - **Pipeline and stage.** A deal Button can show only in some pipelines or in some stages. - **Users and groups.** A Button can show only for some users or for the users in some groups. If you need a Button that does not show, ask your admin. ## "No buttons yet" The Panel or the Floating window shows **No buttons yet** and **Go to settings to create your first button**. Your company has no Buttons in this place. An admin must make the Buttons first. See [Buttons](/docs/buttons). The Panel and the Floating window have different Buttons. A company can have Panel Buttons and no Floating window Buttons. ## "Hover here to reveal buttons" The Panel shows **Hover here to reveal buttons**. This is not an error. Move the mouse pointer over the Panel. OneClick then loads the Buttons. ## The Panel does not show If the OneClick Panel does not show in the sidebar, refresh the Pipedrive page in your browser. If the Panel still does not show, install OneClick for your Pipedrive user. See [Install OneClick as a user](/docs/getting-started/install-as-a-user). If OneClick shows **Seat limit reached**, you have no OneClick seat. Ask your admin to give you a seat. --- # Buttons Source: https://help.theoneclick.io/docs/buttons.md This page is for admins who make Buttons. A Button is an action that you configure in OneClick. A Pipedrive user presses it in the Panel or in the Floating window. For the view of the user, see [Use Buttons](/docs/use-buttons). ## Select the Button type OneClick has three Button types. | Button type | What a press does | Use it when | | ----------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [Workflow button](/docs/buttons/workflow-button) | Sends the data of the Pipedrive record to a URL. | A process must start, for example a Make scenario, a Zap or your own server. | | [Link button](/docs/buttons/link-button) | Opens a URL that OneClick builds from Pipedrive field values. | The user must go to a page, for example a form, a registry or an invoice tool. | | [Interface button](/docs/buttons/interface-button) | Opens an Interface view that you build in Interface Builder. | The user must see data or fill in a form in a screen inside Pipedrive. | Some questions help you to select: - Must the press start a process in another system? Use a Workflow button. A Workflow button can also show fields before it sends the data, and it can show messages from the process. - Must the user only open a page in a browser tab or a pop-up window? Use a Link button. - Must the user work in a screen with tables, forms or other blocks? Use an Interface button. In the Settings, the **Create new** menu shows the Interface button with the label **BETA**. ## Select the place: the Panel or the Floating window A Button is in one of two places. You select the place when you make the Button. | Place | Where the user finds it | Data of a Pipedrive record | | --------------- | ------------------------------------------------------------------------------- | -------------------------- | | Panel | In the sidebar of a deal, a person or an organization. | Yes: the open record. | | Floating window | In a window over Pipedrive. The user opens it with the OneClick icon in the top bar. | No. | A Panel Button belongs to the record that the user has open. When the user presses it, OneClick uses the data of that deal, person or organization. The Floating window stays open when the user goes to another page in Pipedrive. Thus it cannot belong to a record. Use it for actions that do not apply to one record, for example a batch process or a general action. The Panel and the Floating window have different Buttons. A user cannot press a Panel Button in the Floating window, or a Floating window Button in the Panel. ### A Floating window Button gets no Pipedrive record A Floating window Button gets no data from a deal, a person or an organization. Do not make a Floating window Button for an action that needs the data of a record. OneClick removes the settings that need a record from a Floating window Button: - **Workflow button.** The fields can only be fields that the user fills in, and headers, labels and dividers. Deal, person and organization fields are not available. The editor has no **Products** section and no **Interface** section. - **Link button.** The URL can only contain text and values of the user who presses the Button. - **Interface button.** The Interface views get no deal, person or organization data. They can show data from your own data source and the data of the user. - **Limit visibility.** You can limit the Button only by users and groups. See [Limit visibility](/docs/buttons/limit-visibility). If you save a Floating window Button with a setting that needs a record, OneClick shows an error, for example **Floating window buttons can only use disposable fields and UI elements**. ## Make a Button 1. Open a deal, a person or an organization in Pipedrive. 2. Click **Settings** at the bottom of the OneClick Panel. The Settings open on the **Buttons** tab. 3. Click the **Panel** tab or the **Floating window** tab. The number after the name is the number of Buttons in that place. 4. Click **Create new**. The menu shows the place of the new Button, for example **NEW FLOATING WINDOW BUTTON**. 5. Click **Workflow button**, **Link button** or **Interface button**. The Button editor opens. 6. Set the Button. The pages of each Button type tell you how. 7. Click **Save**. ![The Buttons tab of the OneClick Settings with the Panel tab and the Floating window tab and a list of Panel Buttons](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/settings-buttons-tab.png) ![The Create new menu on the Floating window tab, with the header New floating window button and the three Button types](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/create-new-floating-window-button.png) You cannot move a Button to the other place later. To have the same Button in the other place, make a new Button on the other tab. ## Settings for all Button types - [Limit visibility](/docs/buttons/limit-visibility): show a Button only for some records, pipelines, stages, users or groups. - [Manage Buttons](/docs/buttons/manage-buttons): sort, group, duplicate and delete Buttons. - [Transfer a Button](/docs/buttons/transfer-a-button): copy a Button to the OneClick of another Pipedrive company. - [Migrate to API v2](/docs/buttons/migrate-to-api-v2): move a Button to Pipedrive API v2. --- # Manage Buttons Source: https://help.theoneclick.io/docs/buttons/manage-buttons.md This page is for admins who make Buttons. You manage the Buttons on the **Buttons** tab of the OneClick Settings. To open the Settings, click **Settings** at the bottom of the OneClick Panel. The **Panel** tab and the **Floating window** tab have different lists. Select the tab of the Buttons that you want to manage. Move the mouse pointer over a Button in the list. The Button then shows its controls: - The API version: **V2** or **V1**. See [Migrate to API v2](/docs/buttons/migrate-to-api-v2). An Interface button has no API version. - The trash icon deletes the Button. - The copy icon duplicates the Button. - **Edit** opens the Button editor. ![A Button in the Buttons list with the API version V2, the trash icon, the copy icon and Edit](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/manage-buttons/button-actions.png) ## Sort the Buttons The users see the Buttons in the order of the list. 1. Drag a Button to a new position in the list. 2. Release the mouse button. OneClick saves the new order immediately. ## Put Buttons in groups A group shows its Buttons under a group header. The user opens and closes the group with a click on the header. See [Button groups](/docs/use-buttons#button-groups). To make a group, do one of these steps: - Click **Add Group**. An empty group shows in the list. - Drag a Button to the area **Drag here to create a new group**. OneClick makes a group with this Button in it. To manage a group: - To rename a group, click the group name and type a new name. A group name has a maximum of 40 characters. If you remove all of the name, the name becomes **Group**. - To move Buttons into the group or out of it, drag them. The Buttons with no group are in the area **Ungrouped buttons here**. - To sort the groups, drag a group by its handle. - To move all Buttons out of a group, click the clear icon in the group header. The group stays. - To delete a group, click the remove icon in the group header. Its Buttons move to the Buttons with no group. OneClick does not delete the Buttons. ## Duplicate a Button A duplicate is a good start for a new Button that is almost the same as an old one. 1. Move the mouse pointer over the Button in the list. 2. Click the copy icon. OneClick makes a copy with the name of the original and the text "(copy)" at the end. The copy has all the settings of the original and is in the same group. You cannot duplicate a Button that has confidential headers from other users. The copy icon is then not available, and OneClick shows **You cannot copy this button, as it contains confidential headers added by users other than you**. ## Delete a Button :::caution A deleted Button goes away for all Pipedrive users in your company. You cannot restore it. ::: 1. Move the mouse pointer over the Button in the list. 2. Click the trash icon. The row shows **Cancel** and **Yes, delete**. 3. Click **Yes, delete**. To keep the Button, click **Cancel**. --- # Transfer a Button Source: https://help.theoneclick.io/docs/buttons/transfer-a-button.md This page is for admins who make Buttons. A transfer copies a Button from the OneClick of one Pipedrive company to the OneClick of another Pipedrive company. For example, you make and test a Button in a sandbox company, and then you transfer it to your production company. - The **source company** has the Button. - The **target company** gets the copy. The Button in the source company does not change. A transfer works for all Button types. ## Make a transfer-enabled API key in the target company Do these steps in the OneClick of the target company. 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Settings** tab. 3. Click **API Keys** in the menu at the left. 4. Click **Create New API Key**. 5. Type a name for the key in **Label**. 6. Turn on **Allow button transfers from other organizations**. OneClick shows a warning: the source company sees the label of this key in its transfer history. 7. Click **Create**. The list shows the key with **(Transfers allowed)** after its label. 8. Click the copy icon at the right of the key. OneClick copies the key to the clipboard. Keep the key secret. Each person who has the key can transfer Buttons to your company. To stop this, click **Delete** at the right of the key. ## Transfer the Button from the source company Do these steps in the OneClick of the source company. 1. Open the Settings and click **Edit** on the Button. See [Manage Buttons](/docs/buttons/manage-buttons). 2. Click **Transfer** in the menu at the left. A new Button has no **Transfer** item. Save the Button first. 3. Paste the key in **Target Organization API Key**. 4. Click **Transfer Button**. OneClick shows **Button successfully transferred to** and the name of the target company. ![The Transfer section of the Button editor. Target Organization API Key has a key, and Transfer Button is available.](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/transfer-a-button/transfer-api-key.png) You cannot undo a transfer. To remove the copy, delete it in the target company. **Transfer History** shows each transfer of the Button: the target company, the label of the API key, the person who transferred it and the date. ## Examine the copy in the target company The copy is in the Buttons list of the target company, on the same tab as the original: **Panel** or **Floating window**. It has the name of the original with "(transferred)" at the end. If a Button with this name is already in the list, OneClick adds a number, for example "(transferred 1)". The copy is not in a group. The **Button** section of the copy shows **Transfer Origin**: the source company, the API key, the person who transferred the Button and the date. Some settings belong to the source company. OneClick does not copy them. Before you use the copy, do these checks: - **Headers.** OneClick does not copy the header values. Each header has the value "Set your own value", and no header is confidential. Type the correct values and make the headers confidential again. - **Limit visibility.** OneClick removes the pipelines, the stages, the users and the groups. The scopes stay. Set the limits again. See [Limit visibility](/docs/buttons/limit-visibility). - **Pipedrive custom fields.** A custom field of the source company is not in the target company. Select the correct field in the target company again. - **Filter fields and user fields.** OneClick clears the allowed filters and the default values of filter fields, and the default values of user fields. Set them again. - **Signed link.** OneClick does not copy the secret of a Signed link. Make a new secret. - **Interface variables.** OneClick does not copy the values of confidential Interface variables. Type them again. ## Errors | Message | Cause | | ------------------------------------------ | ---------------------------------------------------------------------------------- | | **Invalid API key** | No OneClick API key has this value. Copy the key again. | | **API key does not allow button transfers** | The key does not have **Allow button transfers from other organizations**. Make a new key. | | **Cannot transfer to same organization** | The key belongs to the source company. Use a key of the target company. | | **Too many transfer!** | One company can do a maximum of 30 transfers to the same target company in 24 hours. | --- # Migrate to API v2 Source: https://help.theoneclick.io/docs/buttons/migrate-to-api-v2.md This page is for admins who make Buttons. OneClick reads the data of a Pipedrive record through the Pipedrive API. A Workflow button and a Link button use [Pipedrive API v2](https://pipedrive.readme.io/docs/pipedrive-api-v2) or API v1. API v2 is faster and more reliable than API v1. Pipedrive recommends that applications move to API v2. - A new Button uses API v2. - An Interface button has no API version. - The Buttons list shows the API version of each Button: **V2** or **V1**. See [Manage Buttons](/docs/buttons/manage-buttons). The field data of API v2 is partially different from API v1. Some fields have a different key, and some fields are not in API v2. Thus a migrated Workflow button can send a different payload. Migrate each Button one at a time, and test it before the users see it. ## 1. Make a test copy of the Button 1. Duplicate the Button. See [Duplicate a Button](/docs/buttons/manage-buttons#duplicate-a-button). 2. Click **Edit** on the copy. 3. Turn on the switch of **Limit Visibility** and click **Limit Visibility**. 4. In **Show for users**, select only yourself, or only the users who test the Button. See [Limit visibility](/docs/buttons/limit-visibility). 5. Click **Save**. The other users do not see the copy. ## 2. Switch the copy to API v2 1. Click **Button** in the menu at the left. 2. Turn on **Use Pipedrive API v2**. ![The switch Use Pipedrive API v2 in the Button section of the Button editor](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/migrate-to-api-v2/api-v2-toggle.png) ## 3. Select the fields again OneClick looks for each field of the Button in API v2. A field that is not in API v2 gets the text **(Removed or unavailable for this API version)** after its name. The menu item of its section shows a red error icon. For a Workflow button: 1. Click **Custom Fields** in the menu at the left. 2. Find the fields with the error icon. 3. Click a field and select the correct API v2 field in the field selection. 4. Do steps 2 and 3 again for all fields with an error. 5. If the Button uses advanced validation, examine the rules. Select the fields of the rules again. For a Link button: 1. Click **Dynamic URL** in the menu at the left. 2. Find the URL parts with the error icon. 3. Delete each part with an error. Add a dynamic field at the same position and select the correct API v2 field. When no section shows an error icon, click **Save**. ## 4. Test the copy - **Link button.** Press the copy in Pipedrive. Make sure that the URL is correct. - **Workflow button.** Press the original Button and then the copy on the same record. Compare the two payloads that your process receives. Change your process for the differences. The request of a Workflow button has the header `X-oc-pipedrive-api-version` with the value `v1` or `v2`. Your process can use it to read both payload types. If you use Make, Zapier or another automation tool, you can also duplicate your workflow. Connect the copy of the Button to the copy of the workflow. The original Button and workflow then work while you test. ## 5. Publish the migrated Button 1. Open the copy and click **Limit Visibility**. 2. Remove the users that you selected in step 1, or turn off the switch of **Limit Visibility**. 3. Click **Save**. All users now see the migrated Button. 4. Delete the original Button, or limit it so that the users do not see it. See [Delete a Button](/docs/buttons/manage-buttons#delete-a-button). --- # Workflow button Source: https://help.theoneclick.io/docs/buttons/workflow-button.md This page is for admins who make Buttons. A Workflow button sends the data of a Pipedrive record to a URL. The URL is usually a Make or Zapier webhook, or an endpoint on your own server. Your process then uses the data. For the view of the user, see [Press a Button](/docs/use-buttons/press-a-button). For guides with Zapier, Make and Node.js, see [Using OneClick with](/docs/using-oneclick-with). ## How a Workflow button sends data 1. A Pipedrive user clicks the Workflow button in the Panel of a deal, a person or an organization. 2. OneClick shows the views that you set, for example fields or a confirmation. 3. OneClick sends an HTTP `POST` request to the **Button URL**. The body is JSON with the data of the record. 4. Your process gets the request and starts. ## Make a Workflow button 1. Open a deal, a person or an organization in Pipedrive. 2. Click **Settings** at the bottom of the OneClick Panel. The Settings open on the **Buttons** tab. 3. Click the **Panel** tab or the **Floating window** tab. 4. Click **Create new**. 5. Click **Workflow button**. The Button editor opens on the **Button** section. 6. Type the URL of your webhook or endpoint in **Button URL**. 7. Type the **Button text**. The user sees this text on the Button. 8. Click **Save**. ## The Button section ![The Button section of the Workflow button Send to Make, with Use Pipedrive API v2, Button URL, Button text, Description, Button accent color and Wait for response](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/workflow-button/button-section.png) The **Button** section has these settings: - **Use Pipedrive API v2** sets the Pipedrive API version that the Button uses. See [Migrate to API v2](/docs/buttons/migrate-to-api-v2). - **Button URL** is the URL that gets the data. It is required. It must be a valid URL with a maximum of 1500 characters. - **Button text** is the label of the Button in the Panel or in the Floating window. - **Description (optional)** is a text about the Button. The user sees it after a click on the info icon (**i**) at the right of the Button. The maximum is 500 characters. - **Button accent color** is the color of the Button. The field at the right of the color shows the hex code. Click **Reset** to use the default color. - **Wait for response** makes OneClick wait up to 30 seconds for the answer of your process. The Button then shows the result to the user. See [The answer of your process](#the-answer-of-your-process). ### HTML in the description The description can contain the HTML tags ``, ``, ``, `
` and `
`. A link can have the attributes `href`, `target`, `rel` and `style`. The `style` of a link can set only `color` and `font-size`. OneClick removes all other tags and attributes. When the description contains HTML, the editor shows a preview. ## Test the Button 1. Click **Save** and close the Settings. 2. Open a deal, a person or an organization in Pipedrive. 3. Click the Button in the OneClick Panel. 4. Make sure that your process got the request. For example, look at the history of the Make scenario or the Zap. ## The data that the Button sends OneClick sends the request with the method `POST` and the content type `application/json`. A press in the Panel of a deal sends a body such as this: ```json { "identifier": "25f51481-2e6a-4253-8714-cbd0088f7bae", "resource": "deal", "view": "details", "userId": "18136649", "companyId": "89342902", "selectedIds": "6115", "fields": null } ``` | Key | Value | | ------------- | -------------------------------------------------------------------------------------- | | `identifier` | The ID of the Button. The **Details** of the Button show the same ID. | | `resource` | The type of the record: `deal`, `person` or `organization`. | | `view` | The Pipedrive view in which the user pressed the Button. | | `userId` | The Pipedrive ID of the user who pressed the Button. | | `companyId` | The Pipedrive ID of the company of the user. | | `selectedIds` | The ID of the record. | | `fields` | The values of the fields. The value is `null` when the press has no field values. When **Custom Fields** is off, the key can be missing. | The body also contains the other parameters that Pipedrive gives to the OneClick Panel. Other settings add more keys: - **Custom Fields** adds the field values in `fields`. See [Custom fields](/docs/buttons/workflow-button/sections/custom-fields#the-data-that-the-button-sends). - **Products** adds the deal products in `products`. See [Products](/docs/buttons/workflow-button/sections/products). - **Messaging** and **Interface** add `event_id`, the ID of the press. A Floating window Button has no record. Its body has no `resource`, `selectedIds` and `view`, and it has the key `surface`. See [A Floating window Button gets no Pipedrive record](/docs/buttons#a-floating-window-button-gets-no-pipedrive-record). ### The headers of the request Each request has these HTTP headers: | Header | Value | | ---------------------------- | ------------------------------------------------------------------------ | | `Content-Type` | `application/json` | | `X-oc-user-id` | The Pipedrive ID of the user who pressed the Button. | | `X-oc-company-id` | The Pipedrive ID of the company of the user. | | `X-oc-pipedrive-api-version` | The Pipedrive API version of the Button: `v1` or `v2`. | | `X-oc-event-id` | The ID of the press. Only a Button with **Messaging** or **Interface** sends it. | To send your own headers, for example an API token, use the **Headers** section. See [Headers](/docs/buttons/workflow-button/sections/headers). ## The answer of your process When **Wait for response** is off, OneClick sends the request and does not wait for the answer. When **Wait for response** is on, OneClick waits up to 30 seconds: - A status code from 200 to 299 is a success. The Button shows a green check mark for 2 seconds. - Another status code, an error or no answer in 30 seconds is a failure. The Button shows a red exclamation mark. A click on it shows the message. OneClick takes the message from the answer. The answer can be a text, or JSON with the key `message`, the key `error` or the key `error.message`. ## The Details of the Button After you save the Button, the **Button** section shows the **Details**: - **Identifier**: the ID of the Button. The request sends it in `identifier`. - **Created by** and **Created at**: the user who made the Button, and when. - **Modified by** and **Modified at**: the user who changed the Button last, and when. ## The sections of the editor The editor of a Workflow button has these sections: | Section | What you set | | -------------------- | ------------------------------------------------------------------------------------ | | **Button** | The URL, the text, the description, the color and the API version. | | **Button Behaviour** | A cooldown after a press and a confirmation view. See [Button behavior](/docs/buttons/workflow-button/sections/button-behavior). | | **Headers** | Your own HTTP headers for the request. See [Headers](/docs/buttons/workflow-button/sections/headers). | | **Limit Visibility** | The records, pipelines, stages, users and groups that see the Button. See [Limit visibility](/docs/buttons/limit-visibility). | | **Custom Fields** | The fields that the user sees and fills in before OneClick sends the data. See [Custom fields](/docs/buttons/workflow-button/sections/custom-fields) and [Advanced validation](/docs/buttons/workflow-button/sections/advanced-validation). | | **Products** | The deal products in the request. See [Products](/docs/buttons/workflow-button/sections/products). | | **Messaging** | The messages that your process sends back to the user. See [Messaging](/docs/buttons/workflow-button/sections/messaging). | | **Interface** | The size of a window that the Button opens. The section shows only when your company can use it. | | **Transfer** | A copy of the Button for the OneClick of another Pipedrive company. See [Transfer a Button](/docs/buttons/transfer-a-button). The section shows only for a saved Button. | A section with a switch in the menu is on only when the switch is on. A Floating window Button has no **Products** section and no **Interface** section. --- # Button behavior Source: https://help.theoneclick.io/docs/buttons/workflow-button/sections/button-behavior.md This page is for admins who make Buttons. The **Button Behaviour** section of a Workflow button has two settings: a cooldown and a confirmation view. They prevent presses that the user did not want and presses that start your process again too soon. ## Turn on the section 1. Open the Button in the Button editor. 2. Turn on the switch at the right of **Button Behaviour** in the menu. 3. Click **Button Behaviour**. The section opens. 4. Set a cooldown, a confirmation view or both. 5. Click **Save**. ![The Button Behaviour section of the Button Create invoice with a cooldown of 60 seconds and the confirmation view on](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/workflow-button/sections/button-behavior/button-behaviour-section.png) If the section is on and has no cooldown and no confirmation view, OneClick shows **Fill in the information in at least one field**. ## Cooldown **Cooldown in seconds** blocks the Button for the time that you set. The user cannot press the Button again in that time. The Button shows a circle that fills up. When the circle is full, the user can press the Button again. - The value must be less than 10000 seconds. An empty field or 0 sets no cooldown. - The cooldown starts when OneClick sends the data. A press that stops before that, for example on an empty required field, does not start the cooldown. - The cooldown applies to one user, one Button and one record. Another user can press the Button on the same deal. The same user can press the Button on another deal. - The OneClick server keeps the cooldown. A new browser tab, another browser or a cleared browser cache does not stop it. - If you change the cooldown, the change applies from the next press. ## Confirmation view The confirmation view asks the user to confirm the press before OneClick sends the data. It shows after the fields of the Button. 1. Turn on **Enable confirmation view**. 2. Type a **Header text**, a **Description text**, a **Confirm label** and a **Decline label**. Fill in at least one of them. 3. Select a **Confirm color** and a **Decline color**: **default**, **positive** or **negative**. 4. Look at the **Preview** below the fields. It shows the view that the user sees. If you leave a text empty, the user sees the default text: | Field | Default text | | -------------------- | -------------------------------------------------- | | **Header text** | **Confirm** | | **Description text** | **Are you sure you want to trigger this button?** | | **Confirm label** | **Yes** | | **Decline label** | **Cancel** | For the view of the user, see [Press a Button](/docs/use-buttons/press-a-button#steps-before-oneclick-sends-the-data). --- # Headers Source: https://help.theoneclick.io/docs/buttons/workflow-button/sections/headers.md This page is for admins who make Buttons. The **Headers** section adds your own HTTP headers to the request of a Workflow button. Use a header to send an API token, so that only OneClick can start your process. A header can also send other fixed data. OneClick always sends some headers of its own. See [The headers of the request](/docs/buttons/workflow-button#the-headers-of-the-request). ## Add a header 1. Open the Button in the Button editor. 2. Turn on the switch at the right of **Headers** in the menu. 3. Click **Headers**. The section opens with an empty header. 4. Type the name of the header in **Key**. 5. Type the value of the header in **Value**. The field hides the value. Click the eye icon to show it. 6. To add one more header, click **Add new**. 7. Click **Save**. To remove a header, click the bin icon at the right of the header. ![The Headers section of the Button Create invoice with the headers api-token and x-your-data, their hidden values and the Confidential switches](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/workflow-button/sections/headers/headers-section.png) With the headers `api-token` and `x-your-data`, the request gets these headers: ``` api-token: 123456 x-your-data: Hello world ``` ## Rules for the key and the value - The key can contain letters, numbers, hyphens (`-`) and underscores (`_`). Do not use underscores: some servers remove headers with underscores in the name. - The key can have a maximum of 190 characters. The value can have a maximum of 1024 characters. - Two headers cannot have the same key. OneClick does not look at upper case and lower case. - Some keys are reserved, for example `Content-Type`, `Host`, `User-Agent`, `X-oc-user-id`, `X-oc-company-id` and `X-oc-event-id`. OneClick then shows **This key is reserved**. - When the section is on, it must have at least one header. ## Confidential headers Turn on **Confidential** to hide the value of a header from other admins. Only the admin who added the header can see and change its value. A confidential header that another admin added has these effects for you: - You cannot see or change its key and its value. A warning icon at the right of the header tells who added it. - You cannot change the **Button URL**. With a new URL, you could send the value to a server that shows it. The field shows **You cannot edit the URL, as this button contains confidential headers added by users other than you**. - You cannot duplicate the Button. OneClick shows **You are not authorized to copy this button because it contains confidential headers**. - You can delete the header. Thus a header of a deleted user does not lock the Button. You cannot set a header of another admin as confidential. ## Headers on other Button types An Interface button also has a **Headers** section. See [Headers for the Interface view](/docs/buttons/interface-button#headers-for-the-interface-view). A Link button has no **Headers** section. --- # Custom fields Source: https://help.theoneclick.io/docs/buttons/workflow-button/sections/custom-fields.md This page is for admins who make Buttons. The **Custom Fields** section adds fields to a Workflow button. When the user clicks the Button, OneClick shows the fields before it sends the data. The user can examine the values and fill in the fields that the process needs. The request then contains the values in the key `fields`. For the view of the user, see [Fill in the fields](/docs/use-buttons/fill-in-fields). ![The Custom Fields section of the Button Approve discount, with the Fields tab, the Advanced validation switch, the deal field ID and its preview](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/workflow-button/sections/custom-fields/fields-tab.png) ## Add a field 1. Open the Button in the Button editor. 2. Turn on the switch at the right of **Custom Fields** in the menu. 3. Click **Custom Fields**. The section opens on the **Fields** tab. 4. Click **Add new data field**. 5. Select the type of field: **Deal**, **Organization**, **Person**, **Disposable** or **Additional element**. The field shows at the top of the list. 6. Set the field at the right of the list. The **Preview** below the settings shows the field as the user sees it. 7. Click **Save**. To open a field, click it in the list. To remove the open field, click the bin icon at the top right. When the section is on, it must have at least one field. A section with only additional elements is not valid. Then OneClick shows **Also choose one of the other field types: deal, person, organization, or disposable**. ## Pipedrive fields A **Deal**, **Organization** or **Person** field shows the value of a Pipedrive field of the record. Select the field in **Field**. The list contains the standard fields and the custom fields of Pipedrive. It also contains fields that a user cannot edit, for example **ID**. The user cannot edit a Pipedrive field in OneClick. To change the value, the user changes it in Pipedrive. You can add each Pipedrive field to a Button one time. ## Disposable fields A disposable field is a field that the user fills in. OneClick sends the value with this press only and does not save it in Pipedrive. At the next press, the field shows its default value again. | Setting | What you set | | ----------------- | ---------------------------------------------------------------------------------------------- | | **Field type** | The type of the value. See the table below. | | **Field label** | The name that the user sees. | | **Field key** | The key of the value in the request. OneClick makes the key from the label. You can change it. | | **Default value** | The value that the field shows at the start. | Two disposable fields of a Button cannot have the same key. | Field type | The value | | ----------------- | ---------------------------------------------------------------------------------------------- | | **Boolean** | A switch: on or off. | | **Date** | A date. | | **Email** | An email address. | | **Number** | A number. | | **Short text** | A text of one line. The default value can have a maximum of 255 characters. | | **Long text** | A text of more lines. The default value can have a maximum of 2000 characters. | | **Single select** | One option from a list. | | **Multi select** | One or more options from a list. | | **Users** | One Pipedrive user, or more users when **Allow multiple users** is on. | | **Filter** | One Pipedrive filter, or more filters when **Allow multiple filters** is on. | ### Options of a select field A **Single select** or **Multi select** field must have at least one option. 1. Click **Add option**. An empty option shows in **Options**. 2. Click the option and type its name. 3. To change the sequence, drag the option with the handle at the left. 4. To remove an option, click the bin icon at the right of the option. After you save the Button, each option shows its ID, for example **ID: 12**. Before the save, it shows **ID: N/A**. The request sends the ID with the name of the option. Use the ID in your process: the ID stays the same when you change the name of the option. ### Default value of a Users field For a **Users** field, you can select a Pipedrive user or **Current user**. **Current user** is the user who presses the Button. ### Settings of a Filter field - **Allowed filter types** sets the types of filters that the user can select, for example `deals`. When it is empty, the user can select all types. - **Allowed filters** sets the filters that the user can select. The list contains the shared filters of Pipedrive. When it is empty, the user can select all shared filters. - **Default value** sets the filter that the field shows at the start. ## Additional elements An additional element helps the user to read the fields. It sends no data. Select the element in **Type**: - **header**: a title. Select the **Size**: **small**, **medium** or **large**. Type the **Text**. - **label**: a text. Type the **Text**. - **divider**: a line. Select the **Color**. Click **Set Default** to use the default color. ## Required, Do not allow value and Hidden Each field has check boxes at the top right of its settings: | Check box | What it does | Fields | | ---------------------- | -------------------------------------------------------------------------------------------- | ---------------------------- | | **Required** | The field must have a value. A **Boolean** field must be on. | Pipedrive and disposable | | **Do not allow value** | The field must be empty. | Pipedrive | | **Hidden** | The user does not see the field. OneClick sends its value. | Pipedrive | A field cannot be **Required** and **Do not allow value** at the same time. When a field is not valid, OneClick does not send the data. It shows the field with an error message. A hidden field that is not valid also shows. See [Required fields and errors](/docs/use-buttons/fill-in-fields#required-fields-and-errors). ### Do not allow value Use **Do not allow value** to stop a second press. For example, your process writes an invoice number into a Pipedrive field. Set that field to **Do not allow value**. Then the user cannot make the same invoice two times. You can also set the field to read-only in Pipedrive. When you select **Do not allow value**, the field **Custom error message** shows. The user sees this message when the field has a value. The maximum is 50 characters. If you leave it empty, the user sees **Field must be empty**. ### Rules for more than one field For rules such as a number range, a date range or a text format, use [Advanced validation](/docs/buttons/workflow-button/sections/advanced-validation). When **Advanced validation** is on, the fields have no **Required** and **Do not allow value** check boxes, and OneClick ignores their old values. ## The sequence of the fields The user sees the fields in the sequence of the list. To change the sequence, drag a field in the list with the handle at its left. ## Where the fields show The fields that the user sees depend on the record: | The user presses the Button on | The user sees | | ------------------------------ | ---------------------------------------------------------- | | A deal | Deal, organization, person and disposable fields. | | An organization | Organization and disposable fields. | | A person | Person and disposable fields. | To show a Button with deal fields only on deals, use [Limit visibility](/docs/buttons/limit-visibility). A Floating window Button belongs to no record. Thus **Add new data field** shows only **Disposable** and **Additional element**. See [A Floating window Button gets no Pipedrive record](/docs/buttons#a-floating-window-button-gets-no-pipedrive-record). A Link button and an Interface button have no **Custom Fields** section. ## The data that the Button sends The key `fields` of the request contains one object for each type of field: `deal`, `organization`, `person` and `disposable`. In each object, the key of a field is its field key. A press with the deal field **ID** and a disposable field **Discount reason** sends this: ```json { "fields": { "deal": { "id": { "default_value": null, "field_key": "id", "field_label_value": 6115, "field_name": "ID", "field_type": "int", "field_value": 6115, "is_hidden": false, "is_multiple_users_allowed": false, "is_required": false, "is_not_allowed": false, "custom_error_message": "" } }, "disposable": { "discount_reason": { "default_value": null, "field_key": "discount_reason", "field_label_value": "Large order", "field_name": "Discount reason", "field_type": "varchar", "field_value": "Large order", "is_hidden": false, "is_multiple_users_allowed": false, "is_required": true, "is_not_allowed": false, "custom_error_message": "Field must be empty" } } } } ``` | Key | Value | | --------------------------- | ------------------------------------------------------------------------------------- | | `field_key` | The key of the field. For a Pipedrive field, this is the API key of the field in Pipedrive. | | `field_name` | The name of the field. | | `field_type` | The type of the field in Pipedrive or the type of the disposable field. | | `field_label_value` | The value as the user sees it. | | `field_value` | The value. For an option field, it can be the ID of the option. | | `default_value` | The default value of a disposable field. | | `is_hidden` | `true` when the field is hidden. | | `is_required` | `true` when the field is required. | | `is_not_allowed` | `true` when the field must be empty. | | `custom_error_message` | The error message for a field that must be empty. | | `is_multiple_users_allowed` | `true` when a **Users** field accepts more than one user. | For a **Single select** field, `field_value` is an object with the `name` and the `key` (the ID) of the option. For a **Multi select** field, it is a list of these objects. For a **Filter** field, it is a list with the `name`, the `key` and the `type` of each filter. A Pipedrive field key of a custom field is a long code. To find it, open **Company settings** > **Data fields** in Pipedrive. --- # Advanced validation Source: https://help.theoneclick.io/docs/buttons/workflow-button/sections/advanced-validation.md This page is for admins who make Buttons. Advanced validation examines the fields of a Workflow button with rules before OneClick sends the data. A rule can require a value, a number range, a date range or a text format. When the fields do not agree with the rules, OneClick does not send the data. The user sees your error messages and can correct the values. Advanced validation is part of the **Custom Fields** section. First add the fields. See [Custom fields](/docs/buttons/workflow-button/sections/custom-fields). ![The Validation tab of the Button Create invoice: an AND group with the rules Value greater than 1000 and Invoice reference not empty, with error messages](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/workflow-button/sections/advanced-validation/validation-tab.png) ## Turn on Advanced validation 1. Open the Button in the Button editor. 2. Click **Custom Fields** in the menu. 3. Add the fields that you want to examine on the **Fields** tab. 4. Turn on **Advanced validation** above **Add new data field**. The **Validation** tab shows a green check mark. 5. Click the **Validation** tab. 6. Add the rules. See [Add a rule](#add-a-rule). 7. Click **Save**. When **Advanced validation** is on, all rules of the Button are on the **Validation** tab. The fields have no **Required** and **Do not allow value** check boxes, and OneClick ignores their old values. **Hidden** stays on the **Fields** tab. ## Add a rule A rule examines the value of one field. The **Validation** tab starts with one group. Each group has buttons to add rules and groups. 1. Click **+ Rule** in the group. A rule shows in the group. 2. Select the field in the first list. 3. Select the type of the rule in the second list, for example **greater than**. 4. Type the value of the rule, for example `100`. Some rule types, such as **empty** or **this month**, have no value. A field can have more than one rule. To remove a rule, click the bin icon at the right of the rule. To move a rule up or down, click the arrows. ### Rule types The rule types depend on the type of the field: | Field type | Rule types | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Text, email, phone, address, person and organization | **begins with**, **contains**, **does not begin with**, **does not contain**, **does not end with**, **ends with**, **empty**, **not empty**, **regex** | | Number and monetary | **equal**, **not equal**, **less than**, **greater than**, **less than or equal**, **greater than or equal**, **between**, **not between**, **empty**, **not empty** | | Date | The number rule types, and **this day**, **this month**, **last month**, **next month**, **this quarter**, **last quarter**, **next quarter**, **this year**, **last year**, **next year**, **last 7 days**, **next 7 days**, **last 30 days**, **next 30 days** | | Single option, multiple options and users | **in**, **not in**, **empty**, **not empty** | | Boolean | **equal** | ### Regular expressions A **regex** rule examines a text with a regular expression. OneClick uses JavaScript regular expressions. For example, `^[0-9]{5,7}$` accepts 5 to 7 digits. Test the expression before you save the Button, for example on [regex101.com](https://regex101.com/) with the flavor **ECMAScript (JavaScript)**. ## Rule groups A group joins its rules with **AND** or **OR**. Select it in the list at the left of the group: - **AND**: all rules of the group must pass. - **OR**: at least one rule of the group must pass. To add a group in a group, click **+ Group**. A group in a group counts as one rule of its parent group. Thus you can make conditions such as "A and (B or C)". You can put groups in groups to a maximum of three levels below the first group. To remove a group, click the bin icon at the right of the group. When you save, each group must contain at least one rule or group. Else OneClick shows **The group must contain at least one field**. If a rule has no value, OneClick shows **Validation builder schema is invalid**. ## Error messages Write error messages that tell the user what to correct. You can write a message for a rule and for a group. - **Rule message:** click the arrow at the right of the rule value. Type the message in **Add error message**. Only the rules in the first group have a rule message. - **Group message:** type the message in **Add error message for group** in the group header. A rule message shows below its field. A group message shows above the fields. When two groups in the same parent group fail, OneClick joins their messages with "AND" or "OR", as the parent group does. If a failed rule has no message, OneClick writes a message from the rule, for example **is empty** or **does not match regex pattern** with the expression. If a group in a group fails and no group has a message, the user sees **Validation failed**. For the view of the user, see [Required fields and errors](/docs/use-buttons/fill-in-fields#required-fields-and-errors). ## Hidden fields with rules A field can be hidden and have rules. The user then sees the field only when it is not valid. If all fields are valid, the user does not see the fields, and OneClick sends the data. See [A Button with hidden fields](/docs/use-buttons/fill-in-fields#a-button-with-hidden-fields). ## Example: an invoice by email or by post A Button sends an invoice for a deal. The invoice goes by email or by post. Before OneClick sends the data, the organization must have: - A VAT number of two letters and at least six digits, for example `GB123456`. - An invoicing email address, or a full postal address with a postal code of 5 to 7 digits. This example uses the organization fields **VAT number**, **Invoicing email**, **Street**, **Postal code** and **City**. Use the fields of your Pipedrive company. ### Add the fields 1. On the **Fields** tab, add the five organization fields. 2. Select **Hidden** for each field. The user then sees a field only when it is not valid. 3. Turn on **Advanced validation**. ### Make the groups and rules Make these groups and rules on the **Validation** tab: ``` AND ├── VAT number regex ^[A-Za-z]{2}[0-9]{6,}$ └── OR ├── AND │ └── Invoicing email contains @ └── AND ├── Street not empty ├── Postal code regex ^[0-9]{5,7}$ └── City not empty ``` 1. In the first group, select **AND**. 2. Click **+ Rule**. Select **VAT number**, **regex** and type `^[A-Za-z]{2}[0-9]{6,}$`. 3. Click **+ Group**. Select **OR** in the new group. 4. In the **OR** group, click **+ Group** two times. Select **AND** in the two new groups. 5. In the first **AND** group, add the rule **Invoicing email**, **contains**, `@`. 6. In the second **AND** group, add the rules **Street**, **not empty**; **Postal code**, **regex**, `^[0-9]{5,7}$`; and **City**, **not empty**. The validation passes when the VAT number is correct, and the email or the full address is correct. ### Add the error messages 1. At the VAT number rule, click the arrow and type `VAT number is not valid` in **Add error message**. 2. In the **OR** group, type `Add an invoicing email or a postal address` in **Add error message for group**. 3. In the email group, type `Invoicing email is not valid`. 4. In the address group, type `Postal address is missing or not valid`. 5. Click **Save**. The first group needs no message. The messages of the rule and of the groups below it tell the user what is wrong. ### The result The user clicks the Button on a deal of the organization. The organization has no VAT number, no email and no postal code. OneClick does not send the data. It shows the VAT number field with **VAT number is not valid**, and the messages of the groups above the fields. When all values are correct, OneClick sends the data. The user does not see the hidden fields. --- # Products Source: https://help.theoneclick.io/docs/buttons/workflow-button/sections/products.md This page is for admins who make Buttons. The **Products** section adds the products of a deal to the request of a Workflow button. Your process then does not have to get the deal products from Pipedrive. The section can also require that the deal has a product. A Floating window Button has no **Products** section. ## Include the deal products 1. Open the Button in the Button editor. 2. Click **Products** in the menu. 3. Turn on **Include deal products**. 4. To stop a press on a deal without products, turn on **Require at least 1 product**. 5. Click **Save**. The menu then shows **On** at the right of **Products**. When the products are required, it shows **Required**. **Require at least 1 product** is available only when **Include deal products** is on. ![The Products section of the Button Create invoice with Include deal products and Require at least 1 product on, and Required in the menu](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/workflow-button/sections/products/products-section.png) ## The data that the Button sends A press on a deal adds the key `products` to the body of the request. The value is the list of the products of the deal. The list has the format that the Pipedrive API gives for the API version of the Button. See [Migrate to API v2](/docs/buttons/migrate-to-api-v2). ## Products on a person or an organization A person and an organization have no deal products. A press there sends no `products` key, and OneClick does not require a product. To show the Button only on deals, use [Limit visibility](/docs/buttons/limit-visibility). ## A deal without products When **Require at least 1 product** is on and the deal has no product, OneClick does not send the data. The user sees **Deal products are required. Please add at least 1 product and try again.** For the view of the user, see [Press a Button](/docs/use-buttons/press-a-button#steps-before-oneclick-sends-the-data). --- # Messaging Source: https://help.theoneclick.io/docs/buttons/workflow-button/sections/messaging.md This page is for admins who make Buttons. The **Messaging** section lets your process send messages back to the user who pressed a Workflow button. A message can tell the user that the process started, completed or stopped with an error. You can send more than one message for one press, for example one message for each step of the process. The user reads the messages in the Panel. See [Read messages](/docs/use-buttons/messages). ![The Messaging section of the Button Notify the team, with the switch of the section on and the messaging options](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/workflow-button/sections/messaging/messaging-section.png) ## How messaging works 1. The user presses the Button. OneClick makes an ID for the press, the event ID. 2. OneClick sends the request to the URL of the Button. The request contains the event ID in the key `event_id` and in the header `X-oc-event-id`. 3. OneClick shows the answer of your process as a message. This is the HTTP answer message. 4. Your process can send more messages to the messaging end-point of OneClick. These are custom messages. Each custom message contains the event ID. 5. OneClick shows the messages of the press to the user. You can use HTTP answer messages and custom messages together. ![The messages of the Button Notify the team in the OneClick Panel: the HTTP answer message Ok with its date and time](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/workflow-button/sections/messaging/messages-in-the-panel.png) ## Turn on messaging 1. Open the Button in the Button editor. 2. Turn on the switch at the right of **Messaging** in the menu. 3. Click **Messaging**. The section shows the options. See [Messaging options](#messaging-options). 4. Click **Save**. The options are available only when the switch of the section is on. A Link button and an Interface button have no **Messaging** section. After you turn on messaging, press the Button one time. The request then contains `event_id`, and your process or your automation tool can find the key. ## Message types Each message has one of these types: `info`, `success`, `warning` or `error`. The type sets the color of the message in the Panel. A message of the type `error` can also block the Button. See [Disable the button if there are unread error messages](#disable-the-button-if-there-are-unread-error-messages). ## HTTP answer messages When messaging is on, OneClick waits up to 10 seconds for the answer of your process. During the wait, the message of the press is **Waiting**. OneClick then replaces it with a message from the answer. A status code from 200 to 299 is a success. The table shows the message for each type of answer: | The answer | Status 200 to 299 | Other status | | -------------------------------------------- | ------------------------------------ | ------------------------------------ | | A text | The text, with the type `info`. | The text, with the type `error`. | | JSON with `message` and `message_type` | The `message`, with the `message_type`. | The `message`, with the `message_type`. | | No body | **Success**, with the type `success`. | **Error**, with the type `error`. | If the JSON answer has no `message_type`, the type is `info`, also for an error status. Thus, add `"message_type": "error"` to a JSON answer that tells about an error. If the JSON answer has no `message`, the message is empty, with the type `info`. OneClick does not show **Success** for this answer. Thus, always add `message` to a JSON answer. A JSON answer can look like this: ```json { "message_type": "success", "message": "Invoice created" } ``` If your process does not answer in 10 seconds, the message is **Request time out**, with the type `error`. A status code that is not from 200 to 299, or no answer in 10 seconds, also makes the press fail. OneClick logs the press as a failure. If **Wait for response** is also on, the Button shows a red exclamation mark with the error, for example **Request failed with status code 500**. For a press with a success status, OneClick does not use the **Wait for response** setting of the Button. Some automation tools, for example Zapier, cannot send their own HTTP answer. For these tools, turn on [Do not log HTTP responses](#do-not-log-http-responses) and send custom messages. ## Custom messages A custom message is an HTTP request that your process sends to OneClick after the press. Send the request with the method `POST` and a JSON body to the messaging end-point: ``` https://app.theoneclick.io/api/trigger-message ``` The body of a custom message: ```json { "event_id": "d3cc3758-41d3-4eba-bb80-894734f5fa20", "message": "Invoice created", "message_type": "success" } ``` | Key | Value | | -------------- | --------------------------------------------------------------------------------------------- | | `event_id` | The event ID from the request of the press. Copy the value of `event_id` exactly. | | `message` | The text of the message. The maximum is 2000 characters. | | `message_type` | `info`, `success`, `warning` or `error`. If you leave it out, the type is `info`. | | `redirect_url` | Optional. A URL that the browser of the user opens. See [Redirect from response](#redirect-from-response). | The body must contain `message`, or `redirect_url` with **Redirect from response** on. ### Rules for custom messages - Send the custom messages within 10 minutes after the press. After this time, the end-point does not accept a message for the press. - You can send a maximum of 10 custom messages for one press. - The end-point accepts a maximum of 300 requests in a minute from one IP address. Then it answers with the status `429`. ### The answer of the end-point When the end-point accepts the message, it answers with the status `200`: ```json { "error": false, "message": "Ok" } ``` When it does not accept the message, it answers with the status `400` and a reason in `message`: | `message` | Cause | | ------------------------------------------------------------------------ | --------------------------------------------------------------------- | | `Not found or the event window is expired` | The event ID is not correct, or the press was more than 10 minutes ago. | | `The maximum number of messages per event is 10` | The press has 10 custom messages. | | `The message or redirect url is required` | The body has no `message` and no `redirect_url`. | | `The message is required when the redirect from responses is not selected` | The body has only `redirect_url`, and **Redirect from response** is off. | ## Format a message with HTML A message can contain these HTML tags: ``, ``, ``, `
` and `
`. OneClick removes all other tags from the message and keeps their text. The maximum length of 2000 characters includes the tags. Give a link `` its URL in `href`. Its `style` attribute can set only `color` and `font-size`. OneClick opens a link in a message in a new browser tab. ```json { "event_id": "d3cc3758-41d3-4eba-bb80-894734f5fa20", "message": "Invoice created.
Open the invoice", "message_type": "success" } ``` ## Messaging options ### Make messages public When this option is off, only the user who pressed the Button sees the messages. When this option is on, all users see the messages. A message shows only on the record where the user pressed the Button. For example, a message of a press on deal A shows on deal A, but not on deal B. On a Floating window Button, all users of the Button see the messages. A message is unread only for the user who pressed the Button. Other users see it as read. ### Do not log HTTP responses When this option is on, the answer of your process does not make a message. Only custom messages show to the user. ### Redirect from response When this option is on, a message can open a URL in the browser of the user. Add the URL to the key `redirect_url` of a custom message or of the JSON answer of your process: ```json { "event_id": "d3cc3758-41d3-4eba-bb80-894734f5fa20", "message": "The filter is ready", "message_type": "success", "redirect_url": "https://your-company.pipedrive.com/organizations/list/filter/37" } ``` OneClick opens the URL in a new browser tab for the user who pressed the Button. The Panel opens the URL only while the Panel is open, and only within 10 minutes after the press. OneClick opens each URL one time. A message can have only `redirect_url` and no `message`. The message then shows the text **Link** with the host name of the URL, and **opened**. ### Disable the button if there are unread error messages When this option is on, the user cannot press the Button while it has an unread message of the type `error`. Use it to stop a second press that gives the same error again. The user reads the error message, and can then press the Button again. When the messages are public, this option blocks only the user who pressed the Button. ### Disable the button if there are any unread messages When this option is on, the user cannot press the Button while it has an unread message. The user must read all messages first. When the messages are public, this option blocks only the user who pressed the Button. ## Delete the messages 1. Open the Button in the Button editor. 2. Click **Messaging** in the menu. 3. Click **Clear all messages**. 4. Click **Yes, delete**. OneClick deletes all messages of the Button. You cannot undo the delete. The Panel can show the deleted messages for up to 10 minutes. **Clear all messages** shows only for a saved Button. ## Send messages from an automation tool An automation tool sends a custom message with an HTTP `POST` request, for example a webhook step. Use the value of `event_id` from the trigger of the automation. For Zapier, turn on **Do not log HTTP responses**. --- # Limit visibility Source: https://help.theoneclick.io/docs/buttons/limit-visibility.md This page is for admins who make Buttons. With **Limit Visibility**, a Button shows only where it applies. For example, a Button that sends a deal to invoicing must show only on deals, not on persons or organizations. All Button types have this section. ## Turn on Limit visibility 1. Open the Button editor. See [Make a Button](/docs/buttons#make-a-button). 2. In the menu at the left, turn on the switch of **Limit Visibility**. 3. Click **Limit Visibility**. The section shows the visibility fields. 4. Select the values in one or more fields. The next section tells what each field does. 5. Click **Save**. ![The Limit Visibility section of the Button Create invoice with the scope deal and the pipeline Pipeline](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/limit-visibility/limit-visibility-section.png) If the switch is on and all fields are empty, OneClick does not save the Button. It shows **If the visibility is selected, one of the fields must be filled**. To remove all limits, turn off the switch of **Limit Visibility** and click **Save**. ## The visibility fields An empty field does not limit the Button. | Field | The Button shows only | | -------------------------- | --------------------------------------------------------------------------- | | **Show only in scopes** | On the selected record types: deal, organization or person. | | **Show only in pipelines** | On deals in the selected pipelines. | | **Show only in stages** | On deals in the selected stages. | | **Show for users** | For the selected users, and for the users in the groups of **Show for groups**. | | **Show for groups** | For the users in the selected groups, and for the users of **Show for users**. | ### Pipelines and stages - You can select pipelines only when **Show only in scopes** contains deal. If you remove deal from the scopes, OneClick clears the pipelines and the stages. - **Show only in stages** shows only the stages of the selected pipelines. You cannot select a stage without its pipeline. - A pipeline with no selected stage shows the Button in all of its stages. For example, select the pipelines "Sales" and "Renewals", and select only the stage "Proposal" of "Sales". The Button then shows in the stage "Proposal" of "Sales" and in all stages of "Renewals". ### Users and groups **Show for users** and **Show for groups** work together. A user sees the Button if the user is in **Show for users** or is a member of a group in **Show for groups**. You make the groups on the **Groups** tab of the OneClick Settings. See [Groups](/docs/settings/groups). ## How the fields work together A user sees the Button only if all filled-in fields agree. For example, a Button with the scope deal, the pipeline "Sales" and the group "Sales team" shows only on deals in "Sales", and only for the members of "Sales team". Use **Show only in scopes** when a Workflow button sends deal fields. A Button that you press on a person or an organization does not have the data of a deal. ## Floating window Buttons A Floating window Button belongs to no record. Thus its **Limit Visibility** section has only **Show for users** and **Show for groups**. See [The Panel or the Floating window](/docs/buttons#select-the-place-the-panel-or-the-floating-window). ## What the user sees When no Button applies to the record or to the user, the Panel shows **Nothing to see here**. See [Why no Buttons show](/docs/use-buttons/no-buttons). --- # Link button Source: https://help.theoneclick.io/docs/buttons/link-button.md This page is for admins who make Buttons. A Link button opens a URL in the browser of the user. You build the URL from text and from Pipedrive fields. When a user clicks the Button, OneClick puts the current field values of the record into the URL and opens it. For example, a Link button can open a Google search for the name of the organization, or the page of the customer in your invoicing tool. For the view of the user, see [Press a Button](/docs/use-buttons/press-a-button). A Link button sends no data to a server. It only opens a URL. To send the data of a record to a process, use a [Workflow button](/docs/buttons/workflow-button). For guides with Google Forms, Xero, a business registry and Node.js, see [Using OneClick with](/docs/using-oneclick-with). ## How a Link button opens a URL 1. A Pipedrive user clicks the Link button in the Panel of a deal, a person or an organization. 2. OneClick reads the current values of the fields in the URL. 3. OneClick puts the values into the URL and opens it in a new window or in a pop-up window. OneClick reads the field values at the time of the click. The URL always contains the latest data, but the window can open after a short delay. ## Make a Link button 1. Open a deal, a person or an organization in Pipedrive. 2. Click **Settings** at the bottom of the OneClick Panel. The Settings open on the **Buttons** tab. 3. Click the **Panel** tab or the **Floating window** tab. 4. Click **Create new**. 5. Click **Link button**. The Button editor opens on the **Button** section. 6. Type the **Button text**. The user sees this text on the Button. 7. Click **Dynamic URL** in the menu and build the URL. See [Dynamic URL](#dynamic-url). 8. Click **Save**. The Button editor of a Link button has the sections **Button**, **Dynamic URL**, **Window**, **Signed link**, **Limit visibility** and **Transfer**. The **Button** section has **Use Pipedrive API v2**, **Button text**, **Description (optional)** and **Button accent color**. These settings work as in a [Workflow button](/docs/buttons/workflow-button#the-button-section). A Link button has no **Button URL**: the **Dynamic URL** section makes the URL. ## Dynamic URL ![The Dynamic URL section of the Link button Open signed report: a text element, the deal field ID, a text element and the user field email, with the field picker below](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/link-button/dynamic-url-section.png) The **Dynamic URL** section builds the URL from elements in a row. OneClick joins the elements from left to right. There are two types of element: - A text element contains fixed text, for example `https://www.google.com/search?q=`. - A field element contains a Pipedrive field, for example the name of the organization. When the user clicks the Button, OneClick puts the value of the field in place of the element. A new Link button starts with one text element that contains `https://`. Copy a sample URL from the target page first. Then replace the parts that change with field elements. For example, a Google search for the organization has these two elements: | Element | Contents | | ------- | -------------------------------------- | | Text | `https://www.google.com/search?q=` | | Field | The **Name** field of the organization | ### Type the URL without URL encoding Type the URL as plain text, without [URL encoding](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). OneClick encodes the full URL when the user clicks the Button. For example, type a space as a space: ``` https://www.google.com/search?q=test value ``` Do not type `%20` for the space. OneClick encodes the `%` again, and the URL then contains `%2520`: ``` https://www.google.com/search?q=test%2520value ``` If you paste an encoded URL, click **URL Decode** in the URL toolbox. OneClick then decodes the text of the element. ### URL toolbox ![The URL toolbox under the first text element, with Add dynamic field, Add text field, Split, URL Decode and Delete](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/link-button/url-toolbox.png) Put the pointer on an element to show the URL toolbox. The toolbox has these actions: - **Add dynamic field** adds a field element at the right of the current element. Then click a field in the field picker. See [Field picker](#field-picker). - **Add text field** adds an empty text element at the right of the current element. - **Split** divides a text element into two elements at the position of the cursor. Click in the text first. - **URL Decode** decodes the encoded characters in a text element, for example `%20` to a space. - **Delete** removes the element. When the URL has only one element, you cannot remove it. **Split** and **URL Decode** are only on text elements. Click the **+** button at the right of the row to show the actions **Add dynamic field** and **Add text field**. They add the element at the end of the URL. To change the order of the elements, drag an element by its handle (**⠿**) to a different position. ### Field picker The field picker is below the row of elements. It has a tab for each record type: **Deal**, **Organization**, **Person** and **User**. Each tab shows the fields of that type as labels. - Type in **Search by name or key** to find a field. - Put the pointer on a field to see its key and its type. - Click a field to add it to the URL. If you clicked **Add dynamic field** first, the field goes to that position. If not, the field goes to the end of the URL. Some fields contain more than one value. For these fields, a **Choose field** list opens. Click the value that the URL uses: ![The Choose field list of the organization field Industry, with the values id and label](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/link-button/choose-field.png) | Field type | Values in **Choose field** | | -------------------------- | -------------------------------------------------------------------------- | | Single option, multiple options | `id` or `label` | | Organization | `name`, `people_count`, `owner_id`, `address`, `cc_email`, `owner_name`, `value` | | Person | `name`, `email`, `phone`, `owner_id`, `value` | | User | `id`, `name`, `email`, `has_pic`, `pic_hash`, `owner_name`, `value` | The **User** tab has the fields of the Pipedrive user who clicks the Button, for example the email of that user. ### Fields and the record of the click A Link button reads its fields from the record on which the user clicks it: - On a deal, the URL can use the fields of the deal, its organization, its contact person and the user. - On an organization, the URL can use the fields of the organization and the user. - On a person, the URL can use the fields of the person and the user. - In the Floating window, the Button belongs to no record. The field picker then shows only the **User** tab. Every field in the URL must have a value. If a field is empty, or the record has no such field, OneClick does not open the URL. The Panel shows an error in place of the Button. Use [Limit visibility](/docs/buttons/limit-visibility) to show the Button only on the record types that have its fields. ## Window ![The Window section of the Link button Open signed report, with Open in a pop-up window selected, a pop-up window of 1000 by 700 pixels and Resize turned on](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/link-button/window-section.png) The **Window** section sets where the URL opens: - **Open in a new window** opens the URL in a new browser tab or window. - **Open in a pop-up window** opens the URL in a pop-up window with the size and position that you set. ### Pop-up settings The **Pop-up settings** are available only when you select **Open in a pop-up window**. All values are in pixels. - **Window width** and **Window height** set the size of the pop-up window. Use 100 pixels or more. - **Top location** and **Left location** set the position of the pop-up window from the top left corner of the screen. Under **Enable window options**, turn on the parts of the browser window that the pop-up shows: **Scrollbar**, **Resize**, **Menubar**, **Toolbar** and **Location bar**. The pop-up window has the Button text as its name. A second click on the same Button opens the URL in the same pop-up window. ### Browser limits for pop-up windows The browser decides how it opens a pop-up window. OneClick cannot change this. - Some browsers open a pop-up window in a new tab, or do not support pop-up windows. - Some browsers block pop-up windows. The user must then allow pop-up windows for Pipedrive. - Some browsers ignore some window options, for example a hidden location bar or hidden scrollbars. For the pop-up settings of your browser, see the help of [Chrome](https://support.google.com/chrome/answer/95472), [Safari](https://support.apple.com/en-us/102524), [Firefox](https://support.mozilla.org/en-US/kb/pop-blocker-settings-exceptions-troubleshooting) or [Edge](https://support.microsoft.com/en-us/microsoft-edge/block-pop-ups-in-microsoft-edge-1d8ba4f8-f385-9a0b-e944-aa47339b6bb5). For the window options, see the `windowFeatures` parameter of [`window.open()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open). ## Signed link A Link button can put a short-lived signed token in the URL. The target page can then verify that the click came from OneClick and from which Pipedrive user. See [Signed link](/docs/buttons/link-button/sections/signed-link). ## Test the Button 1. Click **Save** and close the Settings. 2. Open a deal, a person or an organization in Pipedrive. 3. Click the Link button in the OneClick Panel. The URL opens in a new window or in a pop-up window. 4. Make sure that the URL contains the correct field values. --- # Signed link Source: https://help.theoneclick.io/docs/buttons/link-button/sections/signed-link.md This page is for admins who make Buttons. The last part is also for the developers of the target page. A Link button opens a URL in the browser. The target page cannot tell from the URL alone that the click came from OneClick. The **Signed link** section solves this. On each click, OneClick makes a new signed token and adds it to the URL as a query parameter. The target page verifies the token with a secret that only OneClick and the target page know. A Link button without a Signed link opens the URL as it is. ## How a signed click works 1. A Pipedrive user clicks the Link button. 2. The browser opens an empty window. 3. OneClick checks the user and makes a token on the OneClick server. The token is signed with the secret. 4. OneClick adds the token to the URL in the query parameter, for example `?oneclick_token=`. 5. The window opens the URL. 6. The target page verifies the token and then shows its content. If OneClick cannot make the token, it closes the window and the Panel shows an error. OneClick never opens the URL without the token. If the browser blocks the window, the error tells the user to allow pop-up windows for OneClick. ## Add a Signed link 1. Open the Link button in the Button editor. 2. Click **Signed link** in the menu. The section shows **No Signed link added yet**. 3. Click **Add a Signed link**. OneClick makes a new secret and fills in the default values. 4. Change **Query parameter name** and **Token lifetime (seconds)** if necessary. 5. Copy the secret from **Signing secret** and give it to the developer of the target page. 6. Click **Save**. ## The settings ![The Signed link section of the Link button Open signed report, with Query parameter name, Token lifetime (seconds), the hidden Signing secret and the buttons Reveal, Generate a new secret and Remove the Signed link](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/link-button/sections/signed-link/signed-link-section.png) | Setting | Default | Rules | | ---------------------------- | ---------------- | --------------------------------------------------------------------------- | | **Query parameter name** | `oneclick_token` | Starts with a letter. Letters, digits, hyphens and underscores. 64 characters or less. | | **Token lifetime (seconds)** | 60 | From 15 to 300 seconds. | | **Signing secret** | A new random key | A 256-bit key in Base64URL text. Passwords are not accepted. | If the URL already has a query parameter with the same name, OneClick replaces it with the token. ### The signing secret Use the key that OneClick makes, or paste a 256-bit Base64URL key of your own. A key of 32 bytes is 43 characters long, or 44 characters with the `=` padding at the end. OneClick encrypts the secret and never sends it to the browser of a user. When you open the saved Button again, the field hides the secret: - The admin who made the secret can click **Reveal** to show it again. - For other admins, the secret stays hidden. They can still replace it or remove the Signed link. **Generate a new secret** replaces the secret at once. Tokens with the old secret then fail. Give the new secret to the target page at the same time. **Remove the Signed link** removes the setting. The Link button then opens the URL without a token. ### Copies and transfers - A copy of the Button in the same Pipedrive company keeps the secret. - A [Button transfer](/docs/buttons/transfer-a-button) to another Pipedrive company keeps the query parameter name and the token lifetime, but not the secret. The section then says that the Button carries no signing secret. Until an admin of that company generates a new secret, the Button opens the URL without a token. ## Verify the token on the target page The token is a [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) (JWT) with the algorithm `HS256`. To verify it, the target page does these steps: 1. Read the token from the query parameter. 2. Decode the Base64URL secret into its 32 bytes. Use these bytes as the HMAC key, not the text of the secret. 3. Verify the `HS256` signature with the key. Accept only the algorithm `HS256`. 4. Make sure that the time in `exp` is not in the past. 5. Use the claims, for example to find the Pipedrive user. The token has these claims: | Claim | Type | Value | | --------------- | ------- | -------------------------------------------------------------- | | `company_id` | number | The ID of the Pipedrive company. | | `user_id` | number | The ID of the Pipedrive user who clicked the Button. | | `is_user_admin` | boolean | `true` if the user is a Pipedrive admin. | | `iat` | number | The time when OneClick made the token, in seconds since 1970. | | `exp` | number | The time when the token expires, in seconds since 1970. | The token does not contain the deal, the person or the organization. The URL can contain them, but they are not signed. Do not trust them for access control. OneClick makes a new token for each click, but it does not prevent a second use of a token. If the target page must accept a token only one time, it must keep a list of the used tokens until they expire. The `is_user_admin` value is never more than five minutes old: OneClick checks the admin status with Pipedrive again when the stored status is older. For an example in Node.js, see [Verify a Signed link](/docs/using-oneclick-with/nodejs/verify-a-signed-link). --- # Interface button Source: https://help.theoneclick.io/docs/buttons/interface-button.md This page is for admins who make Buttons. An Interface button opens an Interface view. You build the Interface view in Interface Builder. An Interface view is a screen with blocks such as text, tables and forms. For the view of the user, see [Use an Interface view](/docs/use-buttons/use-an-interface-view). ## How an Interface button opens an Interface view 1. A Pipedrive user clicks the Interface button in the Panel of a deal, a person or an organization. 2. A window with the title **OneClick Interface** opens over Pipedrive. 3. The window shows the Interface view with the data of the record that the user has open. OneClick gives the Interface view the type of the record and its ID. Thus a view that you open from a deal shows the title, the value and the fields of that deal. You do not get the record data yourself. An Interface view can also show other data: the data of the user who presses the Button, and data from your own data source. Interface Builder sets these sources. An Interface button in the Floating window gives no record data to its Interface view. See [A Floating window Button gets no Pipedrive record](/docs/buttons#a-floating-window-button-gets-no-pipedrive-record). For the two places of an Interface button, see [Panel and Floating window](/docs/buttons/interface-button/interface-builder/explanation/panel-and-floating-window). ![The OneClick Interface window over Pipedrive with the Interface view Group info for an organization, with a deal scope, yearly totals and a table](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/interface-button/interface-view.png) ## Make an Interface button 1. Open a deal, a person or an organization in Pipedrive. 2. Click **Settings** at the bottom of the OneClick Panel. The Settings open on the **Buttons** tab. 3. Click the **Panel** tab or the **Floating window** tab. 4. Click **Create new**. 5. Click **Interface button**. The menu shows it with the label **BETA**. The Button editor opens. 6. Type the **Button text**. The user sees this text on the Button. 7. Click **Open interface builder**. OneClick saves the Button and opens Interface Builder. If the **Create new** menu does not show **Interface button**, the Interface button is not available for your company. ## The settings of an Interface button The editor of an Interface button has these sections: | Section | What you set | | -------------------- | ------------------------------------------------------------------------------------- | | **Button** | The link to Interface Builder, the size of the window, the text, the description and the color. | | **Headers** | The headers that OneClick adds to each request that the Interface view sends. | | **Limit Visibility** | The records, pipelines, stages, users and groups that see the Button. See [Limit visibility](/docs/buttons/limit-visibility). | | **Transfer** | A copy of the Button for the OneClick of another Pipedrive company. See [Transfer a Button](/docs/buttons/transfer-a-button). The section shows only for a saved Button. | The **Button** section has these settings: - **Open interface builder** opens the Interface view of this Button in Interface Builder. - **Interface width** is the width of the window in pixels. The default is 1100. The value must be from 320 to 2400. - **Interface height** is the height of the window in pixels. The default is 890. The value must be from 120 to 1600. - **Button text** is the label of the Button. - **Description (optional)** is a text about the Button. - **Button accent color** is the color of the Button. Click **Reset** to use the default color. The section shows the warning **The interface builder is currently in beta**. Interface Builder can have bugs and features that are not complete. ![The Button section of an Interface button with the beta warning, Open interface builder, Interface width and Interface height, Button text and Button accent color](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/interface-button/button-section.png) ### Headers for the Interface view When the **Headers** section is on, each request of the Interface view sends the headers of the Button. For example, the request that gets the data of the view, and the request of a form. Set an API token here one time, and all requests send it. To send a header with only one request, set it in Interface Builder. ## Where Interface Builder is You open Interface Builder from two places: - **From the Button editor.** Click **Open interface builder** in the **Button** section. OneClick saves the Button first. Fill in all the required fields before you click it. - **From the Panel.** An admin sees a layout icon at the right of each Interface button in the Panel. Click the icon to open the Interface view of that Button in Interface Builder. Interface Builder saves each change immediately. The Interface view that users see changes at the same time. To try a change without risk, duplicate the Button. The copy has the Interface views of the original. Change the Interface view of the copy, and test it. See [Manage Buttons](/docs/buttons/manage-buttons). To build an Interface view, see [Interface Builder](/docs/buttons/interface-button/interface-builder). --- # Using OneClick with Source: https://help.theoneclick.io/docs/using-oneclick-with.md This page is for admins who make Buttons. A Button can start a process in another service, or open a page of that service. The guides in this section show how to use OneClick with one service. Each service uses one Button type, or two. | Service | Button type | Guides | | ---------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Zapier | Workflow button | [Start a Zap](/docs/using-oneclick-with/zapier/start-a-zap), [Use field values in a Zap](/docs/using-oneclick-with/zapier/use-field-values-in-a-zap), [Send messages from a Zap](/docs/using-oneclick-with/zapier/send-messages-from-a-zap) | | Make | Workflow button | [Start a Make scenario](/docs/using-oneclick-with/make/start-a-make-scenario), [Send messages from Make](/docs/using-oneclick-with/make/send-messages-from-make), [Use field and product data in Make](/docs/using-oneclick-with/make/use-field-and-product-data-in-make) | | Node.js | Workflow button, Link button | [Receive a Workflow button press](/docs/using-oneclick-with/nodejs/receive-a-workflow-button-press), [Check the secret header](/docs/using-oneclick-with/nodejs/check-the-secret-header), [Verify a Signed link](/docs/using-oneclick-with/nodejs/verify-a-signed-link) | | Google Forms | Link button | [Fill in a Google Form](/docs/using-oneclick-with/google-forms/fill-in-a-google-form) | | Xero | Link button | [Show invoices in Xero](/docs/using-oneclick-with/xero/show-invoices-in-xero) | | Business registry | Link button | [Show an organization in the business registry](/docs/using-oneclick-with/business-registry/show-an-organization-in-the-business-registry) | For the settings of each Button type, see [Workflow button](/docs/buttons/workflow-button) and [Link button](/docs/buttons/link-button). --- # Start a Zap Source: https://help.theoneclick.io/docs/using-oneclick-with/zapier/start-a-zap.md This page is for admins who make Buttons. In this guide, you make a Zap that adds a note to a deal. A Workflow button on the deal starts the Zap. The Zap gets the request of the Button with a Webhooks by Zapier trigger. ## Make the Zap trigger 1. Make a new Zap in Zapier. 2. Select **Webhooks by Zapier** as the trigger app. 3. Select **Catch Hook** as the trigger event. 4. Copy the webhook URL of the trigger. ## Make the Workflow button 1. Open a deal in Pipedrive. 2. Make a Workflow button. Use the webhook URL as the **Button URL**. See [Make a Workflow button](/docs/buttons/workflow-button#make-a-workflow-button). 3. Close the Settings. 4. Click the Button in the OneClick Panel. OneClick sends a test request to the Zap. ## Test the trigger 1. Go back to the Zap. 2. Test the trigger. Zapier shows the requests that the webhook got. 3. Select the request of your press. 4. Continue to the action. The request contains the data of the deal. For the keys of the request, see [The data that the Button sends](/docs/buttons/workflow-button#the-data-that-the-button-sends). ## Add a note to the deal 1. Add an action to the Zap. 2. Select **Pipedrive** as the action app. 3. Select **Create Note** as the action event. 4. Select your Pipedrive account, or connect a new account. 5. Type the content of the note. 6. In the deal ID of the note, select `selectedIds` from the data of the trigger. `selectedIds` is the ID of the deal where the user pressed the Button. 7. Publish the Zap. ## Test the Button 1. Open the deal in Pipedrive. 2. Click the Button in the OneClick Panel. 3. Make sure that the deal shows the note. If the deal shows no note, look at the history of the Zap in Zapier. ## Next steps - Send the values of fields with the request. See [Use field values in a Zap](/docs/using-oneclick-with/zapier/use-field-values-in-a-zap). - Tell the user about the result of the Zap. See [Send messages from a Zap](/docs/using-oneclick-with/zapier/send-messages-from-a-zap). --- # Use field values in a Zap Source: https://help.theoneclick.io/docs/using-oneclick-with/zapier/use-field-values-in-a-zap.md This page is for admins who make Buttons. In this guide, you add fields to a Workflow button. The Zap then uses the values of the fields in the content of a deal note. Start with the Zap and the Button from [Start a Zap](/docs/using-oneclick-with/zapier/start-a-zap). The Zap gets the request with a **Catch Hook** trigger and adds a note with a Pipedrive **Create Note** action. ## Add fields to the Button 1. Open the Button in the Button editor. 2. Add the fields that the note needs. See [Add a field](/docs/buttons/workflow-button/sections/custom-fields#add-a-field). 3. Click **Save**. 4. Close the Settings. 5. Click the Button in the OneClick Panel of a deal. OneClick sends a request with the field values to the Zap. ## Get the field values in the Zap 1. Go back to the Zap. 2. Open the test of the **Catch Hook** trigger. 3. Load the new requests of the webhook. 4. Select the request of your last press. The data now contains `fields`. The values are in `fields`, in one object for each type of field: `deal`, `organization`, `person` and `disposable`. Each field has its key, for example `fields` > `deal` > `title` > `field_value`. See [The data that the Button sends](/docs/buttons/workflow-button/sections/custom-fields#the-data-that-the-button-sends). The key of a Pipedrive standard field is its name in the Pipedrive API, for example `title`. The key of a Pipedrive custom field is a long code. The key of a disposable field is the **Field key** of the field. ## Add the values to the note 1. Open the **Create Note** action. 2. Edit the content of the note. 3. Select the field values from the data of the trigger, for example the `field_value` of a field. 4. Publish the Zap. ## Test the Button 1. Open the deal in Pipedrive. 2. Click the Button in the OneClick Panel. 3. Fill in the fields, if the Button shows fields that the user fills in. 4. Make sure that the deal shows a note with the field values. --- # Send messages from a Zap Source: https://help.theoneclick.io/docs/using-oneclick-with/zapier/send-messages-from-a-zap.md This page is for admins who make Buttons. In this guide, a Zap tells the user about its steps. After each step, the Zap sends a custom message to OneClick. The user reads the messages in the OneClick Panel. For all the details of messaging, see [Messaging](/docs/buttons/workflow-button/sections/messaging). Start with a Zap that a Workflow button starts, for example the Zap from [Start a Zap](/docs/using-oneclick-with/zapier/start-a-zap). The Zap gets the request with a **Catch Hook** trigger. ## Turn on messaging for the Button Zapier cannot send its own HTTP answer to OneClick. The Zap sends custom messages instead. 1. Open the Button in the Button editor. 2. Turn on the switch at the right of **Messaging** in the menu. 3. Click **Messaging**. 4. Turn on **Do not log HTTP responses**. The answer of the webhook then does not make a message. 5. Click **Save**. 6. Close the Settings. 7. Click the Button in the OneClick Panel of a deal. The request now contains `event_id`. ## Get the event ID in the Zap 1. Go back to the Zap. 2. Open the test of the **Catch Hook** trigger. 3. Load the new requests of the webhook. 4. Select the request of your last press. The data now contains `event_id`. OneClick uses the event ID to show the message to the correct user, on the correct Button and record. ## Add a custom message Add a message after each step of the Zap that the user must know about. 1. Add an action after the step. 2. Select **Webhooks by Zapier** as the action app. 3. Select **POST** as the action event. 4. Type the URL of the messaging end-point in the URL of the action. The [Messaging](/docs/buttons/workflow-button/sections/messaging#custom-messages) page gives the URL. 5. Set the payload type to `json`. 6. Add the key `message` with the text of the message. 7. Add the key `message_type` with the type of the message, for example `success`. 8. Add the key `event_id`. Select `event_id` from the data of the trigger as its value. 9. Publish the Zap. ![The data of a Webhooks by Zapier POST action with the keys message, message_type and event_id](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/zapier/send-messages-from-a-zap/third-party-webhook-data.png) The type of a message is `info`, `success`, `warning` or `error`. For the keys and the rules of a custom message, see [Custom messages](/docs/buttons/workflow-button/sections/messaging#custom-messages). ## Test the Button 1. Open a deal in Pipedrive. 2. Click the Button in the OneClick Panel. 3. Make sure that the Panel shows the messages of the Zap. See [Read messages](/docs/use-buttons/messages). ## Stop a second press after an error A Zap that stopped with an error usually stops again at the next press. You can block the Button until the user reads the error message. 1. Send the message of an error step with the `message_type` `error`. 2. Open the Button in the Button editor. 3. Click **Messaging** in the menu. 4. Turn on **Disable the button if there are unread error messages**. 5. Click **Save**. The user can press the Button again after the user reads the error message. See [Disable the button if there are unread error messages](/docs/buttons/workflow-button/sections/messaging#disable-the-button-if-there-are-unread-error-messages). To send a different message for a success and for an error, use Zapier paths. --- # Start a Make scenario Source: https://help.theoneclick.io/docs/using-oneclick-with/make/start-a-make-scenario.md This page is for admins who make Buttons. The video shows how to start a Make scenario with a Workflow button. [Watch the video on YouTube](https://www.youtube.com/watch?v=bzeUAIWnCnw) ## The Make modules The app **OneClick for Pipedrive** in Make has these modules: - **Button click** starts the scenario. The module makes a Workflow button in OneClick and connects the Button to the scenario. You set the text of the Button and the records that show the Button: deals, organizations or persons. - **Send message** sends a message back to the user who pressed the Button. See [Send messages from Make](/docs/using-oneclick-with/make/send-messages-from-make). The **Button click** module needs a OneClick API key for its connection. ## Make a OneClick API key 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Settings** tab. 3. Click **API Keys**. The **Personal API keys** list shows. 4. Click **Create New API Key**. 5. Type a **Label** for the key, for example `Make`. 6. Click **Create**. The key shows in the list. 7. Click the copy icon at the right of the key. 8. Paste the key in the connection of the **Button click** module in Make. ## The Button that the module makes The Button shows in the OneClick Panel. Its **Button URL** is the webhook of the scenario. To change the Button, for example to add fields, open it in the Button editor. See [Workflow button](/docs/buttons/workflow-button). --- # Send messages from Make Source: https://help.theoneclick.io/docs/using-oneclick-with/make/send-messages-from-make.md This page is for admins who make Buttons. The video shows how a Make scenario sends messages back to the user who pressed a Workflow button. [Watch the video on YouTube](https://www.youtube.com/watch?v=v7A1q_wdVm4) ## The Make modules The scenario uses two modules of the app **OneClick for Pipedrive**: - **Button click** starts the scenario. Turn on messaging in the module. The request of the Button then contains `event_id`, the ID of the press. See [Start a Make scenario](/docs/using-oneclick-with/make/start-a-make-scenario). - **Send message** sends a message to the user. Map `event_id` from the **Button click** module to the event ID of the message. Then type the text of the message and select its type. The type of a message is `info`, `success`, `warning` or `error`. You can add a **Send message** module after each step of the scenario. For the rules of the messages, see [Messaging](/docs/buttons/workflow-button/sections/messaging#custom-messages). --- # Use field and product data in Make Source: https://help.theoneclick.io/docs/using-oneclick-with/make/use-field-and-product-data-in-make.md This page is for admins who make Buttons. The video shows how a Make scenario uses the field values and the deal products that a Workflow button sends. [Watch the video on YouTube](https://www.youtube.com/watch?v=h3eGS1uRFcI) ## The Make modules The scenario starts with the **Button click** module of the app **OneClick for Pipedrive**. See [Start a Make scenario](/docs/using-oneclick-with/make/start-a-make-scenario). - To send the deal products, turn on the deal products in the **Button click** module, or turn on **Include deal products** in the **Products** section of the Button. The request then contains `products`. See [Products](/docs/buttons/workflow-button/sections/products). - To send field values, add fields in the **Custom Fields** section of the Button. The request then contains `fields`. See [Custom fields](/docs/buttons/workflow-button/sections/custom-fields#the-data-that-the-button-sends). The next modules of the scenario use the values from the output of the **Button click** module. --- # Receive a Workflow button press Source: https://help.theoneclick.io/docs/using-oneclick-with/nodejs/receive-a-workflow-button-press.md This page is for admins who make Buttons. A Workflow button sends the data of a Pipedrive record to a URL. In this guide, you make an endpoint on a Node.js server that gets this request. The endpoint reads the data and sends a message back to the user. You need: - Node.js 18 or later and the package `express`. - A public HTTPS URL for your server. ## Make the endpoint 1. Make a project folder. 2. In the folder, run `npm init -y`. npm makes the file `package.json`. 3. Run `npm pkg set type=module`. Node.js then reads `import` in the `.js` files. 4. Run `npm install express`. 5. Make the file `server.js` with this code: ```js import express from 'express'; const app = express(); app.use(express.json()); app.post('/oneclick', (req, res) => { const userId = req.header('X-oc-user-id'); const companyId = req.header('X-oc-company-id'); const { identifier, resource, selectedIds, fields } = req.body; console.log({ userId, companyId, identifier, resource, selectedIds, fields }); res.json({ message: 'The data is received', message_type: 'success' }); }); app.listen(3000); ``` 6. Start the server with `node server.js`. 7. Make the server available at your public HTTPS URL. ## Connect the Button 1. Make a Workflow button. See [Make a Workflow button](/docs/buttons/workflow-button#make-a-workflow-button). 2. Type the URL of the endpoint in **Button URL**, for example `https://example.com/oneclick`. 3. Turn on [Messaging](/docs/buttons/workflow-button/sections/messaging). The user then sees the message of the endpoint. 4. Click **Save**. 5. Press the Button in the Panel of a deal. The server writes the data to the log, and the user sees **The data is received**. ## Read the data The body has the ID of the Button in `identifier` and the record in `resource` and `selectedIds`. For all keys, see [The data that the Button sends](/docs/buttons/workflow-button#the-data-that-the-button-sends). Use the headers `X-oc-user-id` and `X-oc-company-id` to find the user and the company. OneClick sets these headers on its server. The same values in the body come from the browser of the user, so do not use them for access control. A person who calls your endpoint directly can also send these headers. Thus, use them only after you check the secret header. See [Check the secret header](/docs/using-oneclick-with/nodejs/check-the-secret-header). For all headers, see [The headers of the request](/docs/buttons/workflow-button#the-headers-of-the-request). ## Answer in time - With **Messaging**, send the answer in 10 seconds. After 10 seconds, the user sees **Request time out**. - With **Wait for response**, send the answer in 30 seconds. - Send a status code from 200 to 299 for a success. OneClick sends each press one time only. It does not send the request again after an error. If the work takes more time, answer at once and send a message later. See [Custom messages](/docs/buttons/workflow-button/sections/messaging#custom-messages). ## Accept only requests from OneClick The request has no signature. To make sure that the request comes from your Button, send a secret header and check it. See [Check the secret header](/docs/using-oneclick-with/nodejs/check-the-secret-header). --- # Check the secret header Source: https://help.theoneclick.io/docs/using-oneclick-with/nodejs/check-the-secret-header.md This page is for admins who make Buttons. The request of a Workflow button has no signature. Any person who knows the URL of your endpoint can send a request to it. In this guide, you add a secret header to the Button. The endpoint then rejects each request without the header. Start with the endpoint from [Receive a Workflow button press](/docs/using-oneclick-with/nodejs/receive-a-workflow-button-press). ## Make a secret 1. Make a long random value, for example with this command: ```sh node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))" ``` 2. Keep the value in an environment variable on your server, for example `ONECLICK_SECRET`. Do not put it in the code. ## Add the header to the Button 1. Open the Button in the Button editor. 2. Turn on the switch at the right of **Headers** in the menu. 3. Click **Headers**. 4. Type `x-api-token` in **Key**. 5. Type the secret in **Value**. 6. Turn on **Confidential**. Other admins then cannot see the secret. 7. Click **Save**. With a confidential header of another admin, an admin cannot change the **Button URL** or duplicate the Button. See [Confidential headers](/docs/buttons/workflow-button/sections/headers#confidential-headers). For the rules of the key and the value, see [Headers](/docs/buttons/workflow-button/sections/headers). ## Check the header on the endpoint Check the header before the endpoint does other work: ```js import { timingSafeEqual } from 'node:crypto'; function hasSecret(req) { const expected = Buffer.from(process.env.ONECLICK_SECRET ?? ''); const actual = Buffer.from(req.header('x-api-token') ?? ''); return expected.length > 0 && actual.length === expected.length && timingSafeEqual(actual, expected); } app.post('/oneclick', (req, res) => { if (!hasSecret(req)) { return res.status(401).end(); } res.json({ message: 'The data is received', message_type: 'success' }); }); ``` `timingSafeEqual` compares the values in a constant time. Thus the time of the answer does not tell a part of the secret. ## Change the secret 1. Make a new secret. 2. Set the new secret in the environment variable. 3. Restart the server. 4. Type the new secret in **Value** in the **Headers** section of the Button. 5. Click **Save**. Between step 3 and step 5, the endpoint rejects the presses of the Button. --- # Verify a Signed link Source: https://help.theoneclick.io/docs/using-oneclick-with/nodejs/verify-a-signed-link.md This page is for admins who make Buttons. A Link button with a [Signed link](/docs/buttons/link-button/sections/signed-link) adds a token to the URL. The token tells the target page which Pipedrive user clicked the Button. In this guide, you verify the token on a Node.js server. You need: - A Link button with a Signed link. - The signing secret of the Button. - Node.js 18 or later on your server. ## Verify the token with the crypto module This function uses only the built-in `crypto` module. It returns the claims of a valid token, or `null`. The code uses `import` and `export`, so set `"type": "module"` in `package.json` or use a `.mjs` file. ```js import { createHmac, timingSafeEqual } from 'node:crypto'; export function verifyOneClickToken(token, secret) { const [header, payload, signature] = token.split('.'); if (!header || !payload || !signature) return null; const { alg } = JSON.parse(Buffer.from(header, 'base64url').toString()); if (alg !== 'HS256') return null; const key = Buffer.from(secret, 'base64url'); const expected = createHmac('sha256', key).update(`${header}.${payload}`).digest(); const actual = Buffer.from(signature, 'base64url'); if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) return null; const claims = JSON.parse(Buffer.from(payload, 'base64url').toString()); if (claims.exp <= Math.floor(Date.now() / 1000)) return null; return claims; } ``` The function does the steps in [Verify the token on the target page](/docs/buttons/link-button/sections/signed-link#verify-the-token-on-the-target-page). It uses the decoded bytes of the secret as the key, not the text of the secret. ## Verify the token with a JWT library With a JWT library, give the decoded bytes of the secret as the key. For example, with `jsonwebtoken`: ```js jwt.verify(token, Buffer.from(secret, 'base64url'), { algorithms: ['HS256'] }); ``` ## Use the claims The claims tell the Pipedrive company and the Pipedrive user. For the list of the claims, see [Verify the token on the target page](/docs/buttons/link-button/sections/signed-link#verify-the-token-on-the-target-page). Do not use the other values in the URL for access control, for example the ID of the deal. The token does not sign them. --- # Fill in a Google Form Source: https://help.theoneclick.io/docs/using-oneclick-with/google-forms/fill-in-a-google-form.md This page is for admins who make Buttons. In this guide, you make a Link button that opens a Google Form. The form already contains the name of the organization, the value and the expected close date of the deal. The user only checks the answers and sends the form. You need a Google Form with three questions: a short answer for the customer name, a short answer for the deal value and a date for the expected close date. ## Get a pre-filled link of the form Google Forms can make a link that fills in the answers. The link has a parameter for each question. 1. Open the form in Google Forms. 2. Click the menu with three dots and click **Get pre-filled link**. 3. Type a sample answer for each question. Use a single word with no spaces, for example `Test`. 4. Click **Get link**. 5. Click **Copy link**. The link looks like this: ``` https://docs.google.com/forms/d/e/
/viewform?usp=pp_url&entry.1980661752=Test&entry.1793490643=2026-11-30&entry.1784899242=100 ``` Each `entry.=` parameter is one question. The text after `=` is your sample answer. In the next steps, you replace each sample answer with a field of the deal. ## Make the Link button 1. Open a deal in Pipedrive. 2. Make a Link button and type the **Button text**, for example `Fill in the deal form`. See [Make a Link button](/docs/buttons/link-button#make-a-link-button). 3. Click **Dynamic URL** in the menu. 4. Paste the link into the first text element. If the link contains `%` codes, click **URL Decode** in the URL toolbox. See [Type the URL without URL encoding](/docs/buttons/link-button#type-the-url-without-url-encoding). Do these steps for each `entry.=` parameter, from left to right: 1. Click in the text immediately after `=`. 2. Click **Split** in the URL toolbox. The text divides into two elements. 3. Delete the sample answer at the start of the right element. 4. Put the pointer on the left element and click **Add dynamic field**. A field element shows at the right of it. 5. On the **Deal** tab of the field picker, click the field for this question. The field goes into the field element. Use these fields of the **Deal** tab: | Question | Field | | -------------------- | ----------------------- | | Customer name | **Organization name** | | Deal value | **Value** | | Expected close date | **Expected close date** | ![The end of the Dynamic URL of the Link button Fill in the deal form: the deal fields Organization Name, Expected close date and Value between entry texts](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/google-forms/fill-in-a-google-form/dynamic-url.png) For the URL toolbox and the field picker, see [URL toolbox](/docs/buttons/link-button#url-toolbox) and [Field picker](/docs/buttons/link-button#field-picker). ## Show the Button only on deals The URL uses the fields of a deal. On a person or an organization, the URL has no value for these fields. 1. Turn on the switch of **Limit Visibility** and click **Limit Visibility**. 2. In **Show only in scopes**, select deal. 3. Click **Save**. ![The Limit Visibility section of the Link button Fill in the deal form with the scope deal](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/google-forms/fill-in-a-google-form/limit-visibility.png) See [Limit visibility](/docs/buttons/limit-visibility). ## Test the Button 1. Open a deal that has an organization, a value and an expected close date. 2. Click the Button in the OneClick Panel. The Google Form opens. 3. Make sure that the form shows the name of the organization, the value and the expected close date of the deal. Every field in the URL must have a value. If the deal has no organization, no value or no expected close date, OneClick does not open the form. The Panel shows an error in place of the Button. See [Fields and the record of the click](/docs/buttons/link-button#fields-and-the-record-of-the-click). The pre-filled link gives a date answer in the format `YYYY-MM-DD`, for example `2026-11-30`. The **Expected close date** field has the same format. Use a date field with this format for a date question. --- # Show invoices in Xero Source: https://help.theoneclick.io/docs/using-oneclick-with/xero/show-invoices-in-xero.md This page is for admins who make Buttons. In this guide, you make a Link button that opens the invoice activity of a customer in [Xero](https://www.xero.com/). The URL uses the Xero ID of the customer. You need an organization field that contains the Xero contact ID of the customer, for example a custom field **Xero ID**. An integration fills in this field, for example a Make scenario or a Zap that makes the customer in Xero. For Xero in these tools, see the help of [Make](https://www.make.com/en/help/app/xero) and [Zapier](https://help.zapier.com/hc/en-us/articles/38844152391821-How-to-get-started-with-Xero-on-Zapier). ## Get a sample URL 1. Open Xero. 2. Open the contacts and select a customer. Xero shows the activity of the customer. 3. Copy the URL from the address bar of the browser. The URL is long. Keep the part to `/activity/` and delete the rest: ``` https://go.xero.com/app/!wz58Q/contacts/contact/d79ce333-a1a4-41fa-996e-5c09e9032f3d/activity/ ``` The part after `/app/`, here `!wz58Q`, identifies your Xero organization. Your URL has a different value. The part between `contact/` and `/activity/` is the Xero ID of the customer. The Link button puts the Xero ID of the organization in its place. ## Make the Link button 1. Open a deal or an organization in Pipedrive. 2. Make a Link button and type the **Button text**, for example `Show invoices in Xero`. See [Make a Link button](/docs/buttons/link-button#make-a-link-button). 3. Click **Dynamic URL** in the menu. 4. Paste the sample URL into the first text element. 5. Delete the Xero ID of the sample customer. Keep the slashes at the two sides of it. 6. Click in the text at the position of the deleted ID. 7. Click **Split** in the URL toolbox. The text divides into two elements. The right element contains `/activity/`. 8. Put the pointer on the left element and click **Add dynamic field**. A field element shows between the two text elements. 9. Click the **Organization** tab of the field picker. 10. Type the name of your Xero ID field in **Search by name or key**, and click the field. 11. Click **Save**. ![The Dynamic URL section of the Link button Show invoices in Xero: the Xero URL, the organization field Xero ID and the text /activity/](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/xero/show-invoices-in-xero/dynamic-url.png) For the URL toolbox and the field picker, see [Dynamic URL](/docs/buttons/link-button#dynamic-url). ## Show the Button only where it applies On an organization, OneClick reads the Xero ID of that organization. On a deal, it reads the Xero ID of the organization of the deal. On a person, the URL has no value. See [Fields and the record of the click](/docs/buttons/link-button#fields-and-the-record-of-the-click). 1. Turn on the switch of **Limit Visibility** and click **Limit Visibility**. 2. In **Show only in scopes**, select organization. To show the Button on deals too, also select deal. 3. Click **Save**. ![The Limit Visibility section of the Link button Show invoices in Xero with the scopes organization and deal](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/xero/show-invoices-in-xero/limit-visibility.png) See [Limit visibility](/docs/buttons/limit-visibility). ## Test the Button 1. Open an organization that has a value in the Xero ID field. 2. Click the Button in the OneClick Panel. Xero opens the activity of the customer. ![The OneClick Panel of the organization Acme Robotics Ltd with the Button Show invoices in Xero](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/xero/show-invoices-in-xero/panel-on-organization.png) If the Xero ID field is empty, OneClick does not open the URL. The Panel shows an error in place of the Button. ## Open one invoice from a deal You can use the same steps to open one invoice from a deal. You then need a deal field that contains the Xero ID of the invoice, for example a custom field **Xero invoice ID**. 1. Open the invoice in Xero and copy the URL from the address bar. 2. Make a Link button. In the **Dynamic URL**, replace the ID of the invoice with the invoice field from the **Deal** tab of the field picker. 3. In **Show only in scopes**, select deal. --- # Show an organization in the business registry Source: https://help.theoneclick.io/docs/using-oneclick-with/business-registry/show-an-organization-in-the-business-registry.md This page is for admins who make Buttons. Many countries have a public business registry. It shows the details of a company, for example its address, its company form and its business line. In this guide, you make a Link button that opens the page of the organization in the Finnish registry YTJ. The URL uses the business ID of the organization. You need an organization field that contains the business ID, for example a custom field **Y-tunnus**. ## Get a sample URL 1. Open the YTJ search at [tietopalvelu.ytj.fi](https://tietopalvelu.ytj.fi/). 2. Search for a company and open its page. 3. Copy the URL from the address bar of the browser. The URL looks like this: ``` https://tietopalvelu.ytj.fi/yritys/1863026-2 ``` The end of the URL, `1863026-2`, is the business ID. The Link button puts the business ID of the organization in its place. ## Make the Link button 1. Open a deal or an organization in Pipedrive. 2. Make a Link button and type the **Button text**, for example `Show in business registry`. See [Make a Link button](/docs/buttons/link-button#make-a-link-button). 3. Click **Dynamic URL** in the menu. 4. Paste the sample URL into the first text element. 5. Delete the business ID at the end of the text. The text is now `https://tietopalvelu.ytj.fi/yritys/`. 6. Put the pointer on the text element and click **Add dynamic field**. A field element shows at the right of it. 7. Click the **Organization** tab of the field picker. 8. Type the name of your business ID field in **Search by name or key**, and click the field. 9. Click **Save**. ![The Dynamic URL section of the Link button Show in business registry: the text element with the YTJ URL and the organization field Y-tunnus](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/business-registry/show-an-organization-in-the-business-registry/dynamic-url.png) For the URL toolbox and the field picker, see [Dynamic URL](/docs/buttons/link-button#dynamic-url). ## Show the Button only where it applies The URL uses a field of the organization. On an organization, OneClick reads the field of that organization. On a deal, it reads the field of the organization of the deal. On a person, the URL has no value. See [Fields and the record of the click](/docs/buttons/link-button#fields-and-the-record-of-the-click). 1. Turn on the switch of **Limit Visibility** and click **Limit Visibility**. 2. In **Show only in scopes**, select organization. To show the Button on deals too, also select deal. 3. Click **Save**. ![The Limit Visibility section of the Link button Show in business registry with the scopes organization and deal](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/business-registry/show-an-organization-in-the-business-registry/limit-visibility.png) See [Limit visibility](/docs/buttons/limit-visibility). ## Test the Button 1. Open an organization that has a value in the business ID field. 2. Click the Button in the OneClick Panel. The YTJ page of the organization opens. ![The OneClick Panel of the organization Acme Robotics Ltd with the Button Show in business registry](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/using-oneclick-with/business-registry/show-an-organization-in-the-business-registry/panel-on-organization.png) If the business ID field is empty, OneClick does not open the URL. The Panel shows an error in place of the Button. To use the registry of a different country, copy a sample URL from that registry. Then replace the part that identifies the company with a field element. --- # Settings Source: https://help.theoneclick.io/docs/settings.md This page is for admins. The OneClick Settings contain the Buttons, the users, the groups, the subscription and the general settings of your company. ## Who can open the Settings Only a Pipedrive global admin can open the Settings. For the global permissions, see [Global user management](https://support.pipedrive.com/en/article/global-user-management#global-permissions) in the Pipedrive help. - The Panel and the Floating window show the **Settings** button only to a global admin. - If a user who is not a global admin opens the Settings, OneClick shows **Access denied**. A global admin also needs a seat to use all tabs. Without a seat, the tabs **Buttons**, **Groups** and **Settings** are disabled. A pointer on a disabled tab shows **Access restricted: You don't have the required seat to use this feature.** The tabs **Users** and **Subscription** stay open, so the admin can give a seat to himself or herself. See [Users](/docs/settings/users). ## Open the Settings 1. Open a deal, a person or an organization in Pipedrive. 2. Click **Settings** at the bottom of the OneClick Panel. The Settings open on the **Buttons** tab. You can also click **Settings** at the bottom of the Floating window. ## The tabs | Tab | Contents | | ---------------- | ------------------------------------------------------------------------------------------ | | **Buttons** | The Buttons of the Panel and the Floating window. See [Buttons](/docs/buttons). | | **Users** | The Pipedrive users, their seats and the invitations. See [Users](/docs/settings/users). | | **Groups** | The user groups for Limit visibility. See [Groups](/docs/settings/groups). | | **Subscription** | The plan, the seats, the payment and the invoices. See [Subscription](/docs/settings/subscription). | | **Settings** | **General**, **API Keys** and **Customize**. See [General](/docs/settings/general), [API keys](/docs/settings/api-keys) and [Custom footer](/docs/settings/custom-footer). | The settings apply to all OneClick users in your Pipedrive company. --- # General Source: https://help.theoneclick.io/docs/settings/general.md This page is for admins. The **General** settings contain **Reveal on hover**. ![The General Settings of OneClick with the Reveal on hover switch](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/settings/general/general-settings.png) ## Reveal on hover Pipedrive gives each company a daily API token budget. Each Pipedrive API call uses tokens from this budget. For the details, see [Rate limiting](https://pipedrive.readme.io/docs/core-api-concepts-rate-limiting) in the Pipedrive developer documentation. When a user opens a deal, a person or an organization, Pipedrive loads the OneClick Panel. To show the Buttons, OneClick calls the Pipedrive API. These calls use tokens, also when the user does not press a Button. **Reveal on hover** stops these calls until the user needs the Buttons: - When **Reveal on hover** is on, the Panel shows **Hover here to reveal buttons**. OneClick loads the Buttons when the user moves the mouse pointer over the Panel. - When **Reveal on hover** is off, OneClick loads the Buttons each time that the Panel opens. The setting applies to all OneClick users in your Pipedrive company. ## Turn Reveal on hover on or off 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Settings** tab. The **General** settings open. 3. Click the **Reveal on hover** switch. 4. Click **Save changes**. To discard the change, click **Cancel**. --- # API keys Source: https://help.theoneclick.io/docs/settings/api-keys.md This page is for admins. A OneClick API key has two uses: - The OneClick modules in Make use the key for their connection. See [Start a Make scenario](/docs/using-oneclick-with/make/start-a-make-scenario). - A transfer-enabled API key lets another Pipedrive company transfer Buttons to your company. See [Transfer a Button](/docs/buttons/transfer-a-button). OneClick has no other API for these keys. The keys are personal. The list **Personal API keys** shows only the keys that you made. Other admins of your company do not see them. ## Make an API key 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Settings** tab. 3. Click **API Keys** in the menu at the left. The list **Personal API keys** shows. 4. Click **Create New API Key**. The dialog **Create New API Key** opens. 5. Type a name for the key in **Label**. Use a maximum of 100 characters. 6. For a transfer-enabled API key, turn on **Allow button transfers from other organizations**. Otherwise, keep it off. 7. Click **Create**. The list shows the key, its label and the date when you made it. A transfer-enabled API key has **(Transfers allowed)** after its label. You cannot turn the transfer option on or off after you make the key. Make a new key instead. When you turn on **Allow button transfers from other organizations**, OneClick shows a warning. The source company sees the label of the key in its transfer history. Do not put secret data in the label. ## Copy an API key 1. Click the copy icon at the right of the key. OneClick copies the key to the clipboard. 2. Paste the key in Make, or give it to the admin of the source company. Keep the key secret. Each person who has the key can use it until you delete it. ## Delete an API key 1. Click **Delete** at the right of the key. OneClick asks you to confirm. 2. Click **Yes, delete**. OneClick removes the key from the list. After you delete a key, a Make connection or a Button transfer with this key stops working. --- # Custom footer Source: https://help.theoneclick.io/docs/settings/custom-footer.md This page is for admins. The footer of the OneClick Panel shows the banner **Powered by Zimple**. With the custom footer, you can remove this banner or show your own logo. The custom footer is available only for a company with a subscription to a paid plan, or for a company that a Partner manages. For other companies, the menu item **Customize** is disabled and shows **Feature available for subscribed organizations only**. See [Subscription](/docs/settings/subscription). The custom footer changes only the Panel. The Floating window has no banner. ## Change the footer 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Settings** tab. 3. Click **Customize** in the menu at the left. The **Custom Footer** settings open. 4. Do one or more of these changes: - To remove the banner, turn off **Show footer banner image**. - To show your logo, click the upload area in **Footer banner image**, or drag the image file to it. - To open a web page when a user clicks the banner, type its URL in **Footer banner link URL**. 5. Click **Save changes**. To discard the changes, click **Cancel**. 6. Refresh the Pipedrive page in your browser. The Panel shows the new footer. ## The logo image - Use a JPG or PNG file. - Use a file of a maximum of 2 MB. - Use an image of 154 x 30 pixels for the best result. Your logo replaces the Zimple logo in the Panel. To remove your logo, click the cross at the right of the image, and then click **Save changes**. When **Footer banner link URL** is empty, the banner opens the Zimple web page. --- # Users Source: https://help.theoneclick.io/docs/settings/users.md This page is for admins. The **Users** tab shows all users of your Pipedrive company. On this tab, you invite users to install OneClick and give seats to the users. Pipedrive apps are user specific. Each user must install OneClick for himself or herself. The Buttons and the settings are the same for all users in your company. ## The user list 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Users** tab. The list has these columns: | Column | Contents | | --------------- | ------------------------------------------------------------------------------- | | **Name** | The name of the Pipedrive user. | | **Email** | The email address of the Pipedrive user. | | **Assign seat** | A switch that gives a seat to the user. Only a user who installed OneClick has it. | | **Status** | **Installed**, **Invitation sent**, or an **Invite** button for a user who did not install OneClick. | To find a user, type a part of the name or the email address in the search field. To filter the list, click the filter icon in the column **Assign seat** or **Status**. Then select one or more values: - **Assign seat**: **Not installed**, **Assigned**, **Not assigned**. - **Status**: **Not installed**, **Invitation sent**, **Installed**. ## Give a seat to a user A user can use the Buttons only with a seat. Instead of the Buttons, a user without a seat sees a message that tells the user to contact a Pipedrive admin. The counter above the list shows the number of assigned seats and the seat limit of your plan, for example **3 / 5 seats assigned**. 1. Find the user in the list. 2. Click the switch in the column **Assign seat**. The switch turns on, and the counter increases by one. To remove the seat, click the switch again. The seat is then free for another user. When all seats are in use, the switches of the other users are disabled. To get more seats, change your plan on the **Subscription** tab. See [Subscription](/docs/settings/subscription). With a paid plan, OneClick can give a seat to each new user automatically. See [Subscription](/docs/settings/subscription#give-seats-to-new-users-automatically). ## Invite users The invitation is an email that tells the user how to install OneClick. You can invite a user who has the status **Not installed** or **Invitation sent**. 1. Select the check box at the left of each user to invite. To select all users with the status **Not installed**, select the check box in the header of the list. 2. Click **Invite selected**. The page **Invite users** shows the recipients and a preview of the message. 3. Read the message. To change it, see [Edit the invitation message](#edit-the-invitation-message). 4. Click **Send invitation** or **Send invitations**. The status of the users changes to **Invitation sent**. To invite one user, you can also click **Invite** in the column **Status**. The sender of the email is `noreply@theoneclick.io`. The recipient cannot reply to this address. ### Edit the invitation message 1. On the page **Invite users**, click **Edit message**. The page **Edit invitation message** opens. 2. Change the text in **Subject**. 3. Change the text in **Content**. The content is HTML. You can use inline CSS. OneClick removes script tags. 4. Click **Preview** to see the message. Click **Preview** again to go back to the text. 5. Click **Save changes**. OneClick saves the message for the next invitations. 6. Click **Send test email**. OneClick sends the message to your own email address. 7. Click **Cancel** to go back to the page **Invite users**. The message can contain these variables. OneClick replaces them with your data: | Variable | Value | | ---------------- | --------------------------------------- | | `{{user.name}}` | Your name in Pipedrive. | | `{{user.email}}` | Your email address in Pipedrive. | To go back to the default message, click **Reset to default**. OneClick asks you to confirm, because this removes all your changes. Click **Reset to default** again. --- # Groups Source: https://help.theoneclick.io/docs/settings/groups.md This page is for admins. A group is a list of OneClick users. You use groups in **Show for groups** to show a Button only to some users. See [Limit visibility](/docs/buttons/limit-visibility). Only a user who installed OneClick can be a member of a group. ## The group list 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Groups** tab. The list **User Groups** shows. | Column | Contents | | ------------------- | ------------------------------------------------ | | **Name** | The name of the group. | | **Members** | The number of users in the group. | | **Used in Buttons** | The number of Buttons that use the group. | | **Actions** | The buttons **Edit** and **Delete**. | ![The Groups tab of the OneClick Settings: the list User Groups with one group, its members, its Button count and the buttons Edit and Delete](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/settings/groups/group-list.png) ## Make a group 1. Click **Create Group**. The dialog **Create Group** opens. 2. Type a name in **Group Name**. 3. Click **Create**. The list shows the group with no members. 4. Add the members. See [Change the members of a group](#change-the-members-of-a-group). ## Change the members of a group 1. Click **Edit** in the row of the group. The dialog **Edit Group** opens. 2. To add a user, find the user in the list **Available Users** at the left. Click the add button of the user. The user moves to the list **Group Members** at the right. 3. To remove a user, find the user in the list **Group Members**. Click the remove button of the user. The user moves back to **Available Users**. 4. Click **Save**. Each list has a search field. **Add All** adds all users that the search finds. **Remove All** removes all members that the search finds. You can also change the name of the group in **Group Name**. ## Delete a group 1. Click **Delete** in the row of the group. The dialog **Delete Group** opens. 2. Read the dialog. If Buttons use the group, the dialog shows their names. 3. Click **Delete**. When you delete a group, the Buttons that use it lose the group in **Show for groups**. A user who saw such a Button only through this group does not see it anymore. --- # Subscription Source: https://help.theoneclick.io/docs/settings/subscription.md This page is for admins. The **Subscription** tab shows the plan of your company, its seats, the payment method, the billing contact and the invoices. ![The Subscription tab of OneClick on the Solo plan, with the seat count and the Upgrade to teams plan button](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/settings/subscription/solo-plan.png) ## Plans and seats Each OneClick user who uses the Buttons needs a seat. You give the seats on the **Users** tab. See [Users](/docs/settings/users). | Plan | Seats | | --------------------- | -------------------------------------------------------------------------------------- | | **OneClick Solo** | One seat. This plan is free. | | **OneClick Teams** | Two or more seats. You pay a monthly price for each seat, also for the first seat. | | **OneClick Partner** | The Partner of your company gives the seats. Ask your Partner to add or remove seats. | The **Subscription** tab shows the price of a seat. VAT is added at checkout if applicable. ## Open the Subscription tab 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Subscription** tab. The **Plan** page opens. The menu at the left has the pages **Plan**, **Payment Method**, **Billing contact** and **Invoices**. ## Upgrade to the Teams plan 1. On the **Plan** page, click **Upgrade to teams plan**. The step **Plan options** opens. 2. Type the number of seats in **OneClick user seat**. The minimum is two seats, or the number of users who have a seat now. The page shows the total price per month. 3. If you have a promo code, type it in **Promo code** and click **Apply**. 4. Click **Add payment method**. The step **Payment Method** opens. 5. Type the credit card data and the billing address. OneClick accepts Visa, Mastercard and American Express. 6. Click **Add billing contact**. The step **Billing contact** opens. 7. Type the billing contact data. 8. Click **Continue**. The step **Confirm** shows a summary. 9. Click **Confirm and subscribe**. ## Change the number of seats 1. On the **Plan** page, change the number in **OneClick user seat**. 2. Click **Save**. OneClick asks you to confirm. 3. Confirm the change. When you decrease the number of seats, the current number stays until the next billing date. The **Plan** page shows the current and the new seat limit. You cannot decrease the seats below the number of users who have a seat. OneClick then shows **User seats cannot be decreased**. First remove seats from users on the **Users** tab. ## Give seats to new users automatically With the Teams plan, the **Plan** page has the switch **Assign seats to new users automatically**. The switch is off by default. When the switch is on, OneClick gives a seat to each new user who installs OneClick, while free seats are available. When the switch is off, you give each seat on the **Users** tab. ## Cancel the subscription 1. On the **Plan** page, click **Cancel subscription**. OneClick asks you to confirm. 2. Click **Confirm and cancel subscription**. OneClick removes your billing information and your payment method. Your company keeps all seats until the end of the billing period. The **Plan** page shows this date. After this date, your company goes back to the Solo plan with one seat. Until this date, you can click **Reactivate subscription** to continue the Teams plan. ## Invoices Click **Invoices** in the menu at the left. The list shows each invoice with its total and its status. --- # Connect an agent Source: https://help.theoneclick.io/docs/settings/connect-an-agent.md This page is for admins. The OneClick Settings can offer a set of tools to an AI agent on your own computer. Claude Code and Claude Desktop reach these tools through a small local program, the **relay**. You set up the relay one time on each computer. Steps 1, 2 and 4 are for Claude Code. For Claude Desktop, see [Claude Desktop](#claude-desktop). This page is about the Buttons and the User groups in the Settings. To let an agent build Interface views, see [Connecting Claude Code to Interface Builder](/docs/buttons/interface-button/interface-builder/how-to/agent/connect-claude-code). ## What the agent can do With the tools, the agent can: - list your Buttons, and read and edit a Button that has Agent access on, - create a Button, which has Agent access on from the start, - change the Button order, and create, rename and delete a Button group (its Buttons go to **Ungrouped**), - list, create and edit User groups, - read the OneClick installations, the Pipedrive fields, the pipelines and the filters of your company, to fill in a Button. The agent cannot: - delete a Button or a User group, - turn Agent access on or off (only a person does that), - read a secret, such as an Authorization header value or the key of a Signed link, - change a Button while you have its editor open. The agent changes a Button or a User group only on the tab where you see it. After each change, the list shows the changed row for a moment. For Button groups, see [Manage Buttons](/docs/buttons/manage-buttons#put-buttons-in-groups). For User groups, see [Groups](/docs/settings/groups). ## Before you start - **Chrome 155 to 162 on a computer.** The tools use WebMCP. Chrome turns WebMCP on for OneClick through a trial that ends on **30 March 2027**. In another browser, the tools do not work. - **Claude Code** or **Claude Desktop**, and **Node.js 22 or later**, because the relay runs through `npx`. - **The OneClick Settings in their own tab.** The tools do not work inside Pipedrive. In Pipedrive, open the OneClick Settings and click **Open in new tab**. The **Agent** button shows in that tab, beside your name. See [Open the Settings](/docs/settings#open-the-settings). ## 1. Install the relay 1. In the Settings tab, click **Agent**. The Agent popover opens. 2. Under **1. Install the relay**, click **Copy command**. 3. Paste the command in a terminal. 4. Run the command. Copy the command from the Agent popover, not from this page. The popover puts in the address of your tab. The command has this shape: ```text claude mcp add --scope user oneclick -- npx -y @mcp-b/webmcp-local-relay@6.0.3 --port 9400 --relay-id oneclick --widget-origin https://oneclick-nextjs-production-unxsymfqdq-lz.a.run.app ``` - `--scope user` adds the `oneclick` server to Claude Code for all your projects. - `--port 9400` and `--relay-id oneclick` keep this relay apart from other relays, for example the relay of Interface Builder. - `--widget-origin` is the address of your tab. The relay answers only that address. The relay listens only on your own computer (`127.0.0.1`). No other computer can reach it. ## 2. Add the permission rules By default, Claude Code asks you before each call to a tool. The permission rules change this for some tools. 1. In the Agent popover, under **2. Add the permission rules**, click **Copy rules**. 2. Open your Claude Code settings file: `~/.claude/settings.json`. 3. Add the entries of `allow`, `ask` and `deny` to the `permissions` section. If the lists are already there, add the entries to them. Do not replace the lists. | List | Tools | Effect | | -------- | ---------------------------------------------------------------- | ------------------------------------------------------- | | `allow` | Tools that only read | Claude Code calls them without a prompt. | | `ask` | `set_button_order`, `create_button_group`, `delete_button_group` | Claude Code asks you each time. | | `deny` | The relay's own `webmcp_call_tool` and `webmcp_open_page` | Claude Code never calls them. | | _(none)_ | Other changes, such as `update_button` | Claude Code asks, and you can choose "don't ask again". | Claude Code asks before each Button order or Button group change, also in `auto` mode. These changes move many Buttons at one time. ## 3. Turn on Agent access The agent reads and edits only the Buttons that you allow. 1. Open a Button. 2. In the **Button** section, turn on **Allow agent access (WebMCP)**. 3. Click **Save**. For a Button with Agent access off, the agent sees only its name, its place in the order and its Button group. It can still move the Button in the order. A copy of a Button and a transferred Button start with Agent access off. User groups have no Agent access: the agent can edit every User group. ## 4. Check the connection The Settings page cannot see your agent. The Agent popover never says "connected". Check from Claude Code: 1. Start Claude Code, or start it again if it was open when you installed the relay. 2. Run `/mcp`. 3. Find `oneclick` in the list. 4. Open `oneclick`. It lists tools such as `get_page` and `list_buttons`. 5. Ask the agent to call `get_page`. It tells which Settings tab is open. If `oneclick` has no tools: - Make sure that the Settings tab is open and its Agent popover does not say **The agent tools do not work in this tab.** - Make sure that the tab address is the address in `--widget-origin`. If not, run `claude mcp remove oneclick --scope user` and add the server again with the command from this tab. - Make sure that this tab offers the tools. See [One tab at a time](#one-tab-at-a-time). ## Claude Desktop Claude Desktop uses the same relay as Claude Code. It reads the relay from its config file, not from `claude mcp add`, and it does not read the Claude Code `settings.json`. ### 1. Add the relay 1. In the Settings tab, click **Agent**. 2. Click **Claude Desktop**. 3. Under **1. Add the relay**, click **Copy config**. 4. Open the config file of Claude Desktop: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` The macOS path has a space in `Application Support`. In a terminal, put the path in quotes after `~/`, for example `open -e ~/"Library/Application Support/Claude/claude_desktop_config.json"`. 5. Add the `oneclick` entry to `mcpServers`. If the file has other servers, keep them. Do not replace the file. 6. Quit Claude Desktop. 7. Start Claude Desktop again. Copy the config from the Agent popover, not from this page. The popover puts in the address of your tab. The config has this shape: ```json { "mcpServers": { "oneclick": { "command": "npx", "args": [ "-y", "@mcp-b/webmcp-local-relay@6.0.3", "--port", "9400", "--relay-id", "oneclick", "--widget-origin", "https://oneclick-nextjs-production-unxsymfqdq-lz.a.run.app" ] } } } ``` The arguments are the same as in the Claude Code command. ### 2. Set the tool permissions Claude Desktop has its own permissions for each tool of the `oneclick` connector. Set them in the tool permissions of the `oneclick` connector in Claude Desktop: | Tools | Permission | | ---------------------------------------------------------------- | ------------------------------------------------------ | | The relay's own `webmcp_call_tool` and `webmcp_open_page` | Turn them off, so that the agent cannot call them. | | `set_button_order`, `create_button_group`, `delete_button_group` | Keep a prompt. Do not allow them always. | | Tools that only read | You can allow them, so that they run without a prompt. | `webmcp_call_tool` can call every OneClick tool by name, and `webmcp_open_page` can open any address. Every OneClick action has its own tool, so the agent does not need them. ### 3. Allow the Buttons Do step [3. Turn on Agent access](#3-turn-on-agent-access). ### 4. Check the Claude Desktop connection 1. Start Claude Desktop again if it was open when you changed its config file. 2. Find the `oneclick` connector in Claude Desktop. It lists the OneClick tools, such as `get_page` and `list_buttons`. 3. Ask the agent to call `get_page`. It tells which Settings tab is open. ### When Claude Desktop does not start the relay - **Claude Desktop cannot find `npx`.** Claude Desktop starts `npx` without the `PATH` of your shell. A Node.js from `nvm` is then missing. In a terminal, run `which npx`. Put this full path in `command`. `npx` also starts `node` from the `PATH`, so add an `env` entry with the same folder. For example: ```json "oneclick": { "command": "/Users/you/.nvm/versions/node/v22.12.0/bin/npx", "args": [ "-y", "@mcp-b/webmcp-local-relay@6.0.3", "--port", "9400", "--relay-id", "oneclick", "--widget-origin", "https://oneclick-nextjs-production-unxsymfqdq-lz.a.run.app" ], "env": { "PATH": "/Users/you/.nvm/versions/node/v22.12.0/bin:/usr/bin:/bin" } } ``` - **The JSON is not valid.** Claude Desktop does not start servers from a file with a JSON error. Look for a missing comma between the `oneclick` entry and the other servers. - **The address is wrong.** The `--widget-origin` must be the address of your Settings tab. If not, copy the config again from the Agent popover in that tab. For the other causes, see [4. Check the connection](#4-check-the-connection). ## One tab at a time Only one Settings tab offers the tools at a time. The first tab takes them. The Agent popover of another tab shows **Another OneClick tab offers the agent tools** and a **Use agent here** button. Click the button to move the tools to that tab. ## When you edit at the same time If you and the agent change the same Button or User group, the second save stops. When you save, OneClick tells you that the Button changed, and you can reload it. When the agent saves, it gets the same message and reads the Button again. ## When the tools do not work The Agent popover tells you why: | The popover says | What to do | | -------------------------------------------------- | ---------------------------------------------------------------------------------------- | | They need Chrome version 155 to 162 on a computer. | Open the Settings in Chrome 155 to 162. | | The trial ended. | The tools do not work after 30 March 2027. | | This address has none. | Open the Settings at `https://oneclick-nextjs-production-unxsymfqdq-lz.a.run.app`. | | Chrome did not turn on WebMCP for this page. | Ask your IT support about Chrome policies. | | You have no seat. | Ask an admin to give you a seat in the **Users** tab. See [Users](/docs/settings/users). | ## Limits - A tool call must end in 60 seconds. - One relay serves all Claude Code sessions on your computer. - You can use Claude Code and Claude Desktop on the same computer. The first relay that starts listens on port 9400. The relay that starts next connects to the first relay. ## Related - [Connecting Claude Code to Interface Builder](/docs/buttons/interface-button/interface-builder/how-to/agent/connect-claude-code) — let an agent build Interface views --- # FAQ Source: https://help.theoneclick.io/docs/faq.md Short answers to common questions about OneClick. Each answer links to the page with the full instructions. ## Problems with the Panel and the Settings - [OneClick has disappeared from Pipedrive](/docs/faq/oneclick-has-disappeared) - [I cannot see the Settings button](/docs/faq/i-cannot-see-settings) - [Error messages in OneClick](/docs/faq/error-messages) - [You do not have a seat assigned](/docs/faq/you-do-not-have-a-seat-assigned) ## Plans - [Does a single user need a subscription?](/docs/faq/single-user-subscription) ## Link buttons - [The pop-up window opens in a new tab](/docs/faq/pop-up-window-opens-in-a-new-tab) - [Can a Link button send a user name and a password?](/docs/faq/credentials-in-a-url) ## Pipedrive API v2 - [Do I have to migrate my Buttons to API v2?](/docs/faq/migrate-buttons-to-api-v2) --- # OneClick has disappeared from Pipedrive Source: https://help.theoneclick.io/docs/faq/oneclick-has-disappeared.md The OneClick Panel no longer shows in the sidebar of a deal, a person or an organization. 1. Refresh the Pipedrive page in your browser. 2. Open a deal, a person or an organization. If the Panel shows, OneClick works again. 3. If the Panel does not show, open the [OneClick re-authorisation link](https://oauth.pipedrive.com/oauth/authorize?client_id=de8c9f16a3a18391&redirect_uri=https%3A%2F%2Foneclick-nextjs-production-unxsymfqdq-lz.a.run.app%2Fapi%2Fauthorization). 4. Allow OneClick. OneClick shows **Re-authorisation complete** or **Oneclick installed**. 5. Go back to Pipedrive, refresh the page and open a deal, a person or an organization. 6. If the Panel still does not show, install OneClick for your Pipedrive user again. See [Install OneClick as a user](/docs/getting-started/install-as-a-user). If the Panel shows an error message instead of the Buttons, see [Error messages in OneClick](/docs/faq/error-messages). If the Panel shows no Buttons, see [Why no Buttons show](/docs/use-buttons/no-buttons). --- # I cannot see the Settings button Source: https://help.theoneclick.io/docs/faq/i-cannot-see-settings.md The **Settings** button is at the bottom of the OneClick Panel and the Floating window. ![The bottom of the OneClick Panel with the Settings button at the right](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/faq/i-cannot-see-settings/panel-footer.png) OneClick shows the **Settings** button only to a Pipedrive global admin. See [Who can open the Settings](/docs/settings#who-can-open-the-settings). ## You are not a global admin Ask a global admin of your Pipedrive company to make the change in the Settings. A global admin can also give the global admin permission to you in Pipedrive. ## You became a global admin after you installed OneClick OneClick keeps the admin status of each user. It reads the status from Pipedrive when you install OneClick, and it updates the status later. Until the update, the **Settings** button does not show for you. A re-authorisation updates the status immediately. 1. Sign in to Pipedrive. 2. Open the [OneClick re-authorisation link](https://oauth.pipedrive.com/oauth/authorize?client_id=de8c9f16a3a18391&redirect_uri=https%3A%2F%2Foneclick-nextjs-production-unxsymfqdq-lz.a.run.app%2Fapi%2Fauthorization). 3. Allow OneClick. OneClick shows **Re-authorisation complete**. 4. Go back to Pipedrive and refresh the page. 5. Open a deal, a person or an organization. The **Settings** button shows at the bottom of the Panel. If the **Settings** button still does not show, send a message to [support@theoneclick.io](mailto:support@theoneclick.io). ## You have no seat A global admin without a seat also sees the **Settings** button. The Panel shows the message **No seat assinged** instead of the Buttons, and the **Settings** button stays at the bottom. See [You do not have a seat assigned](/docs/faq/you-do-not-have-a-seat-assigned). --- # Error messages in OneClick Source: https://help.theoneclick.io/docs/faq/error-messages.md This page tells what an error message in the OneClick Panel or the Floating window means and what to do. For the error messages during the installation, see [Install OneClick as a global admin](/docs/getting-started/install) and [Install OneClick as a user](/docs/getting-started/install-as-a-user). ## Oops... Couldn't find admin installation OneClick cannot get a valid Pipedrive authorization for your company. It cannot read Pipedrive data until a user gives the authorization again. The message has a **Re-authorise** button. 1. Click **Re-authorise**. OneClick opens Pipedrive, and Pipedrive asks you to allow OneClick. 2. Allow OneClick. OneClick shows **Re-authorisation complete**. 3. Go back to Pipedrive and refresh the page. If the message shows again, ask a Pipedrive global admin who has OneClick installed to do the same steps. You can also re-authorise OneClick without the message: 1. Sign in to Pipedrive. 2. Open the [OneClick re-authorisation link](https://oauth.pipedrive.com/oauth/authorize?client_id=de8c9f16a3a18391&redirect_uri=https%3A%2F%2Foneclick-nextjs-production-unxsymfqdq-lz.a.run.app%2Fapi%2Fauthorization). 3. Allow OneClick. 4. Go back to Pipedrive and refresh the page. ## Missing admin user installation No Pipedrive global admin in your company has OneClick installed. OneClick needs at least one global admin installation to operate. Ask a global admin to install OneClick. See [Install OneClick as a global admin](/docs/getting-started/install). ## No seat assinged You have OneClick installed, but you have no OneClick seat. See [You do not have a seat assigned](/docs/faq/you-do-not-have-a-seat-assigned). ## Seat limit reached OneClick is installed, but your company has no free seats for you. Ask your admin to give you a seat. See [Users](/docs/settings/users#give-a-seat-to-a-user). ## Seat limit exceeded More users have a seat than the subscription of your company allows. An admin must increase the number of seats or remove seats from users. See [Change the number of seats](/docs/settings/subscription#change-the-number-of-seats) and [Users](/docs/settings/users#give-a-seat-to-a-user). ## Connection to Pipedrive lost OneClick lost the connection to Pipedrive. - In the Panel, refresh the Pipedrive page in your browser. - In the Floating window, close the Floating window and open it again. If OneClick then shows **Oops... Couldn't find admin installation**, follow the steps in [Oops... Couldn't find admin installation](#oops-couldnt-find-admin-installation). ## The identification token expired The session of the Panel expired. Refresh the Pipedrive page in your browser. In the Floating window, the message is **Authentication expired**. Close the Floating window and open it again. ## Pipedrive daily limit reached Your Pipedrive company used all of its daily API requests. OneClick cannot read Pipedrive data until Pipedrive gives more requests. Try again later. To use fewer API requests, an admin can turn on **Reveal on hover**. See [General](/docs/settings/general). ## User not found OneClick has no installation for your Pipedrive user. Install OneClick again. See [Install OneClick as a user](/docs/getting-started/install-as-a-user). --- # You do not have a seat assigned Source: https://help.theoneclick.io/docs/faq/you-do-not-have-a-seat-assigned.md Each OneClick user who uses the Buttons needs a seat. When you have no seat, the Panel shows **No seat assinged** and **You have no OneClick seat assinged. Please contact your Pipedrive admin** instead of the Buttons. ## What to do Ask a Pipedrive global admin to give you a seat. The admin does these steps: 1. Click **Settings** at the bottom of the OneClick Panel. 2. Click the **Users** tab. 3. Find your user in the list. 4. Click the switch in the column **Assign seat**. For the full instructions, see [Users](/docs/settings/users#give-a-seat-to-a-user). If all seats are in use, the admin must first get more seats. See [Subscription](/docs/settings/subscription). ## If you are the admin A global admin without a seat can open the Settings. The tabs **Users** and **Subscription** stay open, so you can give a seat to yourself. See [Who can open the Settings](/docs/settings#who-can-open-the-settings). --- # Does a single user need a subscription? Source: https://help.theoneclick.io/docs/faq/single-user-subscription.md No. When only one user in your Pipedrive company uses OneClick, your company uses the **OneClick Solo** plan. This plan has one seat and is free. Install OneClick from the Pipedrive Marketplace. See [Install OneClick as a global admin](/docs/getting-started/install). When a second user must use the Buttons, your company needs the **OneClick Teams** plan. With this plan, you pay a monthly price for each seat, also for the first seat. The **Subscription** tab shows the price of a seat. See [Subscription](/docs/settings/subscription#plans-and-seats). If a OneClick Partner helps your company, your company can have the **OneClick Partner** plan. The Partner then gives the seats. Ask your Partner to add or remove seats. --- # The pop-up window opens in a new tab Source: https://help.theoneclick.io/docs/faq/pop-up-window-opens-in-a-new-tab.md A Link button can open its URL in a pop-up window. The browser decides how it opens the pop-up window. OneClick cannot change this. - Some browsers open a pop-up window in a new tab, or do not support pop-up windows. - Some browsers block pop-up windows. Allow pop-up windows for Pipedrive in your browser. - Some browsers ignore the window options, for example a hidden location bar or hidden scrollbars. For the pop-up settings of each browser, see [Browser limits for pop-up windows](/docs/buttons/link-button#browser-limits-for-pop-up-windows). --- # Can a Link button send a user name and a password? Source: https://help.theoneclick.io/docs/faq/credentials-in-a-url.md No. A Link button cannot sign you in to a website. The Link button puts Pipedrive field values and text into a URL and opens the URL. It cannot type data into the fields of a web page, for example a sign-in form. See [Link button](/docs/buttons/link-button). The best solution is a website that supports single sign-on. The website then signs you in automatically. If the target page must know that a click came from OneClick, use a Signed link. The Signed link does not sign you in. It lets the target page verify the click. See [Signed link](/docs/buttons/link-button/sections/signed-link). --- # Do I have to migrate my Buttons to API v2? Source: https://help.theoneclick.io/docs/faq/migrate-buttons-to-api-v2.md Not at this time. There is no deadline for the migration, and a Button with API v1 continues to operate. But Pipedrive recommends that applications move to [Pipedrive API v2](https://pipedrive.readme.io/docs/pipedrive-api-v2). API v2 is faster and more reliable than API v1. Thus, start the migration soon. ## Which Buttons to migrate Migrate each Workflow button and each Link button that shows **V1** in the Buttons list. See [Manage Buttons](/docs/buttons/manage-buttons). - A new Button uses API v2. - An Interface button has no API version. ## Why the migration is not automatic The field data of API v2 is partially different from API v1. Some fields have a different key, and some fields are not in API v2. You must select these fields again. A migrated Workflow button can also send a different payload to your process. Thus, migrate each Button one at a time, and test it before the users see it. For the steps, see [Migrate to API v2](/docs/buttons/migrate-to-api-v2). --- # Documentation Source: https://help.theoneclick.io/docs.md This page is a placeholder. The real content goes here: an overview of the documentation and where to start. The documentation has three topics: - [Getting started](/docs/getting-started) and the rest of the OneClick documentation. - [Interface Builder](/docs/buttons/interface-button/interface-builder), where an admin builds Interface views. - [Partner Portal](/docs/partner-portal), where a Partner manages its customers and their Buttons. --- # Interface Builder Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder.md Interface Builder builds the views that an Interface button opens in OneClick. - [Tutorials](/docs/buttons/interface-button/interface-builder/tutorials/01-first-interface): Step-by-step guides to build your first interface. - How-to guides: Practical recipes for common tasks. Start with [Button](/docs/buttons/interface-button/interface-builder/how-to/blocks/button). - Reference: Complete reference for all block types, data binding, and styles. Start with [Block types](/docs/buttons/interface-button/interface-builder/reference/block-types/alert). - [Explanation](/docs/buttons/interface-button/interface-builder/explanation/what-is-interface-builder): Conceptual background on the architecture, forms, and visibility systems. --- # Building Your First Interface Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/tutorials/01-first-interface.md ## Opening the Application Interface Builder is accessed from Pipedrive via a OneClick button. When the app loads, you land on the **Interface Selection Page**, which lists all views belonging to this button. You will see two tabs at the top: **Views** and **Variables**. Interface Selection Page when no views exist yet. The Views tab is selected at the top alongside a Variables tab. The 'Fortnox Invoicing / Interface Views' heading is followed by a yellow Beta Feature notice. The 'Your Views (0)' section shows an empty state with a 'No views yet' message, the helper text 'Create your first interface view to get started building custom interfaces.', and a Create New button. ## Creating a New Interface 1. On the Interface Selection Page, click the **Create New** button next to the **Your Views** heading. 2. The **Create new view** dialog opens. 3. Enter a descriptive **Name** — this name is how you will reference it later when setting up navigation between views. The optional **Description** and **Default view** toggle can be left at their defaults. 4. Click **Create**. The new view opens in the Builder. Create new view dialog overlaid on an empty Views list. The dialog contains a focused Name input, an empty Description input, a Default view toggle, and a Create button at the bottom. ## Understanding the Builder When you open a view, the Builder loads with three main areas: - **Canvas** (left side) — the main working area where you build your interface by arranging rows and blocks. - **Sidebar** (right side) — shows configuration options for whatever is selected. It has two main tabs at the top: the current selection tab (Block Settings, Row Settings, etc.) and **View settings**. - **Top Bar** — a navigation bar at the top of the canvas with the interface name, a back arrow to return to the view list, and three buttons on the right: **Preview**, **Test**, and **Sample data**. The top bar also shows a **Saving...** spinner indicator whenever your changes are being auto-saved. Empty Builder view. The top bar shows the view name 'docs-first-interface' on the left, a back arrow, and Preview, Test, and Sample data buttons on the right. The canvas in the center shows a 'Start building' placeholder with an 'Add first row' button. The right sidebar shows the View settings tab with View URL, Global Styles, and View ID fields. ## Adding a Row Before you can place any content blocks, you need a row. Rows define the column layout of your interface. 1. On an empty canvas, click the **Add first row** button. On a non-empty canvas, hover the gap between two rows and click the `+` button that appears. 2. The **Add row** dialog opens. 3. Pick a layout: - **Full width** — a single column at 100% width - **Two columns** — two equal 50/50 columns - **Three columns** — three equal 33/33/33 columns - **Sidebar left** — 25/75 split - **Sidebar right** — 75/25 split - **Form** — adds a Form Start + Form End marker pair (covered in [Building a Form](/docs/buttons/interface-button/interface-builder/tutorials/03-building-a-form)) 4. The dialog closes and the new row appears on the canvas as an empty container with a grey column placeholder. Add row dialog open over the empty canvas. The dialog lists six layout options stacked vertically with icons and short descriptions: Full width, Two columns, Three columns, Sidebar left, Sidebar right, and Form. ## Adding a Title Block 1. Click an empty column inside the row you just created. The **Add block** dialog opens. 2. Pick **Title** from the list. 3. The block appears on the canvas with an empty text value. Add block dialog open over the canvas with the empty Column on the left. The dialog grid lists Button, Title, Paragraph, Image, Divider, Table, HTML, Input (disabled), Navbar, Avatar, Hover Card, Chart, Alert, and Badge. The Title tile is highlighted with a hover state. ## Editing Block Content 1. Click on the Title block in the canvas to select it. 2. The sidebar switches to the **Block Settings** tab. 3. You will see a **Text** field. This is a Data-Picker-enabled input that supports both static text and dynamic data placeholders. 4. Type your title text, for example: `Welcome to My Interface`. 5. The canvas updates in real-time to reflect your changes. Builder canvas with a Full row containing a selected Title block. The right sidebar shows the Block Settings tab with the Configuration sub-tab open. Block Configuration fields are visible: Name 'Title' and Text 'Welcome to My Interface'. ## Adding a Paragraph Block 1. Add another row using the `+` button (or use a multi-column row from before). 2. Click an empty column to open **Add block** and pick **Paragraph**. 3. Click the new Paragraph block to select it. 4. In the **Block Settings** tab you will see a **Value** field — the same Data-Picker-enabled input as the Title block's **Text** field. 5. Type your paragraph text, for example: `This is my first interface built with Interface Builder.` Builder canvas with two Full rows. Row 1 contains a Title block; Row 2 contains a Paragraph block which is currently selected (blue outline). The right sidebar shows the Paragraph block's Block Configuration with Name 'Paragraph' and the Value field filled with 'This is my first interface built with Interface Builder.' ## Previewing Your Interface 1. Click the **Preview** button in the top bar. 2. The view switches from the Builder to Preview mode. 3. In Preview mode, you see your interface rendered as it will appear to end users. Click the **Pipedrive resource** button at the top to pick a specific deal, person, or organization to test with. 4. To return to the Builder, click the back arrow at the top-left of the Preview screen. Preview mode header (back arrow, 'Preview' title, 'Deal #1995' context badge) above the rendered interface. The interface shows the heading 'Welcome to My Interface' and the paragraph 'This is my first interface built with Interface Builder.' ## Saving Your work is saved automatically. After a brief pause in editing, the Builder saves your latest changes to the server. You will see a **Saving...** indicator with a spinner in the top bar while the save is in progress. There is no manual save button — just keep building and your changes are persisted. ## Summary In this tutorial you learned to: - Open Interface Builder from the Interface Selection Page - Create a new view via the **Create New** button and the **Create new view** dialog - Understand the Builder layout: canvas, sidebar, and top bar - Add rows from the **Add row** dialog and pick column layouts - Add Title and Paragraph blocks from the **Add block** dialog - Edit block content via the sidebar - Preview your interface - Rely on auto-save for persisting your work --- # Displaying Pipedrive Data in Your Interface Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/tutorials/02-data-binding-basics.md ## What is Data Binding? Interfaces display data from Pipedrive resources -- deals, persons, organizations, and more. Instead of typing fixed text, you bind a block's text input to a field through the **Data Picker**, and the field's current value is rendered at run time. The Data Picker inserts each field as a small **blue tag** into the editor. The compiled syntax behind the tag is `{{resource.field}}` (for example `{{deal.title}}`), but in the builder you do not type that syntax yourself -- you click the tag you want and the editor renders it as a tag. ## Opening the Data Picker 1. Select a block on the canvas (for example, a Title or Paragraph block). 2. In the Block Settings panel, find a **Data Picker-enabled input**: Title's **Text** field, Paragraph's **Value** field, and similar fields on other blocks. 3. Click inside the input. A **Data Picker tooltip** appears next to the field. 4. The tooltip's top bar contains an icon-only row of tabs: - **Deal** -- deal fields (title, value, currency, owner, ...) - **Organization** -- organization fields (name, address, ...) - **Person** -- person fields (name, email, phone, ...) - **User** -- the current logged-in user - **Custom** -- the JSON payload returned by your view's API endpoint or your saved Sample data - **Search Params** -- URL parameters passed in from another view - **Variable** -- interface-level variables you define in the Variables tab - **Functions** -- built-in helper functions Title block selected on the canvas, Text field clicked in the Block Configuration sidebar, and the Data Picker tooltip open beneath it. The top row shows the eight icon-only tabs (Deal selected); below is a search field and a list of deal fields including ID, Title, Creator, Value, Contact person, Organisation, Stage, Currency, Add time, Update time, Status, and Probability. ## Browsing Available Data 1. Click a tab to see the fields for that resource. 2. Simple fields (such as `title` or `value`) can be clicked directly to insert them as a tag. 3. Nested fields are expandable. For example, the deal's owner is an object -- expand it to pick `owner_id.name`. 4. The Data Picker remembers which tab you last opened. ## Binding a Deal Title to a Title Block 1. Add a **Title** block to your canvas (or select an existing one). 2. In Block Settings, click the **Text** field. The Data Picker opens. 3. Select the **Deal** tab. 4. Click on **Title**. 5. A blue **Title** tag is inserted into the Text field. The compiled value is `{{deal.title}}`, but you don't see the curly-brace syntax -- you see the tag. Title block on the canvas with the sidebar showing Block Configuration: Name 'Title' and a Text field that contains a single blue Data Picker tag labelled 'Title'. No curly-brace syntax is visible in the editor. ## Combining Static Text and Dynamic Data You can mix typed text with multiple tags in a single field. 1. Add a **Paragraph** block and select it. 2. In the **Value** field, type: `Deal: ` 3. Open the Data Picker and insert the deal **Title** tag. 4. Insert the deal **Currency** tag right after it (or with a space between them). The editor now shows: `Deal:` followed by a Title tag and a Currency tag. The compiled output is `Deal: {{deal.title}} {{deal.currency}}`. This technique works in any Data Picker-enabled field across all block types. Paragraph block on the canvas with the sidebar showing Block Configuration: the Value field starts with the static text 'Deal:' followed by two blue Data Picker tags ('Title' and 'Currency') from the deal tab. ## Testing with Real Data 1. Click **Preview** in the top bar to switch to Preview mode. 2. In the Preview top bar, next to the **Preview** title, there is a **Pipedrive resource** button labelled with the active resource (for example `Deal #1995`). Click it to open the **Pipedrive resource** dialog and pick a different deal, person, or organization from your account. 3. The system fetches the real data for the selected resource and replaces every Data Picker tag with the actual value. 4. Your Title and Paragraph blocks render with live Pipedrive data. If a tag references a resource that is not present (for example a person tag when no person is linked), the rendered value may be empty. Preview mode top bar shows the Preview heading and a 'Deal #1995' resource button. Below it the Title block renders as 'Legendary 1995' and the Paragraph block renders as 'Deal: Legendary 1995 EUR' -- the Title and Currency tags resolved against the live deal. ## Understanding Data Types The Data Picker organises fields by data type: - **String** -- text values such as names, titles, emails. - **Number** -- numeric values such as deal amounts and phone numbers. - **Object** -- nested structures (for example `deal.owner_id` containing `name`, `email`, ...). Expand the object to pick a sub-field; the resulting tag follows the path. - **Array** -- lists of items (for example deal products). Arrays are used by blocks that iterate, such as the Table block (covered in a later tutorial). When you pick a sub-field of an object, the Data Picker creates a tag that renders the dotted path (for example `owner_id.name`). ## Summary In this tutorial you learned to: - Bind block fields by inserting Data Picker tags instead of typing placeholder syntax - Browse the eight Data Picker tabs (Deal, Organization, Person, User, Custom, Search Params, Variable, Functions) - Mix static text and multiple tags in a single field - Preview your interface with a chosen Pipedrive resource via the Preview top-bar dialog - Work with nested object fields by expanding them in the Data Picker --- # Building a Form Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/tutorials/03-building-a-form.md ## How Forms Are Structured A form in Interface Builder is defined by two marker rows on the canvas -- **Form Start** at the top and **Form End** at the bottom -- with your content rows in between. Every input placed between those markers belongs to the form. A **Submit button** links to the form by its **Form Identifier** and is what users click to send their answers. The screenshot below shows the finished tutorial form on the canvas: Form Start carries the `contact-form` identifier badge, and the Submit button shows the same `contact-form` badge — that match is how the button knows which form to send. Builder canvas showing the completed contact-form. Form Start (Row 1) is selected and carries a 'contact-form' badge next to the row label. Row 2 holds a Full Name input with type Text. Row 3 holds an Email Address input with type Email and a small red asterisk marking it Required. Row 4 holds a Submit button with two badges — 'Submit' and 'contact-form'. Row 5 is Form End. The right sidebar shows Form Settings with Form Identifier 'contact-form' and four padding inputs all at 0 px. ## Step 1: Add a Form Element 1. Hover the canvas (or the gap between two rows) to reveal a small `+` button. 2. Click `+` to open the **Add row** dialog. 3. Pick **Form** from the layout list. Two marker rows appear on the canvas: **Form Start** on top and **Form End** at the bottom, with empty space between them. Add row dialog open on top of the empty canvas. Six layout options are listed vertically — Full width, Two columns, Three columns, Sidebar left, Sidebar right, and Form. The Form option is at the bottom and is highlighted with a hover state, with the description 'Form container for input fields'. ## Step 2: Give the Form an Identifier 1. Click the **Form Start** row (Form End works too). 2. The sidebar switches to **Form Settings**. 3. In the **Form Identifier** field, enter a descriptive name. For this tutorial, use `contact-form`. The identifier shows up as a badge on Form Start on the canvas, and it is how the Submit button (added later) will find the correct form. Form Settings tab open in the right sidebar with the Form Identifier field set to 'contact-form'. Padding Top, Bottom, Left, and Right inputs sit below at 0 px. On the canvas, the Form Start row now shows 'contact-form' as a badge next to the row label. ## Step 3: Add a Full-Name Input 1. Hover the area between Form Start and Form End — a `+` button appears. 2. Click `+`, pick a one-column **Full** layout in the **Add row** dialog. 3. Click the empty column inside that new row to open the **Add block** dialog and pick **Input**. 4. Click the new Input block to open its settings. You will see fields for **Label**, **Type**, **Placeholder**, **Help text**, **Default Value**, **Required**, and **Disabled**. 5. Set **Label** to `Full Name`. 6. Leave **Type** as **Text**. Block Configuration sidebar for an Input block. Name 'Input', Label 'Full Name', Type 'Text'. Placeholder, Help text, Pattern, and Default Value fields are empty below. Required and Disabled toggles at the bottom are off. The canvas on the left shows the new Input row inside the contact-form, with the 'Missing submit button' warning visible above it. ## Step 4: Add an Email Input 1. Repeat the same steps to add another row inside the form. 2. Add a second Input block in the new column. 3. Set **Label** to `Email Address`. 4. Change **Type** to **Email**. 5. Turn on the **Required** switch. Builder canvas with the contact-form holding two input rows between Form Start and Form End. Row 2 is a Text input labeled 'Full Name'; Row 3 is an Email input labeled 'Email Address' (currently selected, with Required toggled on in the sidebar). The 'Missing submit button' warning sits between Form Start and the input rows. ## Step 5: Add a Selection Input (Optional) If you want a drop-down or multi-choice field, pick one of these selection types for **Type**: **Single Select**, **Multi Select**, **Checkbox**, or **Radio**. An **Options Type** selector then appears with two choices: - **Static** -- you define label/value pairs manually. Use the options editor that appears to add each pair. - **Dynamic** -- options come from data at render time using the Data Picker. Enter Data Picker expressions for **Labels** and **Values**. ## Step 6: Add Pattern Validation (Optional) For the simple input types (Text, Email, Number, URL, Date) you can add regex validation: 1. In the input settings, scroll to the **Pattern** field and enter a regex (for example, `^[A-Za-z ]+$`). 2. Optionally fill **Pattern Error** with a custom message shown when the pattern fails. Test your regex at [regex101.com](https://regex101.com/) before pasting it in. ## Step 7: Add a Submit Button 1. Add a new row using the `+` button. It can be inside or outside the form boundaries — both work. 2. Click an empty column in the new row, then pick **Button** in the **Add block** dialog. 3. Click the new Button to open its settings. Set **Button Type** to **Form Submit Button**. 4. A **Form** dropdown appears. Pick `contact-form` from the list. Block Configuration sidebar for the new Button block. Button Type is set to 'Form Submit Button' and the Form dropdown shows 'contact-form'. Below them, Form Type 'JSON', an empty Submit URL (highlighted in red because it has no value yet), After submission 'Wait for response', and Timeout '10' s are visible. The canvas on the left shows the full form: Form Start (contact-form), Full Name input, Email Address input, Button row, Form End. ## Step 8: Configure Submission Once Button Type is Form Submit Button, extra settings appear. You will set **Form Type**, **Submit URL**, and an **After submission** behavior. ### Form Type - **JSON** (default) -- posts form values as a JSON payload to the Submit URL. - **Multipart/Form-Data** -- use this whenever any input has **Type = File**. - **Open view with form data** -- instead of posting anywhere, navigates to another view and passes input values as URL search parameters. ### Submit URL For **JSON** and **Multipart/Form-Data**, enter the endpoint in **Submit URL**. Opening the URL input reveals an advanced dialog where you can also add: - **Headers** -- custom HTTP headers (key/value pairs; values support the Data Picker). - **Query parameters** -- additional query string pairs. ### After submission Pick one of: - **Wait for response** -- waits up to **Timeout (s)** seconds (10--60) for the server to reply. You can turn on **Disable form after submission** (prevents double-submits) and **Show message after submission** (displays the server's confirmation). - **Select view** -- immediately navigates to a chosen **View ID** after sending. You can pass static parameters, and optionally forward every input value as search parameters to the target view. Submit button settings scrolled down to show advanced submission configuration. Form Type 'JSON', a red 'Submit URL' button (empty), After submission 'Wait for response', Timeout '10' s, Form State toggle 'Disable form after submission', User Feedback toggle 'Show message after submission', and Validation Behavior toggles ('Show error indicator on submit button', 'Scroll to first error field', 'Show error toast on submit'). ## Step 9: Add a Reset Button (Optional) To let users clear the form: 1. Add another Button block (use the `+` button to add a row, then **Add block** → **Button**). 2. Set **Button Type** to **Form Reset Button**. 3. In the **Form** dropdown, pick `contact-form`. ## Step 10: Test the Form 1. Click **Preview** in the top bar. The form renders with live inputs. 2. Fill in the fields and click the submit button to see the behavior you configured. 3. For an end-to-end test, click **Test** in the top bar -- test mode runs the interface closer to production. Preview mode header with a back arrow, 'Preview' title, and a 'Deal #1995' context badge. Below it, the contact-form is rendered with two filled fields — Full Name 'Sarah Johnson' and Email Address 'sarah.johnson@example.com' — and a blue submit Button at the bottom right of the form. ## Summary In this tutorial you learned how to: - Pick **Form** in the **Add row** dialog and work with the **Form Start** / **Form End** markers on the canvas - Set a **Form Identifier** to name the form - Add **Input** blocks with different **Types** (Text, Email, and selection types) - Configure selection inputs with **Options Type** (Static or Dynamic) - Add **Pattern** validation with a custom **Pattern Error** message - Add a **Form Submit Button** and link it to the form - Configure **Form Type**, **Submit URL**, **Headers**, and **After submission** - Add a **Form Reset Button** to clear the form - Test the form in Preview and Test modes --- # Building a Multi-View Application Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/tutorials/04-multi-view-app.md ## What are Views? An interface can contain multiple **views** (pages). Each view is a separate canvas with its own rows and blocks. One view is marked as the **default view** -- it carries a green **Start** badge in the views list and is the view displayed by default when the interface loads. Users navigate between views using: - **Action buttons** with the "go to view" action - **Navbar blocks** with interface-type links Views are managed from the **Interface Views** page, where every view in the current interface is shown as a card. ## Creating a Second View 1. Go back to the **Interface Views** page by clicking the back arrow in the top bar of the Builder. 2. Click **Create New** to open the **Create new view** dialog. 3. Give it a descriptive name (for example `Order summary`) and click **Create**. 4. Back on the Interface Views list, click the **Edit** button on the new view's card to open it in the Builder. Interface Views page with two view cards. The Create New button is in the top-right of the list, and each card shows the view name, description, row count, and Edit / Settings / Copy / Delete actions. ## Building the Second View 1. With the new view open in the Builder, add rows and blocks as needed. 2. For example, add a Title block bound to `{{deal.title}}` and a Paragraph block showing deal details. 3. This view will serve as a detail page that users navigate to from the first view. ## Adding Navigation with an Action Button On the first view, set up a button that navigates to the second view: 1. Go back to the Interface Views page and open your first view. 2. Add a **Button** block to the canvas. 3. In Button settings, set the **Button Type** to `Action Button`. 4. A new **Action Type** dropdown appears with two options: - **back** -- navigates to the previous view - **go to view** -- navigates to a specific view 5. Select **go to view**. 6. A **View Name** dropdown appears, listing all views in this interface. Select the second view you just created. 7. The button now navigates users to that view when clicked. Block Configuration sidebar for an Action Button. Button Type is 'Action Button', Action Type is 'go to view', and the View Name dropdown is open showing 'Customer details' and 'Detail View' as available targets. ## Adding a Back Button On the second view, add a way to return to the first view: 1. Open the second view in the Builder. 2. Add a **Button** block. 3. Set the **Button Type** to `Action Button`. 4. Set the **Action Type** to **back**. 5. This button returns users to whatever view they came from. The settings panel looks the same as for "go to view" — just without the **View Name** dropdown. ## Passing Parameters Between Views Action buttons can pass data from one view to another using parameters. The receiving view accesses these values via the **Search Params** tab in the Data Picker. 1. On the first view, select your "go to view" Action Button. 2. Below the View Name dropdown, you will see a **Parameters** section. 3. Click to open the parameters dialog. 4. Add key-value pairs. For example: - Key: `deal_id`, Value: a Data Picker tag pointing to the deal's **ID** field. - Key: `deal_title`, Value: a Data Picker tag pointing to the deal's **Title** field. 5. Values support Data Picker expressions, so you can pass dynamic data. On the receiving view: 1. Select a block (for example, a Title block). 2. Open the Data Picker and switch to the **Search Params** tab (the icon-only tab in the picker's top bar). 3. You will see the parameter keys you defined. Selecting one inserts a tag that compiles to `{{searchparams.deal_id}}`. Manage Parameters dialog with two rows: deal_id paired with a blue Data Picker tag for the deal's ID field, and deal_title paired with a Data Picker tag for the Title field. Add Parameter, Cancel, and Save Parameters buttons sit at the bottom. ## Using Navbar for Navigation For persistent navigation across your interface, use a **Navbar** block: 1. Add a **Navbar** block to a row on your view. It typically goes in a full-width row at the top. 2. Click the Navbar block to open its settings. The settings are divided into sections. ### Brand - Toggle **Show title** to display a text title in the navbar. Configure **Title Text**, **Font Size (px)** (12–48), **Font Weight** (Normal, Medium, Semibold, Bold), and **Title Color**. - Toggle **Show logo** to display a logo image. Provide the **Image URL**, **Alt Text**, and **Width / Height (px)**. ### Aria Label Below the Brand section, set the **Aria Label** for the navigation element (defaults to "Navigation menu"). This helps screen readers identify the navigation purpose. ### Layout - **Layout Direction** — Horizontal or Vertical - **Alignment** — Left, Center, Right, or Space Between - **Spacing (px)** — pixel spacing between nav items (0–50) ### Navigation Links 1. Click the **Manage Links** button to open the links dialog. 2. Click **Add** to create a new link. Each link has: - **Label** — the text displayed in the navbar - **Link Type** — choose between: - **Interface** — navigates to another view within this interface. Select the target view from the **Target Interface** dropdown. You can also add **Parameters** (key-value pairs) that are passed to the target view. - **External URL** — opens an external URL (supports Data Picker expressions) 3. Add links for each view you want in your navigation. 4. Reorder links by dragging the grip handle on each link card. 5. Delete links using the trash icon. Manage Links dialog with two Interface-type links. The first ('Customers') is expanded showing Label, Link Type set to Interface, and Target Interface set to 'Customer details'; the second ('Detail') is collapsed below. The Navbar's Brand, Aria Label, and Layout settings are visible in the sidebar behind the dialog. Preview of the view rendered with the Navbar in place: 'My App' brand title on the left and the 'Customers' and 'Detail' links on the right. The Action Button is visible above the navbar. ## Summary In this tutorial you learned to: - Create multiple views from the Interface Views page - Use Action Buttons with the "go to view" action to navigate between views - Add "back" buttons for return navigation - Pass parameters between views using key-value pairs and Data Picker expressions - Access passed parameters on the receiving view via the Search Params tab - Set up a Navbar block with interface-type links for persistent navigation - Configure navbar Brand, Aria Label, Layout, and link settings --- # Building a Table View Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/tutorials/05-table-view.md ## When to Use Tables The **Table** block displays array data in a structured grid with rows and columns. Common use cases include: - Displaying deal products or line items - Showing lists of related contacts or organizations - Rendering any array data from Pipedrive or custom sources Tables support configurable columns, per-row actions, sorting, conditional visibility, and custom styling. ## Adding a Table Block 1. Hover the canvas (or the gap between rows) to reveal the `+` button. Click it and pick **Full** in the **Add row** dialog — full-width works best for tables. 2. Click the empty column inside the new row to open **Add block**, then pick **Table**. 3. Click the Table block to open its settings in the sidebar. Add block dialog open over a full-width row on the empty canvas. The dialog grid lists Button, Title, Paragraph, Image, Divider, Table, HTML, Input (disabled outside forms), Navbar, Avatar, Hover Card, Chart, Alert, and Badge. The Table tile is highlighted with a hover state. ## Setting the Data Source The table needs an array data source to iterate over. 1. In Table settings, find the **Target Array** field. This is a Data Picker input that specifies which array to display. 2. Click the Target Array field to open the Data Picker. 3. Navigate to an array field. For example, under the **Deal** tab, find a field that contains array data (such as deal products or a custom field that returns a list). 4. You can also use the **Custom** tab if your data comes from a custom JSON source. 5. Select the array field. The placeholder is inserted into the Target Array field. The table renders one row per item in the array. Block Configuration sidebar on the right showing the Table block's settings: Name 'Table', Table Title (empty), Title Alignment 'Left', Default Cell Alignment 'Left', and a focused Target Array field. The Data Picker has opened next to the field with the Deal tab selected, listing fields like ID, Title, Creator, Value, Contact person, Organisation, Stage, Currency, Add time, Update time, Status, and Probability. ## Table Header (Optional) Above the data source, the sidebar exposes: - **Table Title** — optional text rendered above the table, for example `Deal Products`. It is plain text: the Data Picker is not available here. - **Title Alignment** — Left, Center, or Right alignment for the title text. - **Default Cell Alignment** — fallback alignment applied to every column that does not set its own alignment. Choose Left, Center, or Right. - **Empty table text** — text shown when the Target Array resolves to an empty list. This is a Data Picker input and supports dynamic values. ## Configuring Columns Columns define what data appears in each table column. Use the **Manage Columns** dialog to add and configure them. 1. Click the **Manage Columns** button in Table settings. 2. The dialog opens with a column list on the left and a settings panel on the right. 3. Click the **Add** dropdown to add a new column. You can choose between: - **Add value column** — displays data from each array item. - **Add action column** — displays clickable action icons. - **Add subrow** — displays an extra row of text rendered below each row (useful for descriptions or secondary info). 4. Select a column on the left to edit its settings on the right. Columns can be reordered by dragging the grip handle, duplicated with the copy icon, or deleted with the trash icon. Subrow columns cannot be reordered — they always render below the main row. Each column has its settings split across four tabs in the right panel: - **General** — the data fields that drive the column. - **Styling** — width, cell alignment, and cell padding. - **Sorting** — whether the column is sortable and how. - **Conditional** — when the column is visible. ### Value Columns: General Tab For each value column, fill in: - **Header** — the column header text. This is a Data Picker input, so you can use static text or dynamic values. - **Value(s)** — the data field to display for each row. This is a Data Picker input that resolves relative to each array item. For example, if your array contains objects with a `name` property, enter `name` or use the Data Picker to select the field. Manage Columns dialog. Left panel: a single column entry '(Value) Column 1' with row controls and an 'Add' button at the bottom. Right panel: tabs General (selected), Styling, Sorting, Conditional. The General tab shows Header set to 'Product' and Value(s) set to 'name', followed by the Column Overview cards summarizing Styling (Left, Auto, Padding off), Sorting (disabled), and Conditional (Always visible). ### Value Columns: Styling Tab - **Cell Alignment** — Left, Center, or Right for the cell content. - **Column Width** — pick **Auto**, or set a fixed width in `%` or `px`. - **Cell padding** — toggle to override the table default. When enabled, you can set Top, Right, Bottom, and Left padding individually. ### Value Columns: Sorting Tab - **Allow sorting** — toggle to let end-users click the column header to reorder rows. - **Sort by this column** — when enabled, this column is the table's default sort. Only one column can hold this flag. - **Sort direction** — **Ascending** or **Descending** for the default sort. - **Custom sort value** — when enabled, sort rows by a different value than the displayed one. Provide a Data Picker path for **Sort value**. Manage Columns dialog with the Sorting tab open for a value column. Allow sorting toggle is on (blue), Sort by this column checkbox is checked, Sort direction is set to Ascending. Below them, a Custom sort value toggle (off) and a disabled Sort value Data Picker input, with a helper note explaining that custom sort value is useful for sorting by a raw number while displaying a formatted value. ### Value Columns: Conditional Tab - **Enable conditional visibility** — toggle to hide the column based on a condition. - **Condition** — Data Picker expression. The column is hidden when the value resolves to empty or `"false"`. Any other value shows the column. ## Action Columns Action columns add clickable buttons to each row, allowing users to perform operations on individual items. A button can show an icon, a text label, or both. 1. In the Manage Columns dialog, click **Add** and select **Add action column**. 2. The General tab shows the column's **Header** plus an accordion of **actions**. Each action has: - **Icon** — choose from grouped **Actions**, **Communication**, **Files**, and **Status** icons. The set includes View, Edit, Delete, Add, Copy, Play, Refresh, External link, Mail, Send, Phone, Message, Bell, User, File, Folder, Download, Upload, Image, Attachment, Print, Archive, Check, Close, Warning, Info, Clock, Star, Heart, Lock, and Unlock. Select **Custom** to fill **Custom Icon** with an image URL through the Data Picker. - **Action Type** — pick **Go to view** to navigate within the interface, **Go to URL** to open a URL, or **Send request** to send a POST without leaving the table. - **Label** — optional button text, shown after you pick an Action Type. It supports the Data Picker and resolves per row. With a Label set, **Icon position** chooses which side the icon sits on, and the Icon picker offers **No icon** for a text-only button. - **View Name** — when Action Type is **Go to view**, pick the destination from the dropdown. Optionally configure **Parameters** (key-value pairs passed to the target view; values reference fields from the current row). - **URL** — when Action Type is **Go to URL**, fill the address. The URL field supports Data Picker expressions, so you can construct URLs with row data. - **Request URL** — when Action Type is **Send request**, enter an absolute HTTP or HTTPS endpoint. Use the Data Picker to include row values. - **Body Data** — optionally configure a JSON payload as JSON or key-value pairs. Include the row's identifier because OneClick metadata identifies the view resource, not the row. Leave it empty for no configured body. - **Omit OneClick metadata envelope** — leave off to send Body Data alongside OneClick metadata; turn on to send only Body Data. Test requests in the Test view; Preview shows them disabled. - **Require confirmation** — when Action Type is **Send request**, turn this on to ask before the request is sent. The **Title** and **Description** support the Data Picker, so the dialog can name the row it acts on. 3. Click **Add Action** to add more actions to the same column. 4. Each action can be duplicated or deleted from the action's accordion menu. The Styling, Sorting, and Conditional tabs apply to action columns in the same way as value columns. Manage Columns dialog with '(Action) Column 2' selected on the left. The General tab is open and shows the column's Header field, then an expanded 'Action 1 (View)' card with Icon set to 'View' (eye), Action Type 'Go to view', an empty View Name dropdown, and a Params section with an 'Add Param' button. An 'Add Action' button below allows additional actions on the same column. ### Passing Row Data to Another View When an action navigates to a view, you can pass data from the current table row: 1. Set the action's **Action Type** to **Go to view**. 2. Choose the target view from **View Name**. 3. Expand the **Parameters** section. 4. Add key-value pairs where the values reference fields from the current array item. The Data Picker context is scoped to the current row, so you can directly select fields from the row item. ## Subrow Columns A **subrow** column adds a second line of text below each main row — useful for descriptions, hints, or secondary details that do not need their own column. - **Path** — the data field rendered as the subrow's text (Data Picker). - The Styling tab supports **Cell Alignment** and **Cell padding** for the subrow text. Conditional visibility is not available for subrow columns. ## Customizing Appearance In addition to per-column styling, the Table block uses the standard block style settings: - **Background color** - **Font size and color** - **Borders** — top, right, bottom, and left borders with width, style, and color The table renders with structured headers and data rows. When the array is empty, the **Empty table text** (if configured) is shown. Preview mode header (back arrow, 'Preview' title, 'Deal #1995' context badge) above a rendered table. The table shows a single header row with a sort indicator in the first column and a centered 'No data' message in the body — the empty state shown when the configured Target Array resolves to an empty list. ## Summary In this tutorial you learned to: - Add a Table block and set its data source via the **Target Array** field - Configure the **Table Title**, **Title Alignment**, **Default Cell Alignment**, and **Empty table text** at the table level - Add **value**, **action**, and **subrow** columns from the **Manage Columns** dialog - Configure each column across the **General**, **Styling**, **Sorting**, and **Conditional** tabs - Add **Go to view**, **Go to URL**, and **Send request** actions with per-row data - Toggle **Allow sorting**, set a default sort column and direction, and use a custom sort value - Hide columns conditionally using the **Conditional** tab --- # Creating a New View Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/views/creating-a-view.md ## Interface Views Page Open the views list for an interface from the interface management page (the **Interface Domain > Interface Views** breadcrumb). The page shows every view in the interface as a card with its name, description, row count, and the **Start** badge on whichever card is the main view. The Interface Views list with two view cards: 'Customer details' (highlighted with a green border and a Start badge as the main view) and 'Order summary'. Each card shows the view name, description, '1 row' counter, an Interface type label, and Edit / Settings / Copy / Delete action buttons. A 'Create New' button sits at the top right of the Your Views (2) section, with a Beta Feature warning above the cards. ## Creating a New View 1. Click **Create New** in the top-right of the **Your Views** section. 2. The **Create new view** dialog opens. Fill in: - **Name** -- a unique, descriptive name. The name is used in navigation references (action buttons, navbar links, form-after-submit selectors) and in the view-selector dropdowns inside the builder. Choose clear names like `Customer details`, `Order summary`, or `Edit form`. - **Description** -- optional context shown on the view card. - **Default view** -- when on, this view becomes the interface's main view (see [Main View](#main-view) below). The first view of an interface is forced to be the default and the toggle is disabled. 3. Click **Create**. The view is created with an empty canvas and the builder opens automatically. ## Editing the View in the Builder Click **Edit** on a view card (or open a view from the breadcrumbs) to start working on it in the builder. From there you can: - Add rows and blocks. - Configure data bindings via the Data Picker. - Set Global Styles for view-wide font, colour, and gap defaults. - Configure Areas to group rows for shared visibility or looping. Each view has its own independent layout, rows, blocks, and settings. Edits auto-save -- there is no separate save or publish step. See [Saving](/docs/buttons/interface-button/interface-builder/how-to/views/publishing) for the auto-save and validation rules that apply. ## Card Actions Each view card has four action buttons: | Button | What it does | |---|---| | **Edit** | Opens the view in the builder. | | **Settings** | Opens the **Edit view** dialog. Same fields as **Create new view** plus a read-only **ID** -- use this dialog to rename, edit the description, or change which view is the main view. | | **Copy** (clipboard icon) | Duplicates the view inside the same interface. The copy is never the main view. | | **Delete** (trash icon) | Removes the view after a confirmation prompt. | ## Main View The main view is the one that opens when a user clicks the OneClick button in Pipedrive. In the views list it is highlighted with a green border and a **Start** badge (star icon) on the card preview. To change which view is the main view: 1. Click **Settings** on the view card you want to promote. 2. In the **Edit view** dialog, turn on the **Default view** switch. 3. Save. Only one view can be the main view at a time -- enabling **Default view** on a different card automatically clears it on the previous main view. Other views are reached through navigation actions: Action Buttons, Navbar links, Table action columns, and form submissions. See [Navigating Between Views](/docs/buttons/interface-button/interface-builder/how-to/views/navigation) for setup details. --- # Managing Interface Views Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/views/managing-interface-views.md Interface Views is the top-level list of all views under a single interface (for example, a deal-details panel, a product form, a summary page). This page covers the tools for managing that list from the home screen. ## The Interface Views list Open the Interface Views page from the home screen. The list shows one card per view. Each card contains: - A **preview area** with an abstract miniature of the view's layout. Hovering reveals an **Open Editor** overlay you can click to jump straight into the builder. - A **Start** badge in the top-left of the preview when the view is the interface's default view. - An **Error** badge instead, if the view's saved data fails to parse. - The view **name** and **description**. - Stats: the **row count** and an **Interface** label. - Action buttons: - **Edit** -- the primary call-to-action; opens the view in the builder. - **Settings** -- opens the view's settings dialog (rename, edit description, mark as default, etc.). - **Copy view** -- icon button with a tooltip; duplicates the view. - **Delete view** -- icon button with a tooltip; removes the view. Interface Views home screen with two view cards. The left card 'Customer details' shows a green Start badge in its preview, the row count '1 row', and the Edit, Settings, Copy, and Delete action buttons. The right card 'Order summary' has the same layout without a badge. ## Copying a view Click the **Copy view** icon on any card to duplicate it. The new view appears instantly as `" (Copy)"` and contains a full snapshot of every row, block, area, and data source. Use this when you want to iterate on a view without breaking the production version, or when you need several similar views that differ only slightly. ## Deleting a view 1. Click the **Delete view** icon on a card. 2. The card switches to an inline confirmation: **"Delete this view?"** with **Cancel** and **Delete** buttons. 3. Click **Delete** to remove the view, or **Cancel** to back out. This action cannot be undone from the views list. If you took a [snapshot](/docs/buttons/interface-button/interface-builder/how-to/views/snapshots) before the delete, restore that snapshot to get the view back with its original id. The restore returns all views and variables to the state of the snapshot, and you can undo it. Interface Views list with the right card 'Order summary' switched to its inline delete confirmation state. The action row reads 'Delete this view?' followed by Cancel and Delete buttons; the left card 'Customer details' is unchanged. --- # Navigating Between Views Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/views/navigation.md ## Action Button The Action Button is the primary way to navigate between views. 1. Add a **Button** block to your view. 2. Set **Button Type** to **Action Button**. 3. Choose an **Action Type**: - **go to view** -- navigates to a selected view. A **View Name** dropdown lists every view in the interface. - **back** -- returns to the previous view. 4. Optionally click **Handle params** under **Parameters** to add key/value pairs that get forwarded to the target view. Values support the Data Picker. Builder view 'Buttons demo' with an Action Button selected on the canvas. The Block Settings sidebar shows Name 'Button', Button Type 'Action Button', Action Type 'go to view', View Name 'Buttons demo', and a Parameters section with a 'Handle params' button. ## Navbar Links The **Navbar** block supports interface-type links for view navigation: 1. Add a **Navbar** block to your view. 2. Click **Manage Links** in Block Settings to open the link manager dialog. 3. Click **Add** and configure the new link: - **Label** -- the clickable text shown on the navbar. - **Link Type** -- pick **Interface** for in-interface navigation (or **External URL** for an outside link). - **Target Interface** -- the destination view dropdown. Shown when **Link Type** is **Interface**. - **Parameters** -- key/value pairs passed to the target view. Click **Add Parameter** to add rows. The Navbar block's Manage Links dialog open over the docs-navbar view. The first link 'Home' is expanded and shows Label 'Home', Link Type 'Interface', Target Interface 'Account Summary', and an empty Parameters section with an 'Add Parameter' button. A second link 'Documentation' is collapsed below it. ## Table Actions Table blocks can include row action columns that navigate to views. Configure a column as an action column, add an action with **Action Type = Go to view**, pick a **View Name**, and optionally add **Params** -- the action will navigate to the chosen view with those params, alongside the row's data, when a user clicks the icon. ## Form After Submit When a form is submitted, you can navigate to a different view: 1. Set the submit button's **After submission** to **Select view**. 2. Pick the target view from the **View ID** dropdown. 3. Optionally add **Parameters** -- key/value pairs passed alongside the navigation. 4. Turn on **Use input values as search params** to automatically forward every form field value as a URL search parameter on the navigation. Alternatively, set **Form Type** to **Open view with form data** to skip the HTTP submission entirely. The submit button hides its Submit URL and After submission settings, forwards every form input value as a search parameter to the chosen view, and navigates immediately when the user clicks submit. ## Passing Parameters All navigation methods support passing parameters: - **Action Button** -- click **Handle params** under **Parameters** and add key / value entries. - **Table action column** -- each action has its own **Params** key / value editor. - **Navbar links** -- each link has its own **Parameters** section inside the Manage Links dialog. - **Form Submit Button** (After submission = **Select view**) -- use **Parameters** for explicit pairs and / or **Use input values as search params** to forward every form field. The target view receives these as URL search parameters, accessible from the Data Picker's `searchparams` tab (icon-only) and compiled to `{{searchparams.key}}` placeholders at render time. --- # Saving Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/views/publishing.md ## Auto-Save Interface Builder saves automatically. After you stop editing for a brief moment, the change is written to the server -- there is no save button and no publish step. You do not push a view live; it **is** live. The moment a save completes, anyone opening the view in Pipedrive sees your latest edits. :::caution[Every save is immediately live] Preview and Test modes inside the builder render against the same saved data — they do **not** isolate changes from end users. Anyone opening the OneClick button while you're editing sees your in-progress edits. See [External Data Flow](/docs/buttons/interface-button/interface-builder/explanation/external-data-flow) for what each mode does and does not call. For risk-free experimentation, copy the OneClick button in Pipedrive and edit the copy's interface, then point users at the new button when the changes are ready. ::: ## Validation Before each save the builder runs a validation pass over the whole view -- rows, blocks, forms, and every setting. If something is wrong, an **Action required** card appears on the canvas with a quick-fix button, and the save is blocked until you resolve the issue. This means a broken view never reaches end users. An 'Action required' card on the canvas. The card has an amber file-input icon, the heading 'Missing input field', the body text 'Your form needs at least one input field for users to enter data.', and an 'Add input' quick-fix button at the bottom. The card icon, title, description, and quick-fix button vary by issue. For incomplete forms the card title is **Missing input field** (with an **Add input** button) or **Missing submit button** (with an **Add submit button** button); other issues surface as inline errors next to the affected field in Block Settings. ## Common Validation Errors These messages come straight from the validation layer. Each one blocks save until fixed. | Error | Cause | Fix | |---|---|---| | **Form requires at least one submit button** | A form has no submit button. | Add a Button block with **Button Type = Form Submit Button** and pick this form in the **Form** dropdown. | | **Form requires at least one input field** | A form has no Input blocks. | Add at least one Input block between Form Start and Form End. | | **Form start requires a corresponding form end** | A `Form Start` row exists without a matching `Form End`. | Add the `Form End` row, or delete the orphan `Form Start`. | | **Input field must be inside a form** | An Input block sits outside any form. | Move it between a `Form Start` and `Form End` row. | | **Input name must be unique** | Two Input blocks share the same internal name (usually from copy-paste). | Delete one and re-add it so the builder generates a unique name. | | **Submit button requires a form to exist** / **Reset button requires a form to exist** | A Form Submit or Form Reset Button points at a Form Identifier that does not exist. | Create a form with that identifier or pick an existing form. | | **URL is required** | A URL Button or external Navbar link, or a Submit URL on a JSON / Multipart form, has no URL set. | Fill the missing URL field. | | **You can't use the file input type because the form doesn't submit anything -- it opens a new view with the input values as search parameters.** | A form with file inputs uses **Open view with form data** as its Form Type. | Remove the file input or change **Form Type** to **JSON** or **Multipart/Form-Data**. | ## Testing a Live View Once a save completes, the view is live. To test it the way users see it: - Use **Test mode** inside the builder (the **Test** button in the top bar) to run the view with real records. - Or open the OneClick button in Pipedrive to see exactly what users see. Either way verifies: - Layout and styling. - Data Picker placeholders resolve correctly. - Form submissions work. - View navigation behaves as expected. - Conditional visibility rules behave as expected. ## Main View An interface can contain more than one view. The **main view** is the one that opens when a user clicks the OneClick button in Pipedrive. It is highlighted in the views list with a green border and a **Start** badge (star icon) on the card preview. To change which view is the main view, click the **Settings** button on a view card to open the **Interface Settings** dialog, then turn on the **Default view** switch. Only one view can be the main view at a time -- enabling **Default view** on a different card automatically clears it on the previous main view. Users reach the other views through navigation (Action Buttons, Navbar links, or form submissions). --- # Snapshots Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/views/snapshots.md A snapshot is a copy of all the views and all the variables of one interface. Take a snapshot before a big change. If the change breaks something, restore the snapshot and the interface is back in the state of the snapshot. A snapshot does not hold the OneClick settings of the interface (URL, token, headers, fields, visibility). Open the **Snapshots** tab on the home screen, next to **Views** and **Variables**. Snapshots tab with the Take snapshot button in the top-right and a list of four snapshots, newest first. Two rows named 'Before restore: …' have an Auto badge, 'E2E state A' and 'E2E baseline' have a Manual badge. The 'E2E state A' row shows a truncated description ending in '…'. Each row shows the time and the creator 'Test Zimple', a size such as '4 views · 5 variables', a Restore button, and pencil and trash icons. ## Taking a snapshot 1. Click **Take snapshot**. 2. Optionally type a **Name** and a **Description**. An empty name saves the snapshot as `Snapshot `. 3. Click **Take snapshot** in the dialog. The snapshot holds each view and each variable as a whole: for a view, for example its layout, sample data, data source URL and method, additional data, active flag, default view flag, name and description; for a variable, its key, value, type, resource, confidential flag and creator. Confidential values stay encrypted in the snapshot. The content of a snapshot never changes after you take it. ## The snapshot list The list shows the snapshots of the current interface, newest first. Each row shows: - The **name** and a **Manual** or **Auto** badge. An Auto snapshot is the one a restore takes automatically (see [Undoing a restore](#undoing-a-restore)). - The **description**, truncated to one line. Hover it to see the full text. - The creation time and the user who took the snapshot. - The size, for example `4 views · 5 variables`. - **Restore**, **Edit snapshot** (pencil) and **Delete snapshot** (trash). ## Restoring a snapshot A restore returns all the views and variables of the interface to the state of the snapshot: - Views and variables made after the snapshot are removed. - Views and variables deleted after the snapshot come back, with their original ids. References to a restored view from other views keep working. - Views and variables changed after the snapshot change back. - Confidential variables of other admins stay as they are. See [Variables and snapshot restore](/docs/buttons/interface-button/interface-builder/how-to/data/variables#variables-and-snapshot-restore). 1. Click **Restore** on the snapshot row. A summary card opens above the list, titled **Restoring to <snapshot time>**. 2. Check the counts. For views and for variables, the card shows how many **Will be removed**, **Will be restored** and **Will change back**. A red line lists the views that the restore deletes. If confidential variables of other admins stay as they are, a separate line lists their keys. 3. Click **Continue**, or **Cancel** to close the card without changes. Snapshots tab with the summary card 'Restoring to 2026-09-18 13:04' above the list. The Views column shows Will be removed 1, Will be restored 1, Will change back 3. The Variables column shows Will be removed 2, Will be restored 3, Will change back 1. A red line reads 'Views created after the snapshot are deleted: E2E Delta.' Below are the Continue and Cancel buttons. 4. The dialog **This replaces the current state** opens. Type the name of the interface exactly as shown, with the same upper and lower case letters. 5. Click **Restore now**. **Restore now** stays disabled until the name matches. Click **Back** to return to the summary card. Dialog 'This replaces the current state' over the summary card. The text reads 'Everything in Interface Domain made after 2026-09-18 13:04 is lost. A snapshot "Before restore: E2E state A" is created first, so you can undo this restore.' The field under 'Type Interface Domain to confirm' contains 'Interface Domain', and the Back and Restore now buttons are below it. After the restore, a toast confirms it and the **Views** and **Variables** tabs show the restored data. A restore is all or nothing. If it fails, nothing changes and one of these toasts appears: | Toast | Cause | |---|---| | **Restore failed. No changes were made.** | The restore failed. The summary card stays open, so you can try again. | | **Snapshot no longer exists. No changes were made.** | Somebody deleted the snapshot in another session. The list refreshes. | | **Button no longer exists.** | The interface was deleted. The app returns to the OneClick settings. | ## Undoing a restore Before every restore, a snapshot named `Before restore: ` is taken automatically. It has the **Auto** badge and holds the state that the restore replaced. To undo a restore, restore that Auto snapshot. ## Editing and deleting a snapshot - **Edit snapshot** (pencil) changes the name and the description. The copied views and variables do not change. The name cannot be empty. - **Delete snapshot** (trash) asks for confirmation and then deletes the snapshot permanently. This cannot be undone. Any admin can edit, delete and restore any snapshot of the interface, also Auto snapshots and snapshots taken by other admins. When the interface is deleted, its snapshots are deleted too. --- # Testing a View with Real Data Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/views/testing-a-view.md The builder's **Test** mode renders your view with real data while you are editing it. Use it to verify that placeholders resolve, forms submit correctly, and conditional visibility behaves as expected -- before anyone else opens the view. Interface Builder has no separate publish step. Every edit you make is auto-saved and goes live immediately for anyone who opens the view in Pipedrive, so Test mode is the safest place to experiment. ## Opening Test Mode 1. Open the view in the builder. 2. Click the **Test** button in the top bar (next to **Preview** / **Sample data**). The builder switches to Test mode: a single toolbar runs along the top of the canvas, with the rendered view below it. Test mode for a view containing a Chart block. The toolbar from left to right: a back arrow, the heading Test, a 'Deal #1995' resource button, a '/api/r/antti-fortnox' URL button, a green 'Review received data' button, the Test action button, an 'Automatically update on change' toggle (on), and a green 'Done' status. Below the toolbar a bar chart titled 'test' shows four customers (Acme Corporation Ltd, Nordic Solutions AB, TechVenture GmbH, Greenfield Industries) with their amount values. The back arrow on the left returns to the builder. ## Picking a Pipedrive Record The toolbar shows the active resource as a button labelled ` #` (for example, `Deal #1995`). Click it to open the **Pipedrive resource** dialog and pick a different record. 1. Pick a resource type -- **deal**, **person**, or **organization**. 2. Pick a specific record from the list. 3. Close the dialog. The preview reloads with that record's data. Every Data Picker placeholder bound to a Pipedrive field (for example `{{deal.title}}`) resolves to the real value. A [floating window button](/docs/buttons/interface-button/interface-builder/explanation/floating-window-buttons) has no record to pick, so its Test and Preview toolbars do not show the resource button at all. ## Tweaking the External Data Source If your view has a Data Source URL configured, click the URL button on the toolbar (Link icon, label is the path of the configured URL). The **View parameter** dialog opens and lets you tweak the request without editing the saved view configuration: - **URL path** -- override the path the test calls. - **Query parameters** -- add, edit, or remove key/value pairs. Duplicate keys collapse into a single row whose value reads `(multiple)`. Closing the dialog re-runs the request and re-renders the view. ## Reviewing the Backend Response Click **Review received data** (eye icon, green button) to see the JSON your data source actually returned, along with the HTTP status. Use this when placeholders look empty or wrong -- it tells you whether the backend sent what you expected. The dialog is empty until a backend response arrives -- it never falls back to your saved Sample data. If your view has no data source configured, switch to **Preview** to see how Sample data renders. ## Manual vs Automatic Reload The **Automatically update on change** switch on the right of the toolbar controls when reloads happen. - **On** (default) -- the preview reloads automatically whenever you change the resource, the URL path, or any query parameter. - **Off** -- changes are buffered. Click the **Test** action button to fetch the data and re-render manually. Useful when you are making many small edits. Your preference is stored in browser localStorage (`autoloadEnabled`), so it persists across sessions. ## What Test Mode Is Not - It does **not** gate your edits. There is no publish step -- whatever you have saved in the builder is already what users see. Test mode is just a convenient way to render the same view with real records while you keep editing. - It does **not** replace real end-user validation -- the preview runs in the builder, not in the Pipedrive panel where your users actually see the view. ## Troubleshooting - **Toast `Request timed out. No custom data received.`** -- your Data Source URL backend did not respond within ~20 seconds. Check your backend logs. - **Toast `Data loading failed (status 500)`** -- your Data Source URL returned a non-2xx status. The status code is shown in the toast. - **Placeholders show literal text** -- the data needed to resolve them is missing. Check that you selected a Pipedrive record, or that your Data Source URL returned the fields you expect. Use **Review received data** to confirm what arrived. See [External Data Source](/docs/buttons/interface-button/interface-builder/how-to/data/external-data-source) for configuring the URL that Test mode calls. --- # How to Create a Form Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/forms/creating-a-form.md ## Add the Form 1. Hover the gap between two rows on the canvas (or above the first row). A small `+` button appears. 2. Click `+` to open the **Add row** dialog. 3. Pick **Form** from the layout list. Add row dialog open on top of the empty canvas. The dialog lists six layout options stacked vertically: Full width, Two columns, Three columns, Sidebar left, Sidebar right, and Form. The Form option is at the bottom of the list and is highlighted with a hover state, showing its label and the description 'Form container for input fields'. The dialog closes and two new marker rows appear on the canvas: - **Form Start** — marks the beginning of the form (shown with a left-edge accent and a row label). - **Form End** — marks the end of the form (shown with a left-edge accent and a row label). Builder canvas after adding a form. A blue 'Form Start · Row 1' marker sits at the top with a left-edge accent and a default identifier badge ('Form e592'). A matching 'Form End · Row 2' marker sits below. Between the two markers the empty form area shows the 'Action required: Missing input field' warning card. The Form Settings tab is open in the right sidebar. The **Form** option is hidden in the **Add row** dialog when you are already inside a form — forms cannot be nested. ## Set the Form Identifier 1. Click either the **Form Start** or **Form End** row to open the **Form Settings** tab in the sidebar. 2. Enter a unique name in the **Form Identifier** field — for example, `contact-form`. 3. The identifier appears as a badge next to **Form Start** on the canvas and is used by Submit and Reset buttons to target this form. Form Settings tab open in the right sidebar with the Form Identifier field set to 'contact-form'. Below it are Padding Top, Padding Bottom, Padding Left, and Padding Right inputs (all 0 px). On the canvas, the Form Start row now shows the 'contact-form' identifier as a badge next to the row label. ## Adjust Form Padding (Optional) In the **Form Settings** tab you can set inner padding for the rendered form: - **Padding Top** (px) - **Padding Bottom** (px) - **Padding Left** (px) - **Padding Right** (px) ## Add Rows Inside the Form Hover the area between the Form Start and Form End markers, then click the `+` button that appears to open **Add row**. Pick any layout (Full, Two Column, etc.) — note that the **Form** option is hidden inside an existing form. Rows added in this area become part of the form. ## Place Input Fields Click an empty column inside the form to open **Add block**, then pick **Input**. The dialog only allows the **Input** block when the surrounding row is inside a form. For details on input types and settings, see [Input Field Types](/docs/buttons/interface-button/interface-builder/how-to/forms/input-field-types). ## Validation Warnings While you build, the canvas highlights warnings when the form is incomplete. Each warning includes a quick action button to fix the problem: - **Missing input field** — the form has no input blocks between Form Start and Form End. Add at least one Input block. - **Missing submit button** — no button anywhere in the view targets this form's Form Identifier. Add a Button block, set its **Button Type** to **Form Submit Button**, and pick this form from the **Form** dropdown. Close-up of the 'Missing input field' warning card displayed inside an empty form on the canvas. The card has a yellow dashed border, a document-with-arrow icon at the top, an 'ACTION REQUIRED' label, the heading 'Missing input field', the description 'Your form needs at least one input field for users to enter data.', and an 'Add input' quick-action button. --- # Configuring Form Submission Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/forms/form-submission.md A submit button's settings live in the **Configuration** sub-tab of the Block Settings sidebar. Open them by selecting a **Form Submit Button** on the canvas. Builder view 'Buttons demo' with a Form (Form ktyy) containing an Input and a selected submit Button. The Block Settings sidebar shows the Configuration sub-tab with Name 'Button', Button Type 'Form Submit Button', Form 'Form ktyy', Form Type 'JSON', a Submit URL button with a green check badge, After submission 'Wait for response', Timeout 10, Form State (Disable form after submission off), User Feedback (Show message after submission off), and the Validation Behavior toggles (Show error indicator on submit button and Scroll to first error field) all off. ## Pointing the Button at a Form The **Form** dropdown lists every form on the view (each `Form Start` row). Pick the one this submit button should send. ## Form Type Set **Form Type** to control how data is sent: - **JSON** (default) -- sends form data as a JSON payload. Requires a Submit URL. - **Multipart/Form-Data** -- sends as multipart form data. Use this when the form includes file uploads. Requires a Submit URL. - **Open view with form data** -- passes form data to another view as URL search parameters without making any HTTP request. The Submit URL and After submission settings are hidden in this mode; submission always opens a target view. Full request shapes for each type: [Form Submission Types reference](/docs/buttons/interface-button/interface-builder/reference/data-binding/form-submission-types). ## Submit URL For **JSON** and **Multipart/Form-Data**, click the **Submit URL** button to open the **URL Configuration** dialog. The dialog has three cards: - **Button end-point configuration** -- the End-point URL the form posts to (supports the Data Picker), a **URL Active** toggle, and an **Omit oneclick metadata** switch (turn this on for APIs that reject extra fields like `event_id` or `resource_id`, e.g. Pipedrive API v2). - **Query Parameters** -- key/value pairs appended to the Submit URL. Click **Add Parameter** to add a row; values support the Data Picker. - **Manage Headers** -- custom HTTP headers sent with the request. Click **Add Header** to add a row. Header keys must contain only letters, numbers, and hyphens, cannot start or end with a hyphen, and cannot start with `x-oc-` (reserved for system headers). Header values support the Data Picker, so you can use dynamic values like `{{variable.api_key}}`. :::note[OneClick-level headers are merged in automatically] If the OneClick button this interface is attached to has its **Headers** toggle enabled (configured outside the builder, on Pipedrive's **Edit a Button** page), every header listed there is sent with the form submit request. Use the per-call headers here only for values that differ between forms. See [OneClick-Level Headers](/docs/buttons/interface-button/interface-builder/explanation/architecture#oneclick-level-headers) for the merge order and the reserved `x-oc-*` keys. ::: The Submit URL button shows a method badge (always `POST` for submit buttons) and a green ✓ when a URL is set; it turns red if the Submit URL is missing. ## After Submission For **JSON** and **Multipart/Form-Data**, the **After submission** dropdown picks what happens once the request is sent: ### Select view Navigates the user to another view as soon as the request finishes. - **View ID** -- the target view dropdown. - **Parameters** -- key/value pairs passed to the target view. - **Use input values as search params** -- a design-time hint. When on, the form's inputs are listed under **Expected Parameters from Views** in the target view's URL Configuration dialog. Form input values are forwarded on the navigation regardless of this switch — toggling it off does not remove them from the URL. ### Wait for response Waits for the server to respond, then reacts to what came back. - **Timeout (s)** -- how long to wait, between **10** and **60** seconds (default 10). The fetch is aborted if the response does not arrive in time. - **Form State** > **Disable form after submission** -- when on, the submit button stays disabled after the response returns. Useful when the submit is final and you do not want the user to try again. - **User Feedback** > **Show message after submission** -- when on and the response contains a message, replaces the whole form with an inline alert instead of showing a toast. See the [Post-submit message](#post-submit-message) section below. What you return from the server decides what the user sees next. See [HTTP Response Format](/docs/buttons/interface-button/interface-builder/reference/data-binding/http-response-format) for the response shapes. ## Validation Behavior The **Validation Behavior** group controls how validation errors and submission errors are surfaced before the request is even attempted. Each toggle has a tooltip explaining what it does. | Switch | Effect | |---|---| | **Show error indicator on submit button** | Adds a red border and a tooltip with the error count to the submit button while there are validation errors on the form. A passive hint before the user clicks. | | **Scroll to first error field** | When the user clicks submit on an invalid form, smoothly scrolls and focuses the first invalid field. The strongest way to draw attention to a long form's validation issue. | | **Show error toast on submit** | Pops a toast with the number of invalid fields (for example `3 fields have errors`). The toast does not say *which* fields -- combine it with **Scroll to first error field** to make that obvious. | Combine **Scroll to first error field** with **Show error toast on submit** for the strongest feedback: the toast tells the user there *are* errors, the scroll-plus-focus shows *which* one to fix first. ## Submission Feedback ### While the submit is in flight Once the user clicks submit on a **Wait for response** form, the submit button shows a spinner in place of its label (the label's width is preserved so the layout does not jump) and the whole form switches to a `progress` cursor so the user cannot mistake the state for idle. The submit button and every descendant input stay in that state until the response returns -- on success or error -- or the submission throws. A thrown network or JSON-parse error resets the state so the button never gets stuck. **Select view** forms behave the same way up to the point of navigation; the spinner is visible until the browser leaves the page. ### Backend error response feedback When the backend returns `oneclick_data.error_message` or `oneclick_data.message_view` (see [HTTP Response Format](/docs/buttons/interface-button/interface-builder/reference/data-binding/http-response-format#error-responses)), two things happen: 1. A full-page message view replaces the rendered content with the message's `title` and `message`, plus **Go Back** and **Retry** buttons. `message` can be an array, shown as a bullet list, and `variant` sets the colours and the icon. You can suppress either button by returning `hideRetry: true` or `hideBack: true` on the object. 2. On error responses, an additional toast also appears with the response's top-level `message` (or `Something went wrong` when none was supplied). ### Post-submit message When **After submission** is set to **Wait for response** and the backend returns a message, how it is shown depends on **Show message after submission**: | Show message after submission | Response has `title`? | User sees | |--|--|--| | Off | No | Toast with `message` | | Off | Yes | Toast with `title` as primary text, `message` as description | | On | No | Inline alert replacing the form, `message` only | | On | Yes | Inline alert replacing the form, `title` + `message` | When the inline alert appears, the view smoothly scrolls to it so the user does not miss the new content even if they were at the bottom of a long form. The message and title can include a small amount of inline HTML -- bold, italic, line breaks, links, and inline code. See [Messages & Toasts](/docs/buttons/interface-button/interface-builder/how-to/data/messages-and-toasts) for how to format messages your backend returns. --- # Form Validation Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/forms/form-validation.md ## Required Fields 1. Select an input field inside your form. 2. Toggle **Required** on in the input settings. 3. When enabled, the form cannot be submitted until the user fills in this field. :::caution[Hidden inputs ignore Required] The Required toggle is forced off when the input type is Hidden — there is no way to require a hidden field. ::: ### Required from data Use data when some records need the field and others do not. 1. Click the ⇄ button beside the **Required** label. A Data Picker field replaces the switch. 2. Bind the field to a value, for example {{deal.must_fill}}. 3. The field is required when the value is `true`, `yes` or `1`. Case and surrounding spaces do not matter. Any other value leaves the field optional. This includes an empty value, `no`, `0`, `false` and a value that does not resolve, so an empty Data Picker field shows no warning. The value comes from the view data (Sample data, Received data, variables, System context). It does not read other inputs in the same form. Click ⇄ again to go back to the switch. The switch keeps its earlier position, and the Data Picker value is kept too. **Disabled** has the same choice and follows the same rule. A disabled field sends its **Default Value** when the form is submitted, and its validation (Required, Pattern, bounds) does not run. ## Pattern Validation Use regex patterns to enforce custom input formats: 1. Select a text-based input field (**Text**, **Textarea**, **Email**, **Number**, **URL**, or **Date** type). 2. Enter a regex expression in the **Pattern** field (e.g., `^\d{3}-\d{4}$` for a phone format like `123-4567`). The field accepts a literal regex, or a Data Picker placeholder (e.g. `{{validation_rules.email_pattern}}`) that resolves to one at submit time. 3. Once Pattern has a value, a **Pattern Error** field appears underneath. Set it to override the default error message shown when the input does not match. Pattern Error also supports the Data Picker, so the message can be localised or context-dependent. If no custom error message is set, a default validation error is shown. When the **value** a user submits is itself a Data Picker placeholder (e.g. a prefilled field bound to a template variable), the regex check is skipped -- the resolved value is trusted to be validated by the backend. Builder view 'Pattern Demo' with a Form Start row, a selected Email Input (Text type), a Submit Button row, and a Form End row. The Block Settings sidebar shows the Configuration sub-tab with Pattern set to '^\\d{3}-\\d{4}$' (with a regex101.com helper link beneath it) and the Pattern Error field that appeared in response set to 'Use format 123-4567'. Placeholder, Help text, and Default Value are empty; Required is off. ## Number Min/Max Validation For **Number** type inputs, bound the accepted range: 1. Select a **Number** input field. 2. Set **Min** and/or **Max** to the desired bounds. Both accept either a literal number or a Data Picker placeholder that resolves to one (e.g. `{{user.min_age}}`). 3. Once Min has a value, a **Min Error** field appears; once Max has a value, a **Max Error** field appears. Use these to customise the messages shown when the submitted value falls outside the bounds. Bounds are enforced at submit. If the value is below **Min** or above **Max**, the form does not submit and the error message appears next to the field. Changing the input **Type** away from **Number** clears all four fields (Min, Max, Min Error, Max Error) automatically. ## Built-in Type Validation Certain input types have automatic validation: - **Email** -- validates email address format. - **URL** -- validates URL format. - **Number** -- only accepts numeric input. No extra configuration is needed -- these validate automatically on form submission. ## File Type Limits Set **Accepted file types** on a File input to take only some kinds of file. Write one comma-separated list of extensions and MIME types: ``` .pdf, .docx, image/* ``` - A bare word such as `pdf` reads as `.pdf`. Case does not matter, and extra commas are ignored. - An entry that is neither an extension nor a MIME type, such as `*.pdf` or `image/`, shows an error under the field. - An empty list accepts every file. The file dialog offers only the listed types. The drop zone hint starts with the list, such as `.pdf, .png, image/* · One file · max 10 MB`; after three types it shows `+N more`. While a user drags a file of another type over the drop zone, the zone turns red and reads `File type not accepted (.pdf, .png)`. During a drag the browser shows only the file's MIME type, so the warning needs a MIME type for every entry: it never comes while the list holds an extension whose MIME type the field does not know. A file of another type can still arrive, for example by a drop. It joins the selection, its row turns red, and the form does not submit until the user removes it. The message names the file and the list: ``` File "setup.exe" is not an accepted type (.pdf, .png) ``` This is a check in the browser only. The server does not read the list, so do not rely on it to keep a file type out of your endpoint. ## File Size Limits A file input is guarded in two places -- your own limits in the browser, and the server's budget -- and they fail with different messages. ### 1. Your own limits, in the browser You set up to three limits on the field. Each one has its own message, so the user is told which limit they passed and by how much. The form does not submit until the selection clears all three. **Max File Size (MB)** applies to **each file on its own**, never to the selection added up -- three 5 MB files pass a 10 MB limit. An oversized file also turns its own row in the field red as soon as it is picked, and the message names the file: ``` File "contract.pdf" is 12.4 MB, which exceeds the 10 MB limit ``` **Max Total Size (MB)** applies to the selection added up. Only a field with **Allow multiple files** on has it: ``` The selected files total 12.4 MB, which exceeds the 10 MB limit ``` **Max Number of Files** caps how many files the field takes. It too belongs to a multi-file field alone, and it is the only limit that stops a user attaching hundreds of tiny files: ``` 14 files selected, which exceeds the limit of 10 files ``` The range you may set for the two size limits depends on the surrounding form's **Form Type**: **JSON** forms allow up to **10 MB**, **Multipart/Form-Data** forms allow up to **100 MB**. The count may go up to **25** on JSON forms and **50** on Multipart/Form-Data, and arrives pre-filled with **10**. The label inside Block Settings shows the active ceiling for each, and the size fields arrive pre-filled with it -- lower a number yourself if you want a tighter check. When a selection breaks more than one limit at once, the user reads the file type message first, then the per-file size message, then the count, then the total size. A file of the wrong type must go whatever its size, and the two per-file messages are the ones that name a file, so they say what to drop. ### 2. The submission budget, on the server Setting your own limits low enough does *not* guarantee the submission goes through. The server never sees them; it weighs every file field of the submission together against one budget of its own, so files that each passed check 1 can still be refused as a group. The user gets an error toast naming both numbers, and the form is never sent: ``` The submission carries 12.6 MB of files, more than the 10 MB this form accepts. Send fewer or smaller files. ``` To stay clear of it, keep the whole form's uploads under the budget for its **Form Type**, and move a form that needs more than 10 MB onto **Multipart/Form-Data**. The numbers, the reason they differ, and the one case that fails without this message are in [File Size Limits](/docs/buttons/interface-button/interface-builder/reference/data-binding/form-submission-types#file-size-limits). :::caution[No file inputs in "Open view with form data"] A form whose **Form Type** is **Open view with form data** *cannot* contain a file input -- the builder shows a clear validation error if you try. ::: ## Builder Validation Warnings The builder itself validates form structure and shows **Action required** cards directly on the canvas inside an empty form: - **Missing input field** -- with an **Add input** quick-fix button. Add an input block between the `Form Start` and `Form End` rows. - **Missing submit button** -- with an **Add submit button** quick-fix button. Add a button anywhere in the view, set **Button Type** to **Form Submit Button**, and select this form in the **Form** dropdown. Each card includes a one-click action button that drops the missing block in the right place. An 'Action required' card on the canvas. The card has an amber file-input icon, the heading 'Missing input field', the body text 'Your form needs at least one input field for users to enter data.', and an 'Add input' quick-fix button at the bottom. Other validation rules block save until they are resolved -- see [Saving](/docs/buttons/interface-button/interface-builder/how-to/views/publishing) for the full list (duplicate input names, submit/reset buttons that point at a non-existent form, file inputs in `Open view with form data` forms, missing URLs). ## Unique Input Names Each input has a **Name** field (the first row in Block Settings) that becomes the field key when the form is submitted. The builder generates an initial name like `Input` and appends a numeric suffix on duplicates -- a second input becomes `Input_2`, a third becomes `Input_3`, and so on. You can rename inputs from the **Name** field whenever you want to make the submitted JSON more readable. :::caution[Input names must be unique] If two inputs end up sharing a name (typically by manual editing), the builder flags an `Input name must be unique` validation error and blocks save until you change one. ::: --- # Input Field Types and Configuration Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/forms/input-field-types.md ## Adding an Input Field 1. Make sure you have a row inside a form. If you do not, see [Creating a Form](/docs/buttons/interface-button/interface-builder/how-to/forms/creating-a-form) first. 2. Click an empty column inside that row to open the **Add block** dialog. 3. Pick **Input** from the list. (The **Input** entry is only enabled when the row sits between a `Form Start` and a `Form End`.) 4. Click the new block to open its settings in the sidebar. 5. Choose the input **Type** from the dropdown. Builder view 'Input Block Demo' with a Form Start row, an Email Input block (Text type) selected on the canvas, a Submit Button row, and a Form End row. The Block Settings sidebar shows the Configuration sub-tab populated: Name 'Input', Label 'Email', Type 'Text', empty Placeholder / Help text / Pattern / Default Value fields, Required toggled on, and Disabled off. --- ## Basic Types - **Text** -- standard single-line text input. - **Textarea** -- multi-line text input. - **Email** -- text input with email format validation. - **Number** -- numeric-only input. - **URL** -- text input with URL format validation. - **Date** -- date picker. - **Hidden** -- invisible field, useful for passing data without user interaction. Hidden inputs can never be **Required** or **Disabled**: a change to Hidden turns both switches off and sets both settings back to a switch. - **File** -- file upload field. See [File Input](#file-input) below for the form-type rules. ### Textarea Input For **Textarea** type inputs, configure: - **Rows** -- the number of visible text rows (1--20, default 3). - **Max Length** -- the maximum number of characters the user can enter. Leave blank for no limit. ### File Input The rendered field is a row that reads **Drop a file here** (or **Drop files here**), with a **Browse** button on the right. The user either drops files onto the row or clicks anywhere on it to open the file dialog. Under the title, a hint lists the limits you set, such as `One file · max 10 MB` -- a limit you leave empty is left out of the hint. A dropped file goes through the same checks as a picked one. A rendered form field labelled 'Attachment' with no file selected. Under the label sits a bordered row: on the left a grey tile with an upload icon, in the middle the title 'Drop a file here' and under it the grey hint 'One file · max 10 MB', and on the right an outline 'Browse' button. No validation message is shown. A single-file input refuses a drop of several files at once: the row turns red and reads **Only one file allowed. Drop a single file.** as soon as the files are dragged over it, and a drop selects nothing. Once a file is selected, the row is hidden; the user removes the file with **X** to choose another. For **File** type inputs: - The maximum upload size is **Max File Size (MB)**. It applies to **one file at a time**, not to the selection as a whole. The allowed range depends on the surrounding form's **Form Type**: **JSON** forms allow up to **10 MB**, **Multipart/Form-Data** forms allow up to **100 MB**. The label inside Block Settings shows the active limit, and the field arrives pre-filled with it -- lower the number yourself if you want a tighter check. Switching the form type lowers a value that is too high for the new type, but never raises one you set yourself. - **Accepted file types** limits the field to the kinds of file you list, such as `.pdf, .png, image/*`. Leave it empty to accept every file. The file dialog offers only the listed types. A file of another type still joins the selection, but its row turns red and the form does not submit until the user removes it. See [File Type Limits](/docs/buttons/interface-button/interface-builder/how-to/forms/form-validation#file-type-limits). - A form whose **Form Type** is **Open view with form data** *cannot* contain a file input -- that mode forwards values as URL search parameters and cannot carry files. The builder shows a clear error if you try. #### Accepting several files Turn **Allow multiple files** on to let one field carry more than one file. The setting appears on the **File** type only and is off by default. The field then behaves like this: 1. The row reads **Drop files here**, its hint shows the limits (`Up to 10 files · 100 MB total · 10 MB each`), and the file dialog lets the user select several at once. 2. Each selected file gets a row showing its name and size. When **Max File Size (MB)** is set, the row shows `size / limit`, and a file over the limit turns red. A file that is not one of the **Accepted file types** turns red too. 3. Under the rows, a running summary reads `3 files · 12.4 MB / 100 MB` -- the count, the size of the selection so far, and the total-size limit when one is set. It turns red as soon as the selection breaks **Max Number of Files** or **Max Total Size (MB)**; a file that is too large or of another type turns its own row red instead. 4. The **X** on a row removes that one file; the rest stay selected. 5. Under the summary, a slimmer row reads **Add files** -- dropping or picking again *adds* to the selection instead of replacing it. A file that is already in the list is skipped. A rendered form field labelled 'Attachments' with three files selected. Each file sits on its own bordered row with a document icon, the file name (quarterly-report.pdf, signed-contract.pdf, site-photo.jpg) and, underneath, its size against the limit (208.98 KB / 10 MB, 86.91 KB / 10 MB, 402.34 KB / 10 MB). Every row has an X button on the right. Below the three rows, small grey text reads '3 files · 698.23 KB / 10 MB', and under that a slim bordered row with a plus icon tile, the title 'Add files' and an outline 'Browse' button on the right. No row is red, the summary is grey rather than red, and no validation message is shown. **Which limits to set.** A multi-file field has three: | Setting | Set it to | |---|---| | **Max File Size (MB)** | The largest single file the endpoint can handle. | | **Max Total Size (MB)** | What the endpoint can take in one request. Keep it at or under the budget for the form type, or the server refuses the submission even though the field accepted it. | | **Max Number of Files** | How many attachments the field is for. Pre-filled with 10; the highest you may set is 25 on JSON forms and 50 on Multipart/Form-Data. | Each limit has its own message, so the user is told which one they passed rather than being left to guess. Put a form meant for several sizeable files on **Multipart/Form-Data**. See [File Size Limits](/docs/buttons/interface-button/interface-builder/reference/data-binding/form-submission-types#file-size-limits). **Before you turn it on for a live field:** the setting changes what the endpoint receives, so update the integration first. See [File Fields](/docs/buttons/interface-button/interface-builder/reference/data-binding/form-submission-types#file-fields). --- ## Selection Types Selection inputs let users choose from a list of options: - **Checkbox** -- multiple selections with checkboxes. - **Radio** -- single selection with radio buttons. - **Single Select** -- dropdown for a single selection. - **Multi Select** -- dropdown for multiple selections. Each selection type has an **Options Type** dropdown with two values: **Static** or **Dynamic**. ### Static Options 1. Set **Options Type** to **Static**. 2. Click **Manage options** to open the editor and add rows. Each row has: - **Label** -- text shown to the user. Required. - **Value** -- value submitted when this option is selected. Required. 3. Use the editor's **Add Option** button to append rows; click **Save Options** to commit. Both Label and Value must be at least 1 character long. ### Dynamic Options 1. Set **Options Type** to **Dynamic**. 2. Fill the fields: - **Labels Delimiter** -- character used to split the resolved labels string. Default: `,`. - **Values Delimiter** -- character used to split the resolved values string. Default: `,`. - **Labels** -- Data Picker expression that resolves to the option labels. - **Values** -- Data Picker expression that resolves to the option values. A warning banner inside Block Settings reminds you that if your data contains the delimiter character, the options may be split incorrectly. --- ## Default Values Use the **Default Value** field to pre-fill the input. The field supports the Data Picker, so you can bind the default to any resource field or variable. Help text under the field changes per Type to describe what is expected (for example `YYYY-MM-DD format` for Date, `Coerced to a number` for Number). For selection inputs with **Static** options, the **Default Value** field gains a small swap button next to its label. The button toggles between two modes: - A **dropdown** of the static options (the selection's stored value is the option's `value`). - A **plain-text input** that supports template variables -- type the option's `value` directly, optionally as a Data Picker expression. For multi-value selections (Checkbox / Multi Select) separate values with commas. ## Labels and Help Text - **Label** -- text label displayed above the input field. - **Help text** -- smaller hint text shown below the input. Supports the Data Picker. - **Placeholder** -- hint text shown inside the empty input. Available on **Text**, **Textarea**, **Email**, **Number**, **URL**, **Single Select**, and **Multi Select** only -- Checkbox, Radio, Date, File, and Hidden inputs hide the Placeholder field. Supports the Data Picker. ## Validation Settings - **Required** -- toggle to make the field mandatory. Click the ⇄ button beside the label to take the value from data instead: see [Required from data](/docs/buttons/interface-button/interface-builder/how-to/forms/form-validation#required-from-data). Hidden inputs cannot be Required. - **Pattern** -- regex pattern for custom validation. Available on Text, Textarea, Email, Number, URL, and Date. Must be a valid regular expression. - **Pattern Error** -- custom error message shown when pattern validation fails. Only appears once Pattern has a value. - **Disabled** -- toggle to make the field read-only. A disabled field sends its **Default Value** and skips its validation. Click the ⇄ button beside the label to take the value from data instead; the same `true` / `yes` / `1` rule applies as for Required. Hidden inputs cannot be Disabled. For numeric bounds (**Min**, **Max**, **Min Error**, **Max Error**) and file size limits, see [Form Validation](/docs/buttons/interface-button/interface-builder/how-to/forms/form-validation). ## Style and Visibility The Input block uses the standard **Style** sub-tab (background, font, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](/docs/buttons/interface-button/interface-builder/how-to/layout/block-styles) and [Conditional Visibility](/docs/buttons/interface-button/interface-builder/how-to/visibility/conditional-visibility). --- # Using the Data Picker Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/data/data-picker.md This guide covers the everyday picker workflow. For the full breakdown of every tab, type filter, and badge — see the [Data Picker reference](/docs/buttons/interface-button/interface-builder/reference/data-binding/data-picker). ## Inserting Your First Placeholder 1. Click into any block setting that supports the Data Picker — for example a Title block's **Text** field. 2. The picker opens as a tooltip beside the field. 3. Pick the tab whose data you want (Deal, Organization, Person, User, Custom, Search Params, Variable, Functions, Context, or — inside a looping area — Loop item). 4. Click a field in the tree. A blue badge appears in the field as a single unit; the placeholder it represents (for example `{{deal.title}}`) is what gets resolved at render time. On a [floating window button](/docs/buttons/interface-button/interface-builder/explanation/floating-window-buttons) the **Deal**, **Organization** and **Person** tabs are not in the strip at all, because that button's views get no Pipedrive record. Builder view 'Data Picker Demo' with a Title block selected. The Block Settings sidebar's Text field shows a single blue 'Title' badge with a small × delete icon. The Data Picker tooltip is open beside the Block Settings panel: the Deal tab is selected (the dollar-sign tab) and the field tree below shows ID, Title, Creator (with an expand chevron), Value, Contact person, Organisation, Stage, Currency, Add time, Update time, Status, Probability. ## Combining Static Text and Placeholders You can mix plain text with badges in the same field. Type freely before, between, and after badges — the picker treats text as text and badges as atomic units. A typical Paragraph **Value** might read: ``` Deal: {{deal.title}} — {{deal.value}} {{deal.currency}} ``` At render time the three placeholders resolve to live values from the deal record (for example `Deal: Legendary 1995 — 3193 EUR`). ## Removing a Placeholder Three ways: - Click the small **×** on the badge. - Place the cursor after the badge and press **Backspace** — the whole badge disappears in one keystroke. - Select across the badge and type — the badge is replaced by whatever you type. ## Editing Complex Expressions in the Larger Dialog Once a field has more than one or two placeholders — or when you start mixing in functions like `if`, `formatCurrency`, or `daysBetween` — the inline picker gets cramped. Click the **expand** icon at the right edge of the Data Picker input to open the same field in a larger dialog. Toggle **Show result** to preview the rendered value (resolved against the active sample data) and **Show whitespace** to make spaces visible. For the **HTML** block specifically, **Show result** renders the compiled output as actual HTML (using the same sanitiser as the live view) so you can see the visual result without switching to Preview mode — see [How to Use the HTML Block](/docs/buttons/interface-button/interface-builder/how-to/blocks/html#previewing-without-leaving-the-dialog). Expand dialog open over the builder canvas. The dialog header reads 'Text' with a minimize icon top-right. A large Slate editor in the centre holds three placeholder badges separated by an em-dash and a space — Title, Value, Currency. Below it the Show result switch is on (showing the rendered preview 'Legendary 1995 — 3193 EUR' beneath the editor) and the Show whitespace switch is off. The Data Picker tooltip floats to the left of the dialog with the Deal tab selected. The dialog ignores clicks outside, so you can keep clicking around the canvas without losing your edits — only the minimize icon (top right) closes it. **Show whitespace** is useful when something looks "off" in the rendered output and you suspect a stray or missing space — for example a placeholder that touches the next word, or two spaces between values. Switch the toggle on to see every space in the field as a small dot. The toggle is a **global** preference that applies to every Data Picker field in the builder and is remembered across reloads, unlike **Show result** which is set per field. Expand dialog with the Show whitespace toggle on. The field contains plain text and small dot markers between every word, visualising each space character. Show result is also on; the resolved text appears below the editor. ## Working Inside a Looping Area When the field is inside an [area with looping enabled](/docs/buttons/interface-button/interface-builder/how-to/layout/areas#looping-an-area), the picker grows an extra **Loop item** tab (a repeat icon). Open it to: - pick a field of the current iteration's array item (the `index` field is shown last in the list) — placeholders resolve per repetition, so `{{deal.products.name}}` reads a different product on each loop; - pick `index` — the iteration number, starting at **1**. If the field is **not** inside a looping area, the Loop item tab does not appear. ## Type-Filtered Contexts Some block settings only accept a specific data type. The picker greys out fields that do not match: - **Table > Target Array** and **Area > Loop > Target array** accept only arrays. - **Visibility > Condition** accepts any value but is most useful with strings or booleans. - Most text-based settings exclude objects from the clickable set — clicking an object's badge only expands its children. You do not choose the filter manually — the surrounding setting decides it for you. ## Reusing the Last-Opened Tab The picker remembers which tab you opened last across fields. If you spend a session inserting Deal fields, the next picker you open also lands on the Deal tab. Switch tabs once and that becomes the new default. Useful when you are building a row of similar inputs. --- # Configuring an External Data Source Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/data/external-data-source.md ## Opening the URL Configuration Dialog 1. Open the **View settings** tab in the right panel. 2. Click the **Configure URL** button (next to **View URL**, with the active method shown as a `POST` / `GET` badge). The **URL Configuration** dialog opens. URL Configuration dialog open over the View URL demo view. The View end-point configuration card shows HTTP Method tabs (GET / POST, POST selected), an empty End-point URL field, the URL Active switch turned on, and the Omit oneclick metadata switch turned off. The Query Parameters card below has an Add Parameter button on the right and an empty state showing 'No query parameters configured' with an Add Your First Parameter button. The dialog is divided into cards, in this order: **View end-point configuration**, **Query Parameters**, and **Manage Headers**. Click **Save** in the top-right to apply changes, or **Cancel** to discard them. ## HTTP Method In the **View end-point configuration** card, pick **GET** or **POST** with the toggle buttons next to **HTTP Method** (default: **GET**). - **POST** -- sends a request body with deal/person/organization context. - **GET** -- appends parameters to the URL. ## End-point URL Enter the full URL of the external API endpoint in the **End-point URL** field. This is the URL the view calls to fetch data when it opens. The field supports the Data Picker, so you can build the URL from variables. ## URL Active Turn on the **URL Active** switch to enable the external data source. The helper text reads _"When disabled, no fetch will be made on view load."_ When off, no request is made and the **Custom** tab in the Data Picker remains empty. ## Omit oneclick metadata The **Omit oneclick metadata** switch tells Interface Builder not to add `event_id`, `resource_id`, or other OC-specific fields to the request body. Turn this on for APIs that reject unknown fields, such as the Pipedrive API v2. ## Query Parameters In the **Query Parameters** card, click **Add Parameter** (or **Add Your First Parameter** when the list is empty) to append a row. - Each row has a **Key** input and a **Value** input. Values support the Data Picker. - The **Trash** icon at the end of the row removes that parameter. - Keys must be 1--255 characters, values 1--512 characters. Duplicate keys are flagged with `Duplicate key not allowed`. ## Manage Headers In the **Manage Headers** card, click **Add Header** (the empty state shows _"No headers configured yet"_). Each header has: - **Key** -- the header name. Must contain only letters, numbers, and hyphens, cannot start or end with a hyphen, and cannot start with `x-oc-` (reserved for system headers). - **Value** -- the header value. Supports the Data Picker, so you can use dynamic values such as `{{variable.api_key}}`. :::note[OneClick-level headers are merged in automatically] If the OneClick button this interface is attached to has its **Headers** toggle enabled (configured outside the builder, on Pipedrive's **Edit a Button** page), every header listed there is sent with this request. You only need to set per-call headers here for values that differ between requests. See [OneClick-Level Headers](/docs/buttons/interface-button/interface-builder/explanation/architecture#oneclick-level-headers) for the merge order and the reserved `x-oc-*` keys. ::: ## Using the Data Once the URL is active, the external API response fields appear in the Data Picker under the **Custom** tab. 1. Open any Data Picker field. 2. Switch to the **Custom** tab. 3. Browse the response fields and click to insert chips that compile to placeholders like `{{custom.field_name}}`. The data is fetched at render time using the configured method, headers, and parameters. The response is parsed and made available as selectable fields. ## How the Response Reaches the View When the view opens, the builder calls your data source URL and then waits for your response. The view stays in a loading state until the response arrives, and renders as soon as it does. The total wait is capped at roughly **20 seconds**. If nothing arrives in that window, the user sees a `Request timed out. No custom data received.` toast. If the data source URL returns an HTTP status outside 2xx, the user sees `Data loading failed (status 500)` (or whichever status came back). For the exact request shape your endpoint receives — body, headers, system metadata — see the [View Data Source reference](/docs/buttons/interface-button/interface-builder/reference/data-binding/view-data-source). For the parallel-fetch state machine and the differences between Test, Preview, and live render, see [External Data Flow](/docs/buttons/interface-button/interface-builder/explanation/external-data-flow). ## Responding with a Message View Sometimes the "data" you have for the user is a message, not records -- the record cannot be found, the session expired, or a step is still missing. Return a message-view response instead of real data: ```json { "oneclick_data": { "error_message": { "title": "Account not found", "message": "We could not find that account. Choose another." } } } ``` The view shows a full-page message view with your title and message, plus **Go Back** and **Retry** buttons. Use this instead of a toast when the user cannot proceed -- they cannot miss a full-page card. The object form also accepts optional `hideRetry: true` and `hideBack: true` flags to hide the corresponding button. Full-page message view in the destructive variant: a light red card with a red circle-alert icon, the title Account not found, the message We could not find that account. Choose another., and the buttons Go Back (outlined) and Retry (solid red). If you only need a single-line message, use the string form. It gets the title "Error": ```json { "oneclick_data": { "error_message": "Something went wrong" } } ``` ### Lists and variants To list several items, send `message` as an array of strings. The message view shows them as a bullet list. Add `variant` to change the colours and icon -- `destructive` (default), `warning`, `info`, `success` or `default`: ```json { "oneclick_data": { "error_message": { "title": "A few things before we continue", "message": ["Add a delivery address", "Choose payment terms"], "variant": "info" } } } ``` Full-page message view in the info variant: a light blue card with a blue info icon, the title A few things before we continue, a bullet list with Add a delivery address and Choose payment terms, and the buttons Go Back (outlined) and Retry (solid blue). ### `message_view` for messages that are not errors When the message is not an error -- for example a `success` or `info` note -- send it as `message_view` instead of `error_message`. The fields and the view are the same; only the name is neutral. `message_view` takes the object form only: ```json { "oneclick_data": { "message_view": { "title": "Almost there", "message": "Customer created. Add a contact person and press Retry.", "variant": "success" } } } ``` Full-page message view in the success variant: a light green card with a green circle-check icon, the title Almost there, the message Customer created. Add a contact person and press Retry., and the buttons Go Back (outlined) and Retry (solid green). - `variant` changes the look only. The buttons stay **Go Back** and **Retry**, and the response is still not a success response. - A missing `variant` is `destructive`, as with `error_message`. - If a response carries both fields, `error_message` wins and `message_view` is ignored. Both fields support a small HTML subset in the message text. See the [Messages & Toasts reference](/docs/buttons/interface-button/interface-builder/reference/data-binding/messaging) for the allowed tags and link behaviour, and [HTTP Response Format → `message_view`](/docs/buttons/interface-button/interface-builder/reference/data-binding/http-response-format#message_view) for all rules. ## Responding with a Redirect If the data source should divert the user to another view instead of rendering, return a redirect: ```json { "oneclick_data": { "redirect_view": { "id": "target-view-id", "params": { "deal_id": "123" } } } } ``` The view shows a "Redirecting..." toast and navigates to the target view. If the target ID does not exist, the view falls back to a full-page message view with the message _"View with ID ... was not found"_. See [HTTP Response Format](/docs/buttons/interface-button/interface-builder/reference/data-binding/http-response-format) for the full list of accepted shapes. --- # Sending Messages and Toasts from Your Backend Source: https://help.theoneclick.io/docs/buttons/interface-button/interface-builder/how-to/data/messages-and-toasts.md Interface Builder shows user-visible messages in three places: 1. **Toast** — a short notification that pops up in a corner of the view. 2. **Inline alert** — a coloured box that replaces the form after submission. 3. **Full-page message view** — takes over the view and offers Retry / Go Back buttons. You decide which one appears by combining the button's settings with the shape of the response your API returns. ## Do I need `oneclick_data`? No — not for a plain toast. **A toast can come from several simpler shapes**; the `oneclick_data` envelope is only required when you want: - a **redirect** (navigate the user to another view) on a URL button or a form submit, or - a **full-page message view** (on a view data source or on a form submission error). For a plain toast — success or error — a top-level response with a `message` is enough. For URL buttons, even a plain text body (not JSON) works. ## Two-minute recipes Pick the row that matches your situation. | I want… | Button setup | Return from API | |---|---|---| | A success toast after form submit | Form Submit, **After submission = Wait for response** | `{ "message": "Saved." }` | | A coloured toast with a title | same | `{ "message": "Profile is up to date.", "title": "Saved", "variant": "success" }` | | Replace the form with a "thank you" screen | same + **Show message after submission** ON | same shape as above | | Navigate to another view after submit | Form Submit, **After submission = Wait for response** | `{ "view_id": "receipt-view" }` | | Show a toast, then navigate | same | `{ "oneclick_data": { "message": "Done.", "redirect_view": { "id": "receipt-view" } } }` | | Error toast on failed submit | same + **non-2xx** HTTP status | `{ "message": "Email already in use." }` | | Full-page error after failed submit (view with a data source) | same + **non-2xx** HTTP status | `{ "oneclick_data": { "error_message": { "title": "Blocked", "message": "…" } } }` | | Quick toast after URL button click | URL Button | plain string body: `"Added to cart"` — **or** `{ "message": "Added to cart" }` | | Redirect after URL button click | URL Button | `{ "oneclick_data": { "redirect_view": { "id": "next" } } }` | | Toast then redirect after URL button click | URL Button + **Wait page transition** ON | Stream interim toasts via the polling endpoint, then return `{ "oneclick_data": { "redirect_view": { "id": "next" } } }`. URL buttons drop a sibling `message` next to `redirect_view`. | | Full-page error on view data source | View with a data source | `{ "oneclick_data": { "error_message": { "title": "…", "message": "…" } } }` | The rest of the page explains each case in detail. --- ## Form submit responses For form submits the submit button's **After submission** setting decides what the builder does with your response. ### After submission = Wait for response All the shapes below are accepted. Return the simplest one that fits. **Just a toast** — return a JSON body: ```json { "message": "Profile saved" } ``` **Coloured toast** — add a variant: ```json { "message": "Profile saved", "variant": "success" } ``` `variant` can be `default`, `destructive`, `info`, `success`, or `warning`. **Toast with a title** — add a title: ```json { "message": "Profile is up to date.", "title": "Saved", "variant": "success" } ``` - With **Show message after submission** off → shown as a toast where `title` is the bold first line and `message` is the description. - With **Show message after submission** on → the form is replaced by an inline alert containing the title and message. The view scrolls to it automatically. **Just a navigation** — no message, just send the user to another view: ```json { "view_id": "target-view" } ``` **Toast plus navigation** — return the `oneclick_data` envelope. This is the only shape that carries both: ```json { "oneclick_data": { "message": "Saved.", "redirect_view": { "id": "receipt", "params": { "order_id": "4321" } } } } ``` ### After submission = Select view The button navigates on its own once the server replies. You usually need no body at all — HTTP 2xx is enough. If you want a toast to flash just before the navigation, return one of these: ```json { "message": "Saved." } ``` ```json { "success": "Saved." } ``` ```json { "oneclick_data": { "message": "Saved." } } ``` All three produce a success toast and then the navigation. ### Submit errors Return any non-2xx HTTP status. The accepted bodies are: | Body | What the user sees | |---|---| | `{ "message": "…" }` | Error toast with the message | | `{ "oneclick_data": { "message": "…" } }` | Error toast with the message, plus a trailing "Something went wrong" toast (the body has no top-level `message`, so the unconditional fallback toast also fires) | | `{ "oneclick_data": { "message": "…", "redirect_view": {…} } }` | Error toast, then navigation | | `{ "oneclick_data": { "error_message": "…" } }` | Full-page message view replaces the view, plus a trailing "Something went wrong" toast in the corner | | `{ "oneclick_data": { "error_message": { "title": "…", "message": "…", "hideRetry": false, "hideBack": false } } }` | Full-page message view with your title and message, plus a trailing "Something went wrong" toast in the corner | | Anything else | Generic "Something went wrong" toast | The submit button re-enables on error unless you turned on **Disable form after submission**. --- ## URL button responses URL buttons accept any of these. Two of the shapes only render their toast when **Wait page transition** is enabled on the button — see [URL button quirks](#url-button-quirks) below. **A plain text body** (not JSON) — shortest path: ``` "Added to cart" ``` Shown as a success toast. You may include inline HTML inside the string (see [HTML support](#html-support)). **JSON with a top-level `message`** — still no envelope needed: ```json { "message": "Added to cart" } ``` Also shown as a success toast. **Envelope with a message**: ```json { "oneclick_data": { "message": "Added to cart" } } ``` Renders a success toast **only when Wait page transition is on**. If the button does not use Wait page transition (the default), this body is silently dropped — the user sees no toast. Prefer the top-level `{ "message": "…" }` shape for plain toasts and reach for the envelope only when you also need a redirect or are already streaming interim updates through the polling endpoint. **Envelope with a redirect** — the envelope is *required* for this: ```json { "oneclick_data": { "redirect_view": { "id": "receipt-view", "params": { "order_id": "4321" } } } } ``` Silent navigation. **Envelope with both** — only the redirect runs: ```json { "oneclick_data": { "message": "Payment successful", "redirect_view": { "id": "receipt-view" } } } ``` URL buttons navigate as soon as a `redirect_view` is present and **silently drop** the sibling `message`. To show a message and then navigate, enable **Wait page transition** on the button and stream the toast through the polling endpoint before returning the final response with `redirect_view`. (Form submits behave differently — they show both the toast and then navigate; see [Form submit responses](#form-submit-responses).) **Errors**: any non-2xx status becomes an error toast. The message comes from the body if it is a plain string or a `{ "message": "…" }` object; otherwise the generic failure message is shown. The button re-enables so the user can try again. ### URL button quirks URL buttons handle the response in two stages: an immediate handler for the very first response, plus an optional polling loop that runs only when **Wait page transition** is on. Because of that split, the envelope `{ "oneclick_data": { "message": "…" } }` only surfaces in the polling-aware path: - **Wait page transition off** (the default): only the immediate handler runs. Plain string bodies and top-level `{ "message": "…" }` produce a toast; envelope-only `oneclick_data.message` is silently dropped. - **Wait page transition on**: the button polls for interim updates (each one becomes a `toast.info`) and at the end shows the final response's `oneclick_data.message` as a `toast.success`. If your final (immediate) response carries both a `message` and a `redirect_view`, the message is dropped — only the redirect runs. Polled responses can carry both, in which case the polled message still shows as `toast.info` just before the redirect. URL buttons never render `title` or `variant` — the toast is always a success toast (or, on errors, an error toast). Those fields only take effect on form submits. --- ## View data source error When a view has a data source URL, the response fills the Data Picker's Custom tab. If you need to show an error instead of data — for example "Account not found" — return this shape (and the envelope **is** required): ```json { "oneclick_data": { "error_message": { "title": "Account not found", "message": "We could not find that account. Choose another." } } } ``` The view shows a full-page message view with your title and message plus **Retry** and **Go Back** buttons. Add `"hideRetry": true` or `"hideBack": true` to hide either button. Full-page message view in the destructive variant: a light red card with a red circle-alert icon, the title Account not found, the message We could not find that account. Choose another., and the buttons Go Back (outlined) and Retry (solid red). To list several things the user must fix, send `message` as an array of strings. The message view shows them as a bullet list. Add `variant` to change the colours and icon of the message view — `destructive` (default), `warning`, `info`, `success` or `default`: ```json { "oneclick_data": { "error_message": { "title": "A few things before we continue", "message": ["Add a delivery address", "Choose payment terms"], "variant": "info" } } } ``` `variant` changes the look only. The buttons stay **Go Back** and **Retry**, and the response still counts as an error. Full-page message view in the info variant: a light blue card with a blue info icon, the title A few things before we continue, a bullet list with Add a delivery address and Choose payment terms, and the buttons Go Back (outlined) and Retry (solid blue). When the message view is not an error, send it as `message_view` instead of `error_message`. The fields and the view are the same; the name just reads better for a `success` or `info` note. `message_view` takes the object form only: ```json { "oneclick_data": { "message_view": { "title": "Almost there", "message": "Customer created. Add a contact person and press Retry.", "variant": "success" } } } ``` Full-page message view in the success variant: a light green card with a green circle-check icon, the title Almost there, the message Customer created. Add a contact person and press Retry., and the buttons Go Back (outlined) and Retry (solid green). If you only need a single-line message, the string form also works: ```json { "oneclick_data": { "error_message": "Something went wrong" } } ``` The same message view also appears when a form submit on this view returns `oneclick_data.error_message` or `oneclick_data.message_view`. --- ## title and variant belong at the top level :::caution[Common mistake] The `oneclick_data` envelope **does not carry `title` or `variant`** — its allowed fields are only `message`, `redirect_view`, `error_message`, `message_view`, and `event_id`. Putting `title` or `variant` inside `oneclick_data` is silently ignored. (The `variant` inside the `error_message` or `message_view` object is a different field: it sets the look of the full-page message view.) ::: If you write: ```json { "oneclick_data": { "message": "Done", "title": "Saved", "variant": "success" } } ``` the `title` and `variant` are silently ignored. Put them at the top level instead: ```json { "message": "Done", "title": "Saved", "variant": "success" } ``` :::caution[URL-button toasts ignore title and variant] This top-level shape is only read on form submits with **Wait for response**. URL buttons do not support titles or variants — the toast always renders as a success toast regardless. ::: --- ## HTML support Every `message` and `title` — whether at the top level or inside `oneclick_data` — passes through a narrow HTML allowlist before rendering. You can use a small subset: ``` / bold / italic underline
line break inline monospace link (opens in a new tab)

paragraph

generic wrapper