WhatsApp Business Chat Integration with Novu

<Note> Check out the [agents](/agents) documentation for more information on how to build agents using WhatsApp. </Note>

Getting Started

To integrate WhatsApp Business with Novu, You will have to create a facebook developer app and obtain the necessary credentials.

<Steps> <Step title="Create a Facebook developer app"> Visit the [Facebook Developer Portal](https://developers.facebook.com/apps/) and create a new app.

Select "Other" for "What do you want your app to do?" and select "Business" for "Select an app type".

</Step> <Step title="Setup WhatsApp product"> On the App Setup page, click on "Set Up" under the "WhatsApp" product. You will need to create or add a Facebook Business Account to your app. </Step> <Step title="Send a sandbox message"> Copy the following pieces and paste them in the Novu WhatsApp Business integration settings:

Temporary access token - Access API token field
Phone Number ID - Phone number identification field

<Warning> It's important to note that the test credentials for whatsapp cannot be used in production and will expire in 24 hours. You will need to submit your app for review to obtain production credentials. </Warning> </Step> <Step title="Add a test phone number"> You can add a test phone number to the sandbox by clicking on the **"Add Phone Number"** button. This number can be used to test your integration with Novu before submitting for a review. </Step> <Step title="Send a test notification from Novu"> You can now create a new workflow with a "chat" node, and add your content. Save your workflow, and click on **"Trigger Notification"** button.

In the to field, specify the phone number you added in the sandbox, and click on "Send Notification".

json

{
  "subscriberId": "TEST_SUBSCRIBER_ID",
  "phone": "+11111111111"
}

and in the overrides field, add the following:

json

{
  "chat": {
    "template": {
      "name": "hello_world",
      "language": {
        "code": "en_US"
      }
    }
  }
}

<Note> For test credentials you can only used the built in Whats App Template. </Note> </Step> </Steps>

Going to production

<Steps> <Step title="Register a business phone number"> To go live you will need to add a real business phone number and submit your app for review. Follow the [Facebook Instructions](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/add-a-phone-number) on how to proceed. </Step> <Step title="Generate a permanent access token"> Follow the [Facebook Instructions](https://developers.facebook.com/docs/whatsapp/business-management-api/get-started/) on how to generate a permanent access token. Depending on your use case. </Step> <Step title="Create a WhatsApp template"> You will need to create a WhatsApp Template to send notifications to your customers. Create a template in the [Business Manager](https://business.facebook.com/wa/manage/message-templates) and submit it for review. After your template is approved, you can use the `template_name` to send notifications to your customers.

To send a notification with a template, you will need to add the following to the overrides field:

<Tabs> <Tab title="Node.js"> ```typescript import { Novu } from '@novu/api';

const novu = new Novu({ secretKey: "<NOVU_SECRET_KEY>" });

await novu.trigger({ workflowId: "workflowId", to: { subscriberId: "subscriberId", phone: "+11111111111", }, payload: {}, overrides: { "chat": { "template": { "name": "template_name", "language": { "code": "en_US" } } } }, });

  </Tab>
  <Tab title="Python">
```python
import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId", "phone": "+11111111111"},
        payload={},
        overrides={
        "chat": {
                "template": {
                        "name": "template_name",
                        "language": {
                                "code": "en_US"
                        }
                }
        }
},
    ))

</Tab> <Tab title="Go"> ```go import ( "context" "os"

novugo "github.com/novuhq/novu-go"
"github.com/novuhq/novu-go/models/components"

)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{ WorkflowID: "workflowId", To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{ SubscriberID: "subscriberId", Phone: novugo.String("+11111111111"), }), Payload: map[string]any{}, Overrides: map[string]any{ "chat": { "template": { "name": "template_name", "language": { "code": "en_US" } } } }, }, nil)

  </Tab>
  <Tab title="PHP">
```php
use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()->setSecurity('<NOVU_SECRET_KEY>')->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId', phone: '+11111111111'),
        payload: {},
        overrides: {
        "chat": {
                "template": {
                        "name": "template_name",
                        "language": {
                                "code": "en_US"
                        }
                }
        }
},
    ),
);

