Automating WhatsApp Outreach with HubSpot and WhatsApp Templates

Jakub Swistak
Published Updated 8 min read
Diagram showing a HubSpot contact creation triggering a WhatsApp template message

In our HubSpot integration guide, we covered connecting an AI Agent to HubSpot live chat. In the HubSpot AI Actions post, we showed how the AI Agent can create contacts, deals, and tickets during conversations.

This post covers automatically sending an approved WhatsApp marketing template when a HubSpot contact is created or its outreach property changes. The contact property quickchat_send_whatsapp_marketing_template also selects the Quickchat AI Agent that sends the template. Set it to that Agent’s exact ID. The legacy value true works only when exactly one Agent is connected to the HubSpot account through OAuth.

The trigger is a HubSpot webhook. The message uses the selected WhatsApp template and the supported contact fields described below. A webhook or successful API request does not, by itself, confirm delivery to the recipient.

How It Works

The flow is:

  1. A contact is created in HubSpot, or its quickchat_send_whatsapp_marketing_template property changes to a routing value.
  2. HubSpot sends a contact.creation or contact.propertyChange webhook. Quickchat AI processes eligible notifications in the background, subject to the short suppression window described under Webhook Processing.
  3. Quickchat AI reads the contact’s current property value and selects a HubSpot-authorized Agent. An unknown ID or an ambiguous true value selects no Agent.
  4. If that Agent has a selected template, a WhatsApp connection and a usable contact phone number, Quickchat AI builds the template parameters and submits the message to the WhatsApp Business API.

The feature uses HubSpot OAuth independently of the Enable HubSpot toggle, which controls the live chat bot. The intended Agent still needs its WhatsApp connection and selected outbound template.

Prerequisites

Before setting up this feature, you need:

  1. A Quickchat AI account with the intended AI Agent.
  2. A HubSpot account and permission to create or edit contact properties. Follow the HubSpot connection steps to authorize the intended Agent through OAuth.
  3. A WhatsApp Business account connected to that same Agent and an approved message template available to it.
  4. A recipient who has supplied their number and given permission to receive your messages, with opt-outs respected. Setting a CRM property does not establish that permission. See the WhatsApp Business Messaging Policy.
  5. A controlled test recipient, such as a team member who has agreed to receive the test. The test sends a real WhatsApp message and may incur messaging charges.

Step 1: Create a Custom Property in HubSpot

First find the intended Agent’s ID. In Quickchat AI, select the Agent, then open Channels > External Apps > API. Copy the value next to Your scenario_id:. This is the Agent identifier used for routing. You do not need to create an API token or copy a secret to read it.

For a new property:

  1. In HubSpot, open Settings > Properties and select Contact properties. Check whether quickchat_send_whatsapp_marketing_template already exists before creating anything.
  2. Click Create property, then Edit more options to configure its details.
  3. Use a label such as Send WhatsApp Marketing Template via Quickchat AI, choose Contact information or another suitable group, and set the internal name to exactly quickchat_send_whatsapp_marketing_template.
  4. Choose Single-line text as the field type so the property can hold an Agent ID. Leave its default value empty, then create the property.
  5. Set the value to the intended Agent’s exact scenario_id only for contacts selected for this outreach. When creating a new contact, include the routing value and phone number in the initial save where possible.

HubSpot distinguishes text properties from checkboxes. The routing behavior is:

HubSpot-authorized Agents in the accountContact property valueRouting result
NoneAny valueNo Agent selected; no send
One or moreExact ID of one of those AgentsSelect that Agent, subject to its template, WhatsApp and phone requirements
Onetrue or TrueSelect the single Agent
More than onetrue or TrueAmbiguous; no Agent selected and no send
One or morefalse, blank or missingNo Agent selected; no send
One or moreUnknown ID, or an ID with different capitalizationNo matching Agent; no send

Whitespace around the value is trimmed. Agent IDs are case-sensitive; the legacy true value is case-insensitive. The count includes Agents connected to that HubSpot account through OAuth even if their live chat toggle is off or they have no outbound template selected. Selecting a template on only one Agent does not make true unambiguous when other Agents are authorized.

