Portal Community
BizFirstAI Portal / Nodes / WhatsApp / Authentication & Setup

Authentication & Setup

Meta app setup, access tokens, and the phoneNumberId credential pair

Every operation on this node authenticates as a request against Meta's Graph API on behalf of a WhatsApp Business Account (WABA). You need two things from Meta before the node can send a single message: an access token and a phone number ID.

1. Create a Meta App and Add the WhatsApp Product

  1. Create (or reuse) a Business app at developers.facebook.com/apps
  2. Add the WhatsApp product to the app
  3. Under WhatsApp → API Setup you'll see a test number, its Phone number ID, and a temporary 24-hour access token — enough to try Message Operations immediately

2. Get a Permanent Access Token

The 24-hour token from API Setup is for testing only. For anything running unattended:

  1. Create a System User in Meta Business Settings under your Business Account
  2. Assign the System User to the WhatsApp Business Account (WABA) with at least manage messages and manage phone numbers permissions
  3. Generate a permanent System User access token scoped to whatsapp_business_messaging and whatsapp_business_management

Config Fields

FieldRequiredDescription
accessToken✓ Yes*Bearer token for the Graph API call. May come from a vault credential instead — see below.
phoneNumberIdDepends on operationThe WhatsApp Business phone number sending/receiving on this call. Not a secret — safe as plain config. Required by messaging, media, profile, and most phone-number operations; not required by catalog/business-account-scoped commerce and template-management calls (they use catalogId/businessAccountId instead).

* Required for every operation, either inline or via vault.

Vault credential takes priority: the executor resolves accessToken in this order — (1) the configured vault credential (credentialID) if present and non-empty, (2) the inline accessToken config field. If neither resolves to a value, the operation fails with MISSING_ACCESS_TOKEN before any HTTP call is made. Store production tokens in the credential vault rather than inline config.

Which Operations Need phoneNumberId?

Two credential-validation paths exist internally:

PathValidatesUsed by
ApplyCredentialsAsyncaccessToken + phoneNumberIdAll message, media, profile, most phone-number, qrcode, and group operations — anything that sends or acts as a specific business phone number.
ApplyAccessTokenAsyncaccessToken onlyCatalog/business-account-scoped template and commerce operations that identify their target via catalogId, productId, collectionId, or businessAccountId instead.
Missing credential errors: a missing accessToken returns MISSING_ACCESS_TOKEN; a missing phoneNumberId (on an operation that needs it) returns MISSING_PHONE_NUMBER_ID. Both fail fast, before any Graph API request is sent.