Messaging
Don't forget to check out our Make and Zapier Messaging examples once you've read this article!
This feature is not available for Link buttons
OneClick can listen for messages from your automation once the button has been triggered. For example you can communicate back to the users if something did not work, or if your automation was completed successfully. You can send multiple messages to the same button click event so you can keep your users updated about the progress of your automation.
Messages can be in form of HTTP status responses or custom messages sent to the OneClick message end-point. The messaging process works as described below, read more about the details later in this article:
In order to use messaging you need to enable the feature in your button settings:
Message types
Messages can be type of info, success, warning or error. Adding a proper message type helps to make the message log in the application panel more understandable and also enables to configure the button behavior in case of an error. Read more how to use message types later in this article.
HTTP status response messages
When the messaging feature has been enabled in your button settings it will by default listen and log any HTTP responses your end-point / webhook sends. If you do not want to listen for HTTP responses but only use custom messages please read this.
Please note that HTTP responses and custom messages can be used together and don't rule each other out
Status codes
By default any HTTP response with a status code of 20x will be regarded as an info message, and all others as errors. If you format your response correctly you can change the message type as long as the status code is 20x (read more below)
Message format
Plain text HTTP responses
If you add plain text (string) to your HTTP response it will show up as your message content in the message log view.
Formatted HTTP responses
If you format your HTTP response as JSON you can change the message type, as long as the status code is 20x. As an example:
{
"message_type": "success",
"message": "Scenario completed"
}The message_type property defines the type of the message, and the message property will be your message content.
Empty HTTP responses
If an empty response is sent the message content will be "Success" in case of status code 20x and "Error" in case of any other status code.
Custom messages
Custom messages work differently from the standard HTTP response method. Custom message process is asynchronous, which allows for example multiple messages to be sent back to the same button and button click event. Also, some platforms (e.g. Zapier) do not allow using custom HTTP responses, in which case custom messages are required.
Please note that custom messages and HTTP responses can be used together and don't rule each other out.
You can send up to 10 custom messages for the same button click event. This is convenient if you want to keep the user updated on the progress of your automation
Messaging end-point
A custom message needs to be sent as an HTTP POST call to the OneClick messaging end-point:
https://app.theoneclick.io/api/trigger-messageMessage window and event ID
When a button with messaging enabled is clicked an event window is opened. The event window is open for 45 seconds in which time messages need to be delivered to the messaging end-point.
If you try to send a message to the messaging end-point outside the event window you will get an HTTP error with status 400: "Not found or the event window is expired"
Also when messaging is enabled for a button an additional event_id property will be added to the button HTTP POST payload. This is needed in your custom message to identify the unique click that happened so the message can be delivered to the right button, Pipedrive object and user:
{
"identifier": "6b4df289-2df2-4009-8517-29d292f433f5",
"resource": "deal",
"view": "details",
"userId": "1108047",
"companyId": "737569",
"selectedIds": "21389",
"fields": null,
"event_id": "d3cc3758-41d3-4eba-bb80-894734f5fa20"
}Message format
Custom messages are sent as HTTP POST calls to the messaging end-point with JSON payload, as an example:
{
"event_id": "d3cc3758-41d3-4eba-bb80-894734f5fa20",
"message": "You succeeded in whatever you tried to do",
"message_type": "success"
}The event_id property needs to be the same as the originating OneClick event_id as explained earlier. The message property is your message and in the message_type property you can define the type of your message.
Additionally you can add a redirect_url property, read more here.
Using HTML to format your message
You can add HTML in your message content to add format. Allowed HTML tags are <a> <b> <i> <br> and <div>. Inline CSS is not allowed. All messages with any illegal HTML tags or CSS will be disregarded.
Please note that the maximum message length is 2000 characters, including HTML formatting
Messaging options
There are a few ways you can configure the messaging behavior in your button settings:
Make messages public
By default the messages are only visible to the user who clicked the button and only on the specific deal, organization or person object from which the button was clicked from. If you want all users to see each other's messages you can make the messages public.
If the messages are made public all user's can see each other's messages, but only on the specific object from which the button was clicked. So as an example if a button with public messages is clicked on deal A, everybody can see the messages on deal A but not on deal B because the messages are still specific to the object.
Please note that the message unread status is only relevant to the user who clicked the button. All others will see the messages as read, unless the message was caused by their own button click
Do not log HTTP responses
If you do not wish to consider HTTP responses as OneClick messages you can enable this option. You can still use custom messages as explained earlier in this article. If enabled any HTTP responses will not be visible in the message log view.
Redirect from response
If the message contains a redirect_url property the user who clicked the button will be redirected to this URL automatically. The URL will open in a new browser tab. An example message content with redirect:
{
"event_id": "d3cc3758-41d3-4eba-bb80-894734f5fa20",
"message": "You succeeded in whatever you tried to do",
"message_type": "success",
"redirect_url": "https://your-tenant.pipedrive.com/organizations/list/filter/37"
}You can also use the redirect feature without an actually message by leaving the message and message_type properties out from your response. An example message content with redirect only:
{
"event_id": "d3cc3758-41d3-4eba-bb80-894734f5fa20",
"redirect_url": "https://your-tenant.pipedrive.com/organizations/list/filter/37"
}If you do not provide an actual message, the user's message log will contain information about the redirect as follows:
Please note that the redirect is only effective within the 45 second message window
Disable the button if there are unread error messages
If you want to make sure the users pay attention to error messages you can enable this feature. If enabled and an unread error message is present, the button will be disabled until the user goes to the message log and sees the error message.
Please note that if you have also made the messages public this only applies to the user who clicked the button
Disable the button if there are any unread messages
If you want to make sure the users read all messages before clicking the button again you can enable this feature. If enabled and there are any unread messages in the message log the user needs to see all the messages until the button can be clicked again.
Please note that if you have also made the messages public this only applies to the user who clicked the button
Using a button with messaging
When a button with messaging enabled is triggered and a message is sent back as a HTTP response or custom message, an envelope icon will appear next to the button. Blue color indicates unread messages and red unread error messages.
When the icon is clicked message log opens. Messages will be marked as read when the user sees them, so if there are many unread messages the user may need to scroll down in order to see them. You can also click on the Mark all read button to confirm all messages.
Message retention and deletion
The messages will be retained for 30 days and then automatically permanently removed. If you need to keep data longer we recommend storing it in Pipedrive for example as a note, activity or in a custom field as part of your automation.
If you want to delete messages you can go to the button settings and click on Clear all messages under the messaging section. This permanently deletes all messages related to the specific button.
Please note that the message deletion may take up to 45 seconds until the message log will be cleared for the button