Manage your WhatsApp channel

Manage the Meta settings behind a connected WhatsApp channel without storing or handling its Meta access token. Wabery checks that the channel belongs to your project, selects its phone number and WhatsApp Business Account automatically, and returns Meta’s documented response fields.

Use a dedicated, connected Meta Cloud channel. Shared Sandbox channels are not eligible because their Meta assets belong to Wabery.

Operation reference

Every operation is available through the named SDK method, the generic SDK get() or mutate() method, the REST endpoint, and the two WhatsApp management MCP tools. Inputs in the tables use the REST and Meta-style snake_case names accepted by the generic method and MCP.

Reads

SDK method	Operation	Input	Result
getBusinessProfile(channelId)	business_profile	None	About, address, description, email, profile picture URL, websites, and vertical.
getCommerceSettings(channelId)	commerce_settings	None	Cart and catalog visibility for the number.
listQrCodes(channelId, options)	qr_codes	Optional format, limit, after, before	QR codes for the number. format is PNG or SVG.
getQrCode(channelId, qrCodeId, options)	qr_code	qr_code_id; optional format	One QR code owned by the number.
getWebhookSubscriptions(channelId)	webhook_subscriptions	None	Provider webhook subscriptions associated with the channel’s WABA. Normal channel connection configures delivery automatically.
getPhoneNumber(channelId)	phone_number	None	Display number, verified name, quality, registration/name status, platform, and throughput.
listPhoneNumbers(channelId, options)	phone_numbers	Optional pagination	Phone numbers under the connected WABA.
getWaba(channelId)	waba	None	WABA identity, currency, timezone, review, verification, ownership, and funding metadata.
listOwnedWabas(channelId, options)	owned_wabas	Optional pagination	The connected WABA when it is owned by the channel’s business. Wabery filters out unrelated accounts.
listSharedWabas(channelId, options)	shared_wabas	Optional pagination	The connected WABA when it is shared with the channel’s business. Wabery filters out unrelated accounts.
listAssignedUsers(channelId, options)	assigned_users	Optional pagination	Business users assigned to the connected WABA.
getAnalytics(channelId, fields)	analytics	One fields expression	Meta analytics or conversation_analytics data.
getCallAnalytics(channelId, fields)	analytics	One call_analytics expression	Calling analytics. This named method uses the same validated analytics operation.
getCreditLines(channelId, options)	credit_lines	Optional pagination	Funding diagnostics for the owning business. Read-only.
getCreditLineAllocation(channelId, allocationId)	credit_line_allocation	allocation_id	One allocation, returned only when it belongs to this channel’s WABA. Read-only.
getCallingSettings(channelId, options)	calling_settings	Optional include_sip_credentials	Calling, visibility, permission, hours, and SIP settings returned by Meta.
getCallPermissions(channelId, userWaId)	call_permissions	user_wa_id	The current call-permission state for one WhatsApp user.
listBlockedUsers(channelId, options)	blocked_users	Optional pagination	WhatsApp user IDs blocked by this business number.

Pagination accepts limit from 1–100 and opaque after or before cursors. Do not construct a cursor from an item ID. Follow the cursor Meta returns.

Analytics accepts exactly one Meta expression beginning with analytics., conversation_analytics., or call_analytics.. Wabery rejects multiple top-level expressions and malformed brackets before sending the request to Meta.

Writes