If the property already exists as a single checkbox, its true/false values remain supported for the single-Agent setup. Keep that working configuration if it meets your needs. A checkbox cannot store an explicit Agent ID. Before adapting an existing property for multiple Agents, have the HubSpot administrator review its saved values, forms, imports and workflows, export the relevant data, and plan changes to the systems that write it. HubSpot documents field-type editing restrictions and possible invalidation of existing values. Do not delete and recreate the property or assume a lossless conversion. Until a compatible property and its dependent workflows are ready, do not use true for a multi-Agent account.

Step 2: Create a WhatsApp Template in Meta Business Manager

This workflow sends an approved template. WhatsApp requires approved templates to initiate conversations and to message outside the 24-hour customer service window; replies within that window can use other message types. If you already have a suitable approved marketing template, skip to Step 3.

  1. Go to Meta Business Manager > WhatsApp Manager > Message Templates.
  2. Click Create Template.
  3. Select Marketing as the category.
  4. Choose a language (e.g., en for English).
  5. Write the template body. You can use placeholders for personalization.

WhatsApp supports two placeholder formats:

FormatExampleDescription
NumberedHello {{1}}, welcome aboard!Parameters are positional
NamedHello {{firstname}}, welcome!Parameters are referenced by name

Quickchat AI maps these placeholders to HubSpot contact properties:

PlaceholderMaps to
{{1}}First Name
{{2}}Last Name
{{firstname}}First Name
{{lastname}}Last Name
Any other nameFallback value (-)

If your template uses parameters beyond first and last name (for example, {{latest_post}} or {{3}}), those receive a fallback dash (-) when the template metadata is available. Missing first or last names also use that fallback. These placeholders do not look up arbitrary HubSpot fields. The dash supplies a nonempty parameter value; it does not guarantee that Meta accepts or delivers the message. Use a template whose body works with this limited mapping.

  1. Submit the template for review and wait for approval. In WhatsApp Manager, approved templates appear as Active, followed by a quality rating. Approval timing varies, and Meta can subsequently pause or reject a template.

Step 3: Select the Template in Quickchat AI

  1. Log in to your Quickchat AI dashboard.
  2. Select your AI Agent.
  3. Go to Channels > External Apps and open HubSpot.
  4. Under Settings, find the WhatsApp template dropdown. It appears when HubSpot is connected, the Agent’s WhatsApp connection is ready, and the approved-template list loads with at least one entry. The live chat toggle does not have to be enabled.
  5. The dropdown shows the loaded approved templates and their language codes. Check both the template name and language.
  6. Select the template you want to send. The selection is saved immediately; if saving fails, resolve the error before testing.

To disable the feature, select None from the dropdown. When no template is selected, the webhook is still received but no message is sent.

Step 4: Test the Setup

  1. Confirm the intended Agent, selected template and language, and the test recipient’s permission. Use a number you control or whose owner has agreed to the test, including its country code.
  2. In HubSpot, create a test contact with that Phone number, first and last name, and the routing property in the same save. Use the exact Agent ID for a text property, or true for an existing checkbox only when a single Agent is authorized.
  3. Check the intended Agent’s Inbox for the outbound template record and verify the actual message on the recipient’s phone. An Inbox record reflects a successful submission to Meta, not proof of delivery or reading. Recording in the Inbox can also fail independently, so absence of a record does not prove that no message was sent.
  4. Compare the sender, template language and substituted names with what you configured. If receipt is unconfirmed, record it as unconfirmed and investigate before retrying.

To check the update path separately, use an existing test contact with permission and a phone number. Change the routing property from blank or false to the intended value. Avoid changing it immediately after creating that contact: creation and property changes share the same two-minute suppression window. Saving an unchanged value is not a reliable way to generate a property-change event. These are checks to perform in your own setup, not delivery results from this tutorial.

If the message does not arrive, check the following:

  • The Phone number field contains the intended WhatsApp recipient number, including its country code. This workflow reads that field, not Mobile phone number.
  • The template is approved and appears as Active in WhatsApp Manager, rather than paused or disabled.
  • The routing property matches an authorized Agent’s ID exactly, or true is used only with one authorized Agent. Check for other connected Agents, not just other selected templates.
  • The intended Agent has both a WhatsApp Business connection and a selected outbound template. If the dropdown is missing, check the connection and whether approved templates loaded.
  • A preceding creation or property-change notification has not caused the new event to fall inside the suppression window. Do not repeatedly toggle the property to troubleshoot an uncertain send.

Technical Details

This section covers the internals for those who want to understand what happens behind the webhook handler.

