Automating WhatsApp Outreach with HubSpot and WhatsApp Templates

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 a different workflow: automatically sending a WhatsApp marketing template to a contact the moment they are created in HubSpot CRM. The trigger is a HubSpot webhook, not a conversation. The message is a pre-approved WhatsApp template, not a free-form AI response.

How It Works

The flow is:

1. A contact is created in HubSpot (manually, via form submission, via API, or through an AI Action).
2. HubSpot fires a contact.creation webhook to Quickchat AI.
3. Quickchat AI checks whether the contact has a custom HubSpot property quickchat_send_whatsapp_marketing_template set to true.
4. If it does, Quickchat AI fetches the contact’s phone number and name from HubSpot, resolves the configured WhatsApp template’s parameters, and sends the template message via the WhatsApp Business API.

The feature does not require the Enable HubSpot toggle to be on. That toggle controls the live chat bot. WhatsApp template outreach only requires that HubSpot is connected (authorized via OAuth).

Prerequisites

Before setting up this feature, you need:

• A Quickchat AI account with an AI Agent
• A HubSpot account with admin access
• Your HubSpot account connected to Quickchat AI via OAuth (see Step 1 of the HubSpot AI Actions guide)
• A WhatsApp Business account connected to your Quickchat AI Agent
• At least one approved WhatsApp message template in your Meta Business Manager

Step 1: Create a Custom Property in HubSpot

The system only sends a WhatsApp template to contacts that have been explicitly flagged for it. This prevents accidental messages to every new contact.

1. In HubSpot, go to Settings > Properties.
2. Click Create property.
3. Set the following values:

4. Save the property.

When creating a contact (or importing contacts in bulk), set this property to true for contacts that should receive the WhatsApp template. Contacts without this property, or with it set to false, are skipped.

Step 2: Create a WhatsApp Template in Meta Business Manager

WhatsApp requires all outbound business-initiated messages to use pre-approved templates. If you already have an 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:

Quickchat AI maps these placeholders to HubSpot contact properties:

If your template uses parameters beyond first and last name (for example, {{latest_post}} or {{3}}), those will receive a fallback dash (-) as a placeholder value. The Meta API rejects empty string values for template parameters, so the fallback ensures delivery even when a value is unknown.

6. Submit the template for review. Meta typically approves marketing templates within a few minutes to a few hours.

Step 3: Select the Template in Quickchat AI

1. Log in to your Quickchat AI dashboard.
2. Select your AI Agent.
3. Go to Integrations and open the HubSpot integration modal.
4. Below the pipeline configuration, you’ll see the WhatsApp Template on Contact Creation section. This section is visible as long as HubSpot is authorized, regardless of whether the chatbot toggle is enabled.
5. The Template dropdown lists all approved templates from your connected WhatsApp Business account, along with their language codes.
6. Select the template you want to send. The configuration is saved immediately on selection.

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

Step 4: Test the Setup

1. In HubSpot, create a new contact with:
   • A valid phone number (including country code, e.g., +1 555 123 4567)
   • The quickchat_send_whatsapp_marketing_template property set to true
2. Within a few seconds, the contact should receive the WhatsApp template message on the phone number you specified.

If the message does not arrive, check the following:

• The phone number includes a country code. Numbers without a country code cannot be routed by WhatsApp.
• The template is in “Approved” status in Meta Business Manager.
• The contact property quickchat_send_whatsapp_marketing_template is exactly true (not True, not yes; HubSpot checkbox properties store lowercase true).
• Your WhatsApp Business account is connected in the Quickchat AI Agent settings.

Technical Details

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

Webhook Processing

HubSpot sends a contact.creation event as a JSON array to the webhook endpoint. Each event contains the portalId (HubSpot account), objectId (contact ID), and eventId (unique event identifier). The handler extracts these three fields and dispatches a background task.

Deduplication uses a cache key based on eventId, objectId, and portalId with a 10-minute TTL. HubSpot may retry webhook deliveries if it does not receive a timely 200 response, so this prevents duplicate sends.

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.

Some examples:

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 (network error, token issue), the system falls back to sending first name and last name as two positional parameters. If both are empty, it sends the template with no parameters at all.

Authorization Model

This feature reuses the existing HubSpot OAuth connection but does not require the Enable HubSpot toggle to be on. That toggle controls the HubSpot live chat bot. The WhatsApp template outreach only requires that HubSpot is connected (authorized via OAuth). You can use this feature independently of the live chat integration.

Use Cases

A few patterns where this is useful:

• Post-form follow-up: A prospect fills out a HubSpot form. A workflow sets the quickchat_send_whatsapp_marketing_template property to true. The contact is created, and the WhatsApp template is sent within seconds.
• Event registration confirmation: Import event attendees into HubSpot with the flag set. Each attendee receives a WhatsApp confirmation with event details.
• Lead nurturing: After an AI Agent creates a contact via a HubSpot AI Action, a HubSpot workflow can set the flag on the newly created contact, triggering a follow-up WhatsApp message asynchronously.

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.