SDK method	Operation	Required input	Effect
updateBusinessProfile(channelId, input)	update_business_profile	At least one supported profile field	Updates about, address, description, email, profile_picture_handle, websites, or vertical.
updateCommerceSettings(channelId, input)	update_commerce_settings	is_cart_enabled and/or is_catalog_visible boolean	Changes cart or catalog visibility.
createQrCode(channelId, input)	create_qr_code	prefilled_message; optional generate_qr_image	Creates a QR code and optionally returns a PNG or SVG image.
updateQrCode(channelId, qrCodeId, input)	update_qr_code	qr_code_id, prefilled_message	Replaces the prefilled message for a QR code.
deleteQrCode(channelId, qrCodeId)	delete_qr_code	qr_code_id	Permanently deletes the QR code in Meta.
deleteMedia(channelId, mediaId)	delete_media	media_id	Deletes Meta-hosted media owned by this phone number.
registerPhone(channelId, pin)	register_phone	Six-digit pin	Registers the phone with Cloud API using two-step verification.
deregisterPhone(channelId)	deregister_phone	None	Deregisters the number from Cloud API and interrupts messaging.
requestVerificationCode(channelId, input)	request_verification_code	code_method (SMS or VOICE), locale	Requests a Meta verification code.
verifyCode(channelId, code)	verify_code	Six-digit code	Verifies the code most recently requested for the number.
setTwoStepVerification(channelId, pin)	set_two_step_verification	Six-digit pin	Replaces the number’s Cloud API two-step verification PIN. Store it securely.
subscribeWebhooks(channelId)	subscribe_webhooks	None	Restores Wabery event delivery for the channel’s WABA. Normal channel connection runs this automatically.
unsubscribeWebhooks(channelId)	unsubscribe_webhooks	None	Detaches the app and stops Wabery from receiving that WABA’s events.
overrideWebhookCallback(channelId, input)	override_webhook_callback	override_callback_uri, verify_token	Overrides this app subscription’s callback. An incorrect URL stops inbound delivery.
assignWabaUser(channelId, input)	assign_waba_user	user, non-empty tasks containing MANAGE and/or DEVELOP	Assigns a business user to the WABA.
unassignWabaUser(channelId, user)	unassign_waba_user	user	Removes the business user’s WABA assignment.
updateCallingSettings(channelId, input)	update_calling_settings	Meta calling settings	Changes per-number calling configuration. See WhatsApp Calling.
manageCall(channelId, input)	manage_call	Meta call action and action-specific fields	Connects, pre-accepts, accepts, rejects, or terminates a call. Wabery supplies messaging_product.
blockUsers(channelId, users)	block_users	Non-empty users array	Blocks the supplied WhatsApp user IDs on the business number.
unblockUsers(channelId, users)	unblock_users	Non-empty users array	Removes those IDs from the business number’s block list.

The SDK validates strongly shaped convenience inputs such as pagination, commerce booleans, QR formats, assignment tasks, and verification codes. Calling settings and call actions remain forward-compatible Meta objects because their country- and account-dependent fields can change independently of Wabery.

Read channel settings

const profile = await wabery.whatsappManagement.getBusinessProfile("channel_...");

const commerce = await wabery.whatsappManagement.getCommerceSettings("channel_...");

const qrCodes = await wabery.whatsappManagement.listQrCodes("channel_...");

The generic read method covers every supported management resource:

await wabery.whatsappManagement.get("channel_...", "phone_number");
await wabery.whatsappManagement.get("channel_...", "waba");
await wabery.whatsappManagement.get("channel_...", "analytics", {
  fields: "analytics.start(1767225600).end(1769817600).granularity(DAY)",
});

await wabery.whatsappManagement.getCallAnalytics(
  "channel_...",
  "call_analytics.start(1767225600).end(1769817600).granularity(DAY)",
);

For WhatsApp Calling, configure the phone with update_calling_settings, send call_permission_request before a business-initiated call, inspect permission with call_permissions, and pass Meta’s SDP call action to manage_call. Wabery handles channel ownership and credentials; your voice stack still owns WebRTC or SIP media. Follow the complete WhatsApp Calling guide before enabling a production number.

Pass { includeSipCredentials: true } to getCallingSettings() only when your SIP integration needs Meta’s credentials. Treat the response as a secret and do not log or send it to a browser.