Webhook Processing

HubSpot sends contact.creation and subscribed contact.propertyChange notifications in JSON arrays. For this outreach property, nonempty property changes other than false are queued for processing; the later routing check can still reject the value. Each event supplies portalId (HubSpot account), objectId (contact ID) and eventId. Quickchat AI reads the contact’s current properties when it processes the notification, so a later edit can affect the value it sees.

Quickchat AI suppresses repeated processing for the same contact and HubSpot account for two minutes. The cache key uses objectId and portalId, not eventId. This window begins before contact lookup and routing checks, so it can also suppress a rapid follow-up after an earlier notification was skipped. Creating a contact first and setting its routing value in a second immediate step can therefore miss the intended send.

This is short-term suppression, not a permanent send ledger or an exactly-once guarantee. A later notification can be processed after the window expires. HubSpot’s webhook documentation also says notifications may be repeated or arrive out of order, and eventId is not guaranteed unique. Verify receipt before deliberately triggering another message.

Phone Number Normalization

The WhatsApp Business API expects phone numbers as digits only, without a leading +. The normalization logic:

  1. Strips all non-digit characters.
  2. Removes a leading 00 international dialing prefix (e.g., 0048123456789 becomes 48123456789).
  3. Rejects numbers shorter than 7 digits as invalid.

This is basic normalization, not validation that a country code is correct or that the number belongs to an active WhatsApp recipient.

Some examples:

InputNormalized
+1 (555) 123-456715551234567
004812345678948123456789
+442071234567442071234567
12345Rejected (too short)

Template Parameter Resolution

Before sending the template, the system fetches the template’s metadata from the Meta Graph API to determine the expected parameters. This is necessary because different templates have different placeholders, and the WhatsApp API rejects messages where the number of parameters does not match the template definition.

The resolution process:

  1. Call GET /{whatsapp_business_account_id}/message_templates?name={template_name} on the Meta Graph API.
  2. Find the BODY component in the response.
  3. Extract all {{...}} placeholders using a regex.
  4. For each placeholder:
    • If it’s a digit ({{1}}, {{2}}), map positionally: position 1 = first name, position 2 = last name.
    • If it’s a known name ({{firstname}}, {{lastname}}), map by name.
    • Otherwise, use the fallback value -.

For named parameters, the Meta API requires a parameter_name field in the request body. Numbered parameters omit this field. The resulting payload sent to POST /{phone_number_id}/messages looks like this for a template with {{firstname}} and {{lastname}}:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "welcome_new_contact",
    "language": { "code": "en" },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "parameter_name": "firstname",
            "text": "John"
          },
          {
            "type": "text",
            "parameter_name": "lastname",
            "text": "Doe"
          }
        ]
      }
    ]
  }
}

If the template metadata cannot be fetched, or is unavailable for the connection, the system falls back to first name and last name as two positional parameters when either name is present. A missing name is an empty string in this fallback path. If both names are empty, it submits the template without body parameters. That fallback can mismatch the approved template and be rejected; it does not make an unavailable template or incompatible parameter layout valid.

Authorization Model

This feature reuses the intended Agent’s HubSpot OAuth connection and requires its WhatsApp sending configuration. The Enable HubSpot toggle controls the HubSpot live chat bot; turning it off does not disable outbound template outreach or remove that Agent from routing. Select None in the outbound WhatsApp template dropdown to disable this feature for that Agent. Keep recipient permission and outreach selection under your team’s control rather than treating the routing property as proof of consent.

Use Cases

A few patterns where this is useful:

  • Post-form follow-up: A prospect provides a phone number and the required messaging permission. Set the intended routing value as part of contact creation where possible, rather than assuming an immediate second update will bypass suppression.
  • Event registration confirmation: Select an approved template containing the event details as fixed text, then route eligible contacts to its Agent. The dynamic mapping supplies first and last name only; it does not retrieve event details from custom CRM fields.
  • Lead nurturing: After an AI Agent creates a contact via a HubSpot AI Action, a separately configured HubSpot workflow can select it for outreach. Account for the suppression window and confirm recipient permission before triggering the change.

What’s Next

For more on integrating your AI Agent with HubSpot, see the HubSpot integration guide and the HubSpot AI Actions tutorial. For general information on WhatsApp templates, see Meta’s message template documentation.

Quickchat AI Quickchat AI Ask Quickchat AI a question