WhatsApp Business Integration

This page describes how to connect a SipPulse AI Agent to a WhatsApp Business Platform (WABA) number, enable additional features and monitor message traffic.

1. Prerequisites

To connect your Agent to WhatsApp, it's essential that your company already has a configured structure on Meta's platform. The hierarchy is as follows:

Meta Business Account → WhatsApp Business Account (WABA) → Phone Number

Make sure all items below are completed before proceeding.

Requirement	Details and Actions
1. Verified Meta Business Account	Your company needs an account on Meta Business Suite. It's crucial that it passes the business verification process. Without this, Meta imposes severe limits that prevent operation. Action: Verify your business in the Business Suite Security Center. Status must be Verified.
2. WhatsApp Business Account (WABA)	Within your Business account, you must have a WhatsApp Account (WABA). If you already use WhatsApp with another platform, you probably already have one. Otherwise, the connection process with SipPulse AI can help create it. Action: Check for an existing WABA in Business Settings → Accounts → WhatsApp Accounts.
3. Valid and Registered Phone Number	The phone number must be able to receive voice calls or SMS for verification. Cannot be in use by another WhatsApp account (personal or Business App). Action: Add the number to your WABA and complete verification. During connection with SipPulse AI, if the number is not yet registered with WhatsApp API, registration will be requested, which may require a two-factor authentication (2FA) PIN.
4. Administrator Permissions	You need administrator access to the Meta Business account to authorize the integration. This is necessary to grant SipPulse AI BSP (Business Solution Provider) permissions. Action: Confirm your access level in Business Settings → People.

2. Connect the number

Open ⋮ → Deploy on the Agent row and click Connect on the WhatsApp card.
A Meta popup (known as Embedded Signup) will be displayed. Log in and follow the steps to select your Meta Business Account, WABA and desired phone number.
If the number is only verified, the flow will request Registration to activate it on the platform. You may need to provide a two-factor authentication (2FA) PIN or create a new one.
After approval, the card in the SipPulse AI interface will display the number and status will change to Online. From this moment, the Agent is ready to respond to received messages.

Automatic integration

No additional webhook configuration is necessary. Upon completing the connection, SipPulse AI is added as a BSP (Business Solution Provider) Partner of your WhatsApp Business Account (WABA); the platform transparently manages sending and receiving messages for that number.

If you wish to revoke access in the future, go to Meta Business Manager → Business Settings → Accounts → WhatsApp Accounts → Settings → Partners and remove SipPulse AI from the list.

3. Quickly enable or disable

Use the toggle in the top-right corner of the card.

On → the Agent processes messages in real time.
Off → incoming traffic is ignored; no token charges.

4. Preferences

Open ⋮ → Preferences on the card to adjust behavior per number.

4.1 Inactivity closure

Option	Description
Time (min)	Period without user messages after which the conversation is closed.
Closing message	Text sent automatically before closure. If empty, nothing is sent.

When a conversation is closed:
The Agent executes configured Post-Analyses.
The thread.closed webhook is triggered (see Webhooks).

4.2 Audio support (transcription)

Field	Function
Enabled	Converts voice messages to text so the Agent can respond.
Model	Choose the transcription model (`pulse-precision-v3`, etc.). Cost according to pricing table.

If disabled, the user receives the default response "Sorry, I cannot process audio messages." The same applies to images, videos or documents – support for these types will be added in the future.

5. Sending proactive messages

For the Agent to initiate a conversation with a user, WhatsApp requires the use of Message Templates (also known as Message Templates or HSM). These templates need to be created and pre-approved by Meta.

5.1 Creating a Message Template

Access Meta Business Suite.
Navigate to All tools → WhatsApp Manager.
Select the correct WABA and go to Account tools → Message templates.
Click Create template.

During creation, you will define:

Category:
- Marketing: Promotions, offers, advertisements.
- Utility: Account notifications, order alerts, etc.
- Authentication: One-time codes for login.
Name: A unique identifier (e.g., order_shipped_notice).
Languages: You can create versions for multiple languages.
Components:
- Header (Optional): Text, image, video or document.
- Body: The main message text. Use variables like 1, 2 for dynamic content.
- Footer (Optional): A short text line.
- Buttons (Optional): Quick reply buttons or call-to-action buttons (visit website, call).

