What the workflow integration is
Once your HubSpot portal is connected to Octopods, the Octopods workflow actions are available inside HubSpot’s workflow builder. You can add an Octopods action as a step in any workflow that operates on records with a destination Octopods can message — typically a contact with a phone number.
When the workflow runs and reaches the Octopods step, it triggers Octopods to send the message you configured. The message goes out on the channel you chose, and the resulting conversation lands in the HubSpot inbox you’ve routed that channel to — the same flow as any inbound conversation.
Before you begin
To use the workflow integration you need:
A HubSpot workspace already connected to your Octopods account.
At least one channel that supports proactive messaging connected inside the HubSpot workspace — Twilio SMS or WhatsApp Cloud API.
HubSpot Workflows access. Your HubSpot subscription must include workflows, and your HubSpot user must be able to create or edit workflows.
If you haven’t connected your HubSpot portal yet, see Connecting a HubSpot Portal.
Step 1: Open or create the workflow
In HubSpot, go to Automation > Workflows. Open an existing workflow or create a new one for the object type you want to message — typically Contact-based workflows for messaging contacts.
Step 2: Add the Octopods action
At the point in the workflow where you want to send the message, click to add an action.
Find the Octopods action in the workflow action list. The action represents one outbound message and is configured per-step.
Select the action to start configuring it.
Step 3: Configure the action
Each Octopods action asks for the details of the message it will send:
Channel. Pick which connected channel the workflow should send through (for example, WhatsApp Cloud API or Twilio SMS).
Template. For WhatsApp, pick the pre-approved template you want to send. The dropdown is searchable so you can find a template by name even if the list is long.
Variables. For WhatsApp templates with variables, map each variable to a HubSpot property (such as the contact’s first name, an appointment date, an order number) so each enrolled record gets the personalized values.
Media. For templates that include media, configure the media the template should send.
Message body. For SMS, configure the text of the message — typically by combining literal text with HubSpot personalization tokens.
Save the action when you’re done.
Step 4: Test, review, and turn the workflow on
Before turning the workflow on for everyone:
Use HubSpot’s workflow review and test features to confirm the action is enrolled correctly and that the variables resolve to sensible values for sample records.
If your workflow uses enrollment criteria, confirm that only the records you intend to message will be enrolled.
Turn the workflow on. From this point, every record that meets the enrollment criteria will trigger the Octopods action.
What happens when the action runs
For each record the workflow processes:
HubSpot sends the action to Octopods with the record’s data.
Octopods picks the channel and template (or message text) you configured, applies the variable values from the record, and sends the message.
The resulting conversation is created or updated in the HubSpot inbox the channel routes to — the same place inbound conversations from that channel land.
The action returns success or failure to the workflow. If it fails, Octopods returns a reason and a request ID so you have something to look up if you need to investigate.
The customer receives a normal message on their channel — they don’t see anything that identifies the workflow as the source.
Channels and message types supported
The workflow actions cover the channels that support automated proactive messaging:
WhatsApp Cloud API — send a pre-approved WhatsApp template, with variables and media as needed.
Twilio SMS — send a free-form text message.
If a channel doesn’t support proactive sending or isn’t connected in the workspace, it won’t appear in the action’s channel dropdown.
Monitoring workflow message delivery
You can confirm what was sent in two places:
HubSpot. The workflow’s history, plus the inbox the channel routes to, shows the conversation each workflow execution created.
Octopods. The proactive messaging history in Octopods records every outbound message, including those triggered by workflows, with delivery status.
When the workflow action fails, the failure reason and request ID returned to HubSpot give you what you need to either retry the action (manually re-enrolling the record once the issue is fixed) or contact Octopods support.
Common things that go wrong
The Octopods action doesn’t appear in the workflow action list. The HubSpot portal isn’t connected to Octopods, or the connection is no longer active. Reconnect the portal from the Connected Workspaces page in Octopods.
No channels appear in the action’s channel dropdown. No channels in your HubSpot workspace currently support proactive messaging, or none are connected. Add or check your channels in Octopods.
A template won’t appear in the dropdown. The template isn’t approved on the connected WhatsApp channel, or it doesn’t belong to the channel you picked. See the Templates section for template approval.
The action fails with a missing-variable error. A required template variable is mapped to a HubSpot property that’s empty for the enrolled record. Add a default value or filter the workflow to only enroll records with the property set.
The action fails with a missing-phone error. SMS and WhatsApp need the contact to have a phone number in international format. Filter the workflow to only enroll contacts with a phone number, or normalize phone numbers in the contact properties first.
What’s next
See the Proactive Messaging section for proactive sending from Octopods directly
See the Templates section for managing WhatsApp templates available to workflows