Skip to main content

Monitoring Workflow Message Delivery

Check what happened to messages sent from HubSpot workflows so you can catch failures early and trust your automations.

Written by Tarek Khalil

What you can see about a workflow message

Every time a workflow action sends a message through Octopods, it produces two output fields that HubSpot stores on the workflow execution:

  • WhatsApp Message ID (for WhatsApp sends) — the identifier of the message at the provider.

  • Initial Delivery Status — the state the message was in when Octopods handed it off to the channel.

HubSpot also records the standard action-level success or failure, including any error message Octopods returned.

Where to look in HubSpot

For any workflow that includes an Octopods action:

  1. Open the workflow in HubSpot.

  2. Click the History tab (or the action card → See performance).

  3. Pick a specific enrollment to see the per-contact execution log.

  4. Expand the Octopods action in the log. The output fields (message ID, delivery status) appear alongside the action’s final status.

Tip: HubSpot’s workflow history is the authoritative source for what happened on a per-contact basis. Use it before digging into Octopods itself.

Delivery statuses you’ll see

The Initial Delivery Status reflects what the provider returned at send time. The most common values are:

  • sent — the message was accepted by the provider. Delivery to the customer’s device is still in progress.

  • delivered — the message reached the recipient’s device.

  • failed — the provider rejected the message at send time.

Because the delivery status is captured at the moment the workflow action runs, it reflects the initial handoff. A customer blocking your number, turning off their phone, or reading the message happens later and isn’t captured in this output field.

Why a workflow message might fail

When an Octopods workflow action fails, the most common reasons are:

  • Invalid or missing phone number. The HubSpot contact has no phone, an empty phone, or a phone that can’t be parsed into a valid international format. The error message names the contact ID and the offending value.

  • Missing HubSpot Contact ID. The workflow was triggered on an object that didn’t resolve to a contact — usually because the object type isn’t supported by the action.

  • Template not found. The WhatsApp template you selected was deleted, paused, or rejected after the action was configured.

  • Template variable count mismatch. The template requires more body or header variables than you mapped.

  • Missing header attachment URL. A media-header template is missing its Header Media URL.

  • Channel disconnected. The WhatsApp or Twilio channel the action is using is no longer active in Octopods.

Each error is recorded on the workflow enrollment so you can see exactly which contact was affected.

What to do when a workflow message fails

The right fix depends on the error:

  1. Fix the data first. For phone-number problems, update the HubSpot contact’s Phone number or Mobile phone number to a valid international format. For missing associations, make sure the workflow is running on a supported object type.

  2. Fix the configuration next. For template problems, open the workflow action and re-select an approved template, or fill in the missing variable. For channel problems, reconnect the affected channel in Octopods.

  3. Re-enroll the contact in the workflow if you want the message to go out again. HubSpot’s workflow tools let you re-enroll contacts after an action has failed.

How workflow messages count toward usage

Messages sent through a workflow action count the same as any other outbound message:

  • WhatsApp template messages count against your WhatsApp message volume and the template’s category pricing.

  • SMS messages count against your Twilio number’s outbound usage.

You can see overall usage in your workspace’s usage dashboard. Messages that fail with validation errors (for example, an invalid phone number) are not sent and therefore do not count.

Spot-checking a real send

If you want to confirm end-to-end delivery after setting up a workflow, the fastest approach is:

  1. Enroll a test contact (yourself, or a colleague) whose phone number you control.

  2. Let the workflow run.

  3. Check the contact’s phone to confirm the message arrived.

  4. Check the workflow history to confirm the delivery status.

Note: WhatsApp template delivery may take a few seconds to appear on the device; SMS is typically near-instant once the provider accepts it.

What’s next

Did this answer your question?