After submission, the template goes through Meta review, which usually takes a few minutes.

Reference: For detailed guidelines on template creation, see Meta's official documentation.

Important: If no approved template exists in your WABA, the template list in the SipPulse AI interface will appear empty.

5.2 Manual sending via UI

Click Send Message in the WhatsApp card menu.
In the side panel, choose the desired Template.
Enter the Destination number (+5511987654321).
Fill in the template's Variable fields if they exist (e.g., {{name}}, {{order_id}}).
(Optional) Write Additional instructions to contextualize the Agent before sending.
Click Send.

5.3 Specific costs

Each triggered template opens a paid conversation whose value is charged directly by Meta (see Costs section).
Cost varies according to template category and recipient region.

5.4 Sending via API

Click </> Code in the interface to get complete examples in Python, JavaScript and cURL.

Endpoint:

text

POST /agent-deploy-whatsapp/{deploy_id}/send-message

Request Body (Example): The variables object is a SipPulse AI abstraction to simplify template component filling.

json

{
  "template_name": "order_confirmed",
  "language_code": "pt_BR",
  "to": "+5511987654321",
  "variables": {
     "body": {
      "name": "Maria",
      "order_id": "98765"
    },
    "buttons": [
      "A98765"
    ]
  }
}

Structure of variables:

The API abstracts component complexity. Simply send the data you want to fill:

body: (Required) An object (dictionary) where each key corresponds to the variable name in the template body (e.g., name, order_id), and the value is the content to be inserted.
buttons: (Optional) A list of strings. Each string in the list fills a variable in dynamic buttons, in the order they appear. Used to complete URLs or for quick reply buttons with variable content.

Required Headers:

Content-Type: application/json
api-key: {SIPPULSE_API_KEY}

Delivery not guaranteed

A 200 Ok response indicates the request was received by SipPulse AI. Delivery to the end user depends on template approval, conversation window, WhatsApp routing and possible pending payments in the Meta Business account. Use the Debug tab to confirm message status.

6. Debugging

The ⋮ → Debug menu displays message and event history:

Column	Meaning
Processed at	Date/time in UTC
Status	`received`, `sent`, `delivered`, `failed`, etc.
Type	`text`, `button`, etc...
Content	Message excerpt or event description

Quick filters allow isolating failures or testing real time with the Refresh button.

7. Costs

Using the WhatsApp channel involves two distinct types of costs:

SipPulse AI Platform Costs:
- Message Processing: Agent token consumption, according to the configured language model (LLM).
- Audio Transcription: Additional cost charged per minute of processed audio, according to the chosen transcription model.
Meta Platform Costs:
- Conversations: Meta charges per 24-hour conversation. Price varies according to conversation category (user-initiated or company-initiated via template) and end user's country.
- Tracking: Meta costs are billed directly to your account. You can monitor them in Meta Business Suite → Billing and Payments.

For details on Meta pricing, see the official WhatsApp Business Platform pricing documentation.

Agents

Deploying Agents

Settings

WhatsApp Business Integration

1. Prerequisites

2. Connect the number

3. Quickly enable or disable

4. Preferences

4.1 Inactivity closure

4.2 Audio support (transcription)

5. Sending proactive messages

5.1 Creating a Message Template

5.2 Manual sending via UI

5.3 Specific costs

5.4 Sending via API

6. Debugging

7. Costs

Deploying Agents

WhatsApp Business Integration ​

1. Prerequisites ​

2. Connect the number ​

3. Quickly enable or disable ​

4. Preferences ​

4.1 Inactivity closure ​

4.2 Audio support (transcription) ​

5. Sending proactive messages ​

5.1 Creating a Message Template ​

5.2 Manual sending via UI ​

5.3 Specific costs ​

5.4 Sending via API ​

6. Debugging ​

7. Costs ​

WhatsApp Business Integration

1. Prerequisites

2. Connect the number

3. Quickly enable or disable

4. Preferences

4.1 Inactivity closure

4.2 Audio support (transcription)

5. Sending proactive messages

5.1 Creating a Message Template

5.2 Manual sending via UI

5.3 Specific costs

5.4 Sending via API

6. Debugging

7. Costs