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**.