</Tab> <Tab title=".NET"> ```csharp using Novu; using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() { WorkflowId = "workflowId", To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() { SubscriberId = "subscriberId", Phone = "+11111111111" }), Payload = {}, Overrides = { "chat": { "template": { "name": "template_name", "language": { "code": "en_US" } } } }, });

  </Tab>
  <Tab title="Java">
```java
import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder().subscriberId("subscriberId").phone("+11111111111").build()))
        .payload({})
        .overrides({
        "chat": {
                "template": {
                        "name": "template_name",
                        "language": {
                                "code": "en_US"
                        }
                }
        }
})
        .build())
    .call();

</Tab> <Tab title="cURL"> ```bash curl --location 'https://api.novu.co/v1/events/trigger' \ --header 'Content-Type: application/json' \ --header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \ -d '{ "name": "workflowId", "to": { "subscriberId": "subscriberId", "phone": "+11111111111" }, "payload": {}, "overrides": { "chat": { "template": { "name": "template_name", "language": { "code": "en_US" } } } } }' ``` </Tab> </Tabs> </Step> </Steps>

Configure WhatsApp overrides

Save a WhatsApp Business override on the Chat step when you need Cloud API message shapes beyond the plain-text step body — for example templates, interactive buttons, or media. The override is stored on the step, so it is versioned and promoted with the workflow, and every trigger sends it without changing your trigger call.

<Note> Provider content overrides in the workflow editor are rolling out gradually and may not be available on your Chat step yet. Overrides passed at trigger time work regardless. See [provider content overrides](/platform/integrations/chat#provider-content-overrides). </Note> <Steps> <Step title="Open the Chat step"> In the [Novu Dashboard](https://dashboard.novu.co), open your workflow and select the Chat step that uses the WhatsApp Business integration. </Step> <Step title="Open the WhatsApp overrides editor"> In the step editor, open the content source dropdown — it reads **Default content** until you switch it — and pick **WhatsApp Business** under **Overrides**. If WhatsApp has no override yet, use the **+** beside it to add one. </Step> <Step title="Write the override JSON"> Enter a JSON object of [WhatsApp Cloud API Message](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages) fields. The editor autocompletes supported field names (`type`, `text`, `template`, `interactive`, media, `context`, and related bodies), validates the JSON, and flags unsupported fields. </Step> <Step title="Save the workflow"> The override applies on the next trigger. </Step> </Steps>

Override values may contain Liquid templates, which Novu compiles at send time:

json

{
  "type": "text",
  "text": {
    "body": "Order {{payload.orderId}} is {{payload.status}}"
  }
}

For text messages, text.body is the primary content field. If your override omits it, Novu fills it with the rendered Chat step body. Recipient addressing (to) is resolved from the subscriber endpoint — prefer addressing a different subscriber when you want a different destination.

Using WhatsApp with agents

WhatsApp is a supported agent provider. Connect your WhatsApp Business account to an agent so users can message your number and get replies in the same thread - without building Meta webhook handling yourself.

<Card title="Build agents on WhatsApp" icon="bot" href="/agents"> Learn how Novu agents work, including managed and custom code agents. </Card>

What you get

When WhatsApp is connected to an agent:

Users message your WhatsApp number and your agent responds in the same chat
Conversations appear in the dashboard under Agent Conversations
Supported content includes text, markdown, and interactive buttons; inbound media is surfaced via attachments

See agent conversations for capabilities across all providers.

Agent conversations vs. workflow notifications

Use case	What happens
Agent conversation	The user messages your WhatsApp number and your agent replies in the same chat.
Workflow notification	You trigger a workflow with a Chat step and Novu sends a one-way template message to the subscriber.

<Card icon="bot" href="/agents/get-started/agents-and-providers" title="Agents and providers"> Connect WhatsApp and other providers to an agent. </Card>

Getting Started

Going to production

Configure WhatsApp overrides

Using WhatsApp with agents

What you get

Agent conversations vs. workflow notifications

Related