await wabery.messages.send({
  channelId: "channel_...",
  to: "+15551234567",
  idempotencyKey: "call-permission-customer-123",
  interactive: {
    type: "call_permission_request",
    action: { name: "call_permission_request" },
  },
});

await wabery.messages.send({
  channelId: "channel_...",
  to: "+15551234567",
  idempotencyKey: "call-button-customer-123",
  interactive: {
    type: "voice_call",
    body: { text: "Call our support team" },
    action: {
      name: "voice_call",
      parameters: { display_text: "Call now" },
    },
  },
});

The voice_call message displays a button that lets the user call you. It does not place a business-initiated call. To call the user, obtain permission and send a connect action through manageCall() with your WebRTC SDP offer or corresponding Meta session data.

Call lifecycle and signaling updates arrive at your project webhook as the typed SDK event call.event. Its payload.kind tells you whether Meta sent a call lifecycle item or a business-initiated call status. payload.call is the original item, so SDP, connection, status, and callback fields remain available; payload.errors preserves any call errors. Delivery uses the same signature, retry, and idempotency guarantees as other Wabery webhooks.

Change settings

await wabery.whatsappManagement.updateBusinessProfile("channel_...", {
  about: "Friendly support from the Acme team",
  email: "support@example.com",
  websites: ["https://example.com"],
  vertical: "RETAIL",
});

await wabery.whatsappManagement.updateCommerceSettings("channel_...", {
  is_cart_enabled: true,
  is_catalog_visible: true,
});

Use mutate() for registration, QR-code, webhook, and calling operations:

await wabery.whatsappManagement.mutate(
  "channel_...",
  "set_two_step_verification",
  { pin: "123456" },
);

await wabery.whatsappManagement.deleteMedia("channel_...", "media_...");

Credit-line and funding information is read-only. Wabery does not attach its own or another provider’s credit line to your WABA. You keep your payment method in Meta and Meta bills you directly.

Cuidado

Deregistering a phone, deleting media or QR codes, and removing webhook subscriptions change Meta immediately. MCP asks you to confirm management writes before it runs them. The SDK and REST API execute authorized writes immediately.

REST API

Read an operation with:

GET /v1/channels/{channel_id}/whatsapp-management?operation=business_profile

Run a write with:

POST /v1/channels/{channel_id}/whatsapp-management
Content-Type: application/json

{
  "operation": "create_qr_code",
  "input": {
    "prefilled_message": "Hello, I need help",
    "generate_qr_image": "PNG"
  }
}

MCP

Use wabery_get_whatsapp_management for reads and wabery_manage_whatsapp for changes. The MCP server keeps destructive writes behind its normal write-mode and confirmation checks.

The read tool accepts { channel_id, operation, params }; put query inputs such as qr_code_id, fields, user_wa_id, or pagination in params. The write tool accepts { channel_id, operation, input }; put the fields from the write table in input.

Hosted MCP requests a person-controlled approval before a write. Trusted local MCP must run in write mode and uses confirmation_token: "manage_whatsapp" when the client does not support elicitation. Reads need neither.

Responses and errors

Management responses preserve Meta’s documented fields so you can adopt a new provider response field without waiting for Wabery to rename it. The SDK return type is WhatsAppManagementResponse, a JSON object with Meta’s response plus Wabery’s transport guarantees.

Wabery validates channel ownership before contacting Meta. Invalid local input returns 400; a missing channel asset or credential returns 409; and Meta permission, ownership, or provider errors retain meta_code and fbtrace_id when Meta supplies them. Do not log access tokens, verification PINs, SIP credentials, or webhook verify tokens with an error.

Meta availability

Calling and payment features are account- and country-dependent. Wabery passes the request through only for the connected channel; Meta remains the source of truth for eligibility, supported fields, availability, and charges. A Meta permission or eligibility failure is returned with meta_code and fbtrace_id when Meta supplies them.

Payments are message operations rather than channel-management operations. For Meta’s India and Singapore APIs, see Regional payment messages.