> For the complete documentation index, see [llms.txt](https://polser.gitbook.io/polser-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polser.gitbook.io/polser-docs/admin/hubspot-native-integration/hubspot-workflow-actions.md).

# HubSpot Workflow Actions

## HubSpot Workflow Actions

{% hint style="info" %}

### Before you start

Make sure you have completed the HubSpot Native Integration setup:

* Polser is connected to HubSpot in **Settings → Integrations**
* The **Polser** app was installed from the HubSpot App Marketplace
* Your **Polser account URL** is saved in the HubSpot app settings
* At least one **WhatsApp phone number** is connected in Polser
  {% endhint %}

Workflow actions let you automate WhatsApp messaging and contact management directly from HubSpot workflows — for example, when a contact is created, a deal stage changes, or a form is submitted.

All Polser workflow actions are available under **Automation → Workflows**. When building or editing a workflow, add an action and search for **Polser**.

{% hint style="warning" %}
All Polser workflow actions run on **Contact** records. Enroll contacts (not companies or deals) in workflows that use these actions, or use a workflow branch that operates on the enrolled contact.
{% endhint %}

***

### Overview

| Action                               | What it does                                  | 24-hour session required? |
| ------------------------------------ | --------------------------------------------- | ------------------------- |
| **Send a WhatsApp message**          | Send a free-form text message                 | Yes                       |
| **Send a WhatsApp template message** | Send a Meta-approved template                 | No                        |
| **Send a voice note**                | Send an audio message                         | Yes                       |
| **Send a WhatsApp sticker**          | Send a saved sticker from your Polser account | Yes                       |
| **Create or update a contact**       | Create or update a contact in Polser          | No                        |
| **Delete a contact**                 | Permanently delete a contact from Polser      | No                        |

***

### Adding a Polser action to a workflow

1. In HubSpot, go to **Automation → Workflows** and create or open a workflow.
2. Set the enrollment trigger (e.g., contact created, property updated, form submitted).
3. Click **+** to add an action.
4. Search for **Polser** and choose the action you need.
5. Map the input fields — most phone fields accept a **contact property** (e.g., Phone number, Mobile phone number, or a custom WhatsApp field).
6. Save and publish the workflow.

{% hint style="info" %}
**Tip:** Map the phone field to the same HubSpot property you configured under **WhatsApp phone number to sync** in Polser. Use international format with country code (e.g. `+34 612 345 678`).
{% endhint %}

***

### Common fields

Several actions share the same optional fields.

#### Phone Number

The recipient’s phone number. Map a HubSpot contact property that holds a valid WhatsApp number.

* Use international format with country code (e.g. `+44XXXXXXXXXX`, `+34XXXXXXXXX`).
* This field is required on all messaging actions and on **Delete a contact**.

#### Source Phone Number

Optional. Only needed if your Polser account has **more than one WhatsApp number**.

Specify which number to send from, in international format (e.g. `+34XXXXXXXXX`). If you have a single WhatsApp number, leave this blank — Polser uses it automatically.

If you have multiple numbers and do not set this field, the action fails with an error asking you to provide a source phone.

***

### Messaging rules (24-hour session window)

WhatsApp limits when you can send free-form messages outside approved templates.

These actions require an **active 24-hour messaging session** — the contact must have messaged your business on WhatsApp within the last 24 hours:

* Send a WhatsApp message
* Send a voice note
* Send a WhatsApp sticker

**Sending a WhatsApp template message** does **not** require an active session. Use it to start conversations or re-engage contacts outside the 24-hour window.

If the session has expired, the action fails with an error suggesting you use a template instead.

***

### Action reference

#### Send a WhatsApp message

Send a text message to a contact via WhatsApp.

**When to use:** Follow-ups, reminders, or personalized messages inside the 24-hour window.

| Field               | Required | Type             | Description                                                     |
| ------------------- | -------- | ---------------- | --------------------------------------------------------------- |
| Phone Number        | Yes      | Contact property | Recipient’s phone number in international format                |
| Message             | Yes      | Static text      | The message body                                                |
| Source Phone Number | No       | Static text      | Sending number (multi-number accounts only)                     |
| Enable URL Previews | No       | Checkbox         | Show link previews for URLs in the message (enabled by default) |

**Example workflow:** When a deal moves to *Closed Won*, send: `Thanks for your purchase! Our team will be in touch shortly.`

**Side effect:** If you configured **Additional fields to sync** in Polser, Polser refreshes the contact’s enhanced profile from HubSpot after a successful send.

***

#### Send a WhatsApp template message

Send a pre-approved WhatsApp template message.

**When to use:** First outreach, re-engagement after 24 hours, or any message that must use a Meta-approved template.

| Field               | Required | Type             | Description                                                                          |
| ------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------ |
| Phone Number        | Yes      | Contact property | Recipient’s phone number in international format                                     |
| Template Name       | Yes      | Static text      | Exact name of the approved template in Polser/Meta (e.g. `appointment_confirmation`) |
| Template Variables  | No       | Static text      | Comma-separated values for template placeholders (e.g. `John, 10:00 PM`)             |
| Source Phone Number | No       | Static text      | Sending number (multi-number accounts only)                                          |

**Template variables:** List values in the order they appear in the template body, separated by commas. For a template like `Hello {{1}}, your appointment is at {{2}}`, enter: `John, 10:00 AM`.

**Example workflow:** When a new contact is created in HubSpot, send a template `welcome_message` with variables from static text or prior workflow steps.

**Side effect:** Enhanced profile fields from HubSpot are synced to Polser after a successful send (same as free-form messages).

***

#### Send a voice note

Send a voice note (audio message) to a contact via WhatsApp.

**When to use:** Personalized audio inside the 24-hour session window.

| Field               | Required | Type             | Description                                      |
| ------------------- | -------- | ---------------- | ------------------------------------------------ |
| Phone Number        | Yes      | Contact property | Recipient’s phone number in international format |
| Audio File URL      | Yes      | Static text      | Public URL to an **OGG** audio file              |
| Source Phone Number | No       | Static text      | Sending number (multi-number accounts only)      |

{% hint style="warning" %}
The audio file must be hosted at a **publicly accessible URL** and in **OGG** format. Private or authenticated URLs will fail.
{% endhint %}

***

#### Send a WhatsApp sticker

Send a sticker from your Polser account’s saved sticker library.

**When to use:** Branded or casual replies inside the 24-hour session window.

| Field               | Required | Type             | Description                                                          |
| ------------------- | -------- | ---------------- | -------------------------------------------------------------------- |
| Phone Number        | Yes      | Contact property | Recipient’s phone number in international format                     |
| Sticker Number      | Yes      | Static number    | Position of the sticker in your Polser library (starting from **1**) |
| Source Phone Number | No       | Static text      | Sending number (multi-number accounts only)                          |

**Sticker numbers:** Stickers are numbered in the order they appear in Polser (1 = first sticker, 2 = second, and so on). Agents save stickers from the inbox composer; those saved stickers form the library this action uses.

If no stickers are configured or the number is out of range, the action fails.

***

#### Create or update a contact

Create a new contact in Polser, or update the name if the contact already exists (matched by phone number).

**When to use:** Keep Polser in sync when HubSpot creates or updates contacts, before sending messages, or for reporting.

| Field        | Required | Type             | Description                                                             |
| ------------ | -------- | ---------------- | ----------------------------------------------------------------------- |
| Phone Number | Yes      | Contact property | Unique identifier in international format                               |
| Contact Name | Yes      | Contact property | Full name (e.g. map `First name` + `Last name`, or a single name field) |
| Labels       | No       | Static text      | Comma-separated Polser labels (e.g. `Newsletter Subscriber, VIP`)       |

**Behavior:**

* If the phone number **does not exist** in Polser → a new contact is created.
* If the phone number **already exists** → the contact’s name is updated.
* **Labels:** New labels are created in Polser if they do not exist, and then applied to the contact. If you enabled label sync in Polser’s HubSpot settings, labels are also pushed to HubSpot.

**Example workflow:** When a contact is created in HubSpot, create the same contact in Polser with the label `HubSpot Lead`.

***

#### Delete a contact

Delete a contact and all related data from Polser.

{% hint style="danger" %}
**This action is irreversible.** It removes the contact, conversation history, and related data from Polser. It does **not** delete the contact from HubSpot.
{% endhint %}

| Field        | Required | Type             | Description                                              |
| ------------ | -------- | ---------------- | -------------------------------------------------------- |
| Phone Number | Yes      | Contact property | Phone number of the contact to delete, with country code |

**When to use:** GDPR erasure requests, or cleaning up test contacts — typically after a confirmation step or manual review in the workflow.

***

### Recommended workflow patterns

#### New lead → template → ongoing messages

1. **Trigger:** Contact created in HubSpot
2. **Action:** Create or update a contact (sync name and labels)
3. **Action:** Send a WhatsApp template message (start the conversation)
4. Later workflows can use **Send a WhatsApp message** once the contact replies (24-hour window opens).

#### Deal won → thank-you message

1. **Trigger:** Deal stage = Closed Won
2. **Branch:** Associated contact has a valid phone number
3. **Action:** Send a WhatsApp template message (if no recent conversation) **or** send a WhatsApp message (if inside a 24-hour window)

#### Unsubscribe/data removal

1. **Trigger:** Contact property *Marketing status* = Unsubscribed (or custom opt-out field)
2. **Action:** Delete a contact (removes data from Polser only)

***

### Troubleshooting

| Error / behavior                                       | Likely cause                                                                           | What to do                                                              |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| No tenant found for portal                             | Polser account URL not set in HubSpot app settings, or HubSpot not connected in Polser | Complete HubSpot Native Integration setup                               |
| Could not resolve WhatsApp phone                       | Multiple WhatsApp numbers and no source phone specified                                | Set **Source Phone Number** on the action                               |
| Customer last message is more than 24 hours ago        | Session expired                                                                        | Use **Send a WhatsApp template message** instead                        |
| Template not found, not approved, or invalid variables | Wrong template name or variable count/order                                            | Check template name in Polser; match variables to template placeholders |
| Contact does not exist (delete)                        | Phone not in Polser or wrong format                                                    | Normalize phone to E.164; create contact first if needed                |
| Sticker index out of range                             | Invalid sticker number                                                                 | Use 1–N where N is your sticker count in Polser                         |
| Invalid phone number                                   | Missing country code or malformed number                                               | Use international format (e.g. `+34…`)                                  |

***

### What gets synced automatically

Some behavior does not require a separate workflow action:

| Polser setting                       | Behavior                                                                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Sync all messages**                | Inbound and outbound WhatsApp messages appear in HubSpot (via the integration, not workflow actions)                     |
| **Start new chat with new contacts** | Polser automatically opens a chat when a contact is created in HubSpot                                                   |
| **Additional fields to sync**        | HubSpot fields appear in Polser’s Enhanced User Profile; refreshed after send-message and send-template workflow actions |
| **Label sync**                       | Polser labels sync to a HubSpot contact property when configured; updated by create/update contact actions               |

Workflow actions complement these settings — they give you explicit control over *when* and *what* to send from HubSpot automation.