Connect to the WhatsApp Business Cloud API to send and receive messages, manage media, message templates, phone numbers, and business profiles for...
WhatsApp connector
-
Install the SDK
Section titled “Install the SDK”Terminal window npm install @scalekit-sdk/nodeTerminal window pip install scalekit -
Set your credentials
Section titled “Set your credentials”Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret> -
Set up the connector
Section titled “Set up the connector”Register your WhatsApp credentials with Scalekit so it can authenticate requests on your behalf. You do this once per environment.
Dashboard setup steps
Generate a permanent access token for a Meta system user so Scalekit can call the WhatsApp Business Cloud API on your behalf. System user tokens don’t expire on their own like standard user tokens, which makes them the right fit for a server-to-server connection.
-
Open System users in Meta Business Settings
- Go to Meta Business Settings for the business portfolio that owns your WhatsApp Business Account.
- Under Users, click System users.
-
Create a system user
-
Click Add, then Create system user.
-
Give it a name (for example,
Scalekit) and set the System user role to Employee. -
Click Create system user.

-
-
Assign your WhatsApp Business Account to the system user
-
Select the system user you just created from the list.
-
Click Assign assets, choose WhatsApp accounts, and select the WhatsApp Business Account you want Scalekit to access.
-
Grant Full control so the system user can send and receive messages, and manage templates and phone numbers.

-
-
Generate the access token
-
With the system user still selected, click Generate token.
-
Select your WhatsApp app, set an expiration (choose Never for a long-lived server-to-server connection), and select the
whatsapp_business_messagingandwhatsapp_business_managementpermissions. -
Click Generate token and copy the token immediately.
-
-
Add the token in Scalekit
- In the Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find WhatsApp and click Create.
- Paste the system user access token you copied and click Save.
-
-
Make your first call
Section titled “Make your first call”quickstart.ts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENV_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'whatsapp'const identifier = 'user_123'// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'whatsapp_businesses_list',toolInput: {},})console.log(result)quickstart.py import osfrom scalekit.client import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENV_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "whatsapp"identifier = "user_123"# Make your first callresult = actions.execute_tool(tool_input={},tool_name="whatsapp_businesses_list",connection_name=connection_name,identifier=identifier,)print(result)
What you can do
Section titled “What you can do”Connect this agent connector to let your agent:
- Unsubscribe subscribed apps — Unsubscribe this app from webhook events for a WhatsApp Business Account, stopping delivery of messages and status updates
- Subscribe subscribed apps — Subscribe this app to receive webhook events (messages, status updates) for a WhatsApp Business Account, optionally overriding the callback URL for just this WABA
- List subscribed apps, qr codes, phone numbers — List the apps currently subscribed to webhook events for a WhatsApp Business Account
- Send text message, template message, reaction message — Send a plain text WhatsApp message to a recipient
- Update qr code, message template, business profile — Update the pre-filled message on an existing WhatsApp QR code or short link
- Get qr code, phone number, message template — Get a single WhatsApp QR code or short link by its code id
Tool list
Section titled “Tool list”Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.
whatsapp_business_account_get#Get details for a WhatsApp Business Account, such as its name, currency, timezone, and message template namespace.
Returns the requested fields as a JSON object.
Use whatsapp_phone_numbers_list to see the phone numbers under this account.2 params
Get details for a WhatsApp Business Account, such as its name, currency, timezone, and message template namespace. Returns the requested fields as a JSON object. Use whatsapp_phone_numbers_list to see the phone numbers under this account.
waba_idstringrequiredThe WhatsApp Business Account ID.fieldsstringoptionalComma-separated list of fields to return.whatsapp_business_profile_get#Get the WhatsApp Business Profile (about, address, description, email, vertical, websites, profile picture) for a phone number.2 params
Get the WhatsApp Business Profile (about, address, description, email, vertical, websites, profile picture) for a phone number.
phone_number_idstringrequiredThe WhatsApp Business phone number ID.fieldsstringoptionalComma-separated list of fields to return.whatsapp_business_profile_update#Update the WhatsApp Business Profile fields for a phone number.7 params
Update the WhatsApp Business Profile fields for a phone number.
phone_number_idstringrequiredThe WhatsApp Business phone number ID.aboutstringoptionalShort business description (max 139 characters).addressstringoptionalBusiness address.descriptionstringoptionalBusiness description.emailstringoptionalBusiness contact email.verticalstringoptionalIndustry vertical.websitesarrayoptionalUp to 2 business website URLs.whatsapp_businesses_list#List the Meta Business Manager accounts the connected access token can act on.
Returns each business's id and name.
Start here to discover a business_id, then use whatsapp_owned_wabas_list or whatsapp_client_wabas_list to find WhatsApp Business Account ids under it.2 params
List the Meta Business Manager accounts the connected access token can act on. Returns each business's id and name. Start here to discover a business_id, then use whatsapp_owned_wabas_list or whatsapp_client_wabas_list to find WhatsApp Business Account ids under it.
fieldsstringoptionalComma-separated list of fields to return per business.limitintegeroptionalMax number of businesses to return per page.whatsapp_client_wabas_list#List the WhatsApp Business Accounts (WABAs) shared with a Business Manager account through Embedded Signup, but not owned by it.
Returns each WABA's id, name, message template namespace, and timezone.
Use whatsapp_businesses_list first to find the business_id. Use whatsapp_owned_wabas_list instead for WABAs this business owns directly.3 params
List the WhatsApp Business Accounts (WABAs) shared with a Business Manager account through Embedded Signup, but not owned by it. Returns each WABA's id, name, message template namespace, and timezone. Use whatsapp_businesses_list first to find the business_id. Use whatsapp_owned_wabas_list instead for WABAs this business owns directly.
business_idstringrequiredThe Meta Business Manager account ID.fieldsstringoptionalComma-separated list of fields to return per WABA.limitintegeroptionalMax number of WABAs to return per page.whatsapp_mark_message_read#Mark an inbound WhatsApp message as read (shows blue ticks to the sender).2 params
Mark an inbound WhatsApp message as read (shows blue ticks to the sender).
message_idstringrequiredThe WhatsApp message ID (wamid) of the inbound message to mark as read.phone_number_idstringrequiredThe WhatsApp Business phone number ID that received the message.whatsapp_media_delete#Delete a previously uploaded WhatsApp media item.1 param
Delete a previously uploaded WhatsApp media item.
media_idstringrequiredThe WhatsApp media ID to delete.whatsapp_media_get_url#Retrieve the temporary download URL and metadata for an uploaded or received WhatsApp media item. The URL expires after 5 minutes.1 param
Retrieve the temporary download URL and metadata for an uploaded or received WhatsApp media item. The URL expires after 5 minutes.
media_idstringrequiredThe WhatsApp media ID.whatsapp_message_template_create#Create a new WhatsApp message template and submit it for Meta review. Must be approved before it can be used to send messages.5 params
Create a new WhatsApp message template and submit it for Meta review. Must be approved before it can be used to send messages.
categorystringrequiredTemplate category.componentsarrayrequiredArray of component objects (header/body/footer/button) defining the template's content and variable placeholders.languagestringrequiredLanguage code for the template.namestringrequiredTemplate name — lowercase alphanumeric and underscores only.waba_idstringrequiredThe WhatsApp Business Account ID to create the template under.whatsapp_message_template_delete#Delete a message template by name, optionally scoped to a single language version.
Returns a success confirmation.
Use whatsapp_message_templates_list first to find the exact name. Provide template_id together with name to remove only that language; name alone removes every language.3 params
Delete a message template by name, optionally scoped to a single language version. Returns a success confirmation. Use whatsapp_message_templates_list first to find the exact name. Provide template_id together with name to remove only that language; name alone removes every language.
namestringrequiredExact template name to delete.waba_idstringrequiredThe WhatsApp Business Account ID.template_idstringoptionalNumeric id of one specific language version to delete. Omit to delete all languages of this template name.whatsapp_message_template_get#Get a single message template's details by exact name, including approval status and components.3 params
Get a single message template's details by exact name, including approval status and components.
namestringrequiredExact template name to look up.waba_idstringrequiredThe WhatsApp Business Account ID.fieldsstringoptionalComma-separated list of fields to return.whatsapp_message_template_update#Edit an existing message template's category and/or components.
Returns the template's updated status, which resets to pending Meta review.
Use whatsapp_message_template_get or whatsapp_message_templates_list first to find the template's numeric id.3 params
Edit an existing message template's category and/or components. Returns the template's updated status, which resets to pending Meta review. Use whatsapp_message_template_get or whatsapp_message_templates_list first to find the template's numeric id.
template_idstringrequiredNumeric id of the template to update (not its name).categorystringoptionalNew template category.componentsarrayoptionalReplacement array of component objects (header/body/footer/button) defining the template's content.whatsapp_message_templates_list#List message templates configured on the WhatsApp Business Account, with optional filters.4 params
List message templates configured on the WhatsApp Business Account, with optional filters.
waba_idstringrequiredThe WhatsApp Business Account ID.fieldsstringoptionalComma-separated list of fields to return per template.limitintegeroptionalMax number of templates to return per page.statusstringoptionalFilter templates by status.whatsapp_owned_wabas_list#List the WhatsApp Business Accounts (WABAs) that a Business Manager account owns.
Returns each WABA's id, name, message template namespace, and timezone.
Use whatsapp_businesses_list first to find the business_id. Use whatsapp_client_wabas_list instead for WABAs shared with this business rather than owned by it.3 params
List the WhatsApp Business Accounts (WABAs) that a Business Manager account owns. Returns each WABA's id, name, message template namespace, and timezone. Use whatsapp_businesses_list first to find the business_id. Use whatsapp_client_wabas_list instead for WABAs shared with this business rather than owned by it.
business_idstringrequiredThe Meta Business Manager account ID.fieldsstringoptionalComma-separated list of fields to return per WABA.limitintegeroptionalMax number of WABAs to return per page.whatsapp_phone_number_deregister#Deregister a phone number from the Cloud API, stopping it from sending or receiving messages until re-registered.
Returns a success confirmation.
Use whatsapp_phone_number_register to re-register the number afterward.1 param
Deregister a phone number from the Cloud API, stopping it from sending or receiving messages until re-registered. Returns a success confirmation. Use whatsapp_phone_number_register to re-register the number afterward.
phone_number_idstringrequiredThe WhatsApp Business phone number ID to deregister.whatsapp_phone_number_get#Get metadata for a WhatsApp Business phone number (verification status, quality rating, display number).2 params
Get metadata for a WhatsApp Business phone number (verification status, quality rating, display number).
phone_number_idstringrequiredThe WhatsApp Business phone number ID.fieldsstringoptionalComma-separated list of fields to return.whatsapp_phone_number_register#Complete Cloud API registration for a phone number after its ownership is verified, setting its two-step verification PIN.
Returns a success confirmation.
Use after whatsapp_phone_number_verify_code. Use whatsapp_phone_number_deregister to reverse this.2 params
Complete Cloud API registration for a phone number after its ownership is verified, setting its two-step verification PIN. Returns a success confirmation. Use after whatsapp_phone_number_verify_code. Use whatsapp_phone_number_deregister to reverse this.
phone_number_idstringrequiredThe WhatsApp Business phone number ID to register.pinstringrequiredA 6-digit PIN used for two-step verification on this phone number.whatsapp_phone_number_request_code#Request an SMS or voice verification code to confirm ownership of a phone number before registering it with the Cloud API.
Returns a success confirmation.
Run this before whatsapp_phone_number_verify_code and whatsapp_phone_number_register when adding a new number.3 params
Request an SMS or voice verification code to confirm ownership of a phone number before registering it with the Cloud API. Returns a success confirmation. Run this before whatsapp_phone_number_verify_code and whatsapp_phone_number_register when adding a new number.
code_methodstringrequiredHow to deliver the verification code.languagestringrequiredLocale for the verification message.phone_number_idstringrequiredThe WhatsApp Business phone number ID to verify.whatsapp_phone_number_set_pin#Set or update the two-step verification PIN for a WhatsApp Business phone number.
Returns a success confirmation.
Another user re-registering this phone number will need this PIN. There is no API to disable two-step verification once set.2 params
Set or update the two-step verification PIN for a WhatsApp Business phone number. Returns a success confirmation. Another user re-registering this phone number will need this PIN. There is no API to disable two-step verification once set.
phone_number_idstringrequiredThe WhatsApp Business phone number ID.pinstringrequiredNew 6-digit two-step verification PIN.whatsapp_phone_number_verify_code#Submit the verification code received via SMS or voice call to confirm ownership of a phone number.
Returns a success confirmation.
Use after whatsapp_phone_number_request_code. Follow with whatsapp_phone_number_register to complete registration.2 params
Submit the verification code received via SMS or voice call to confirm ownership of a phone number. Returns a success confirmation. Use after whatsapp_phone_number_request_code. Follow with whatsapp_phone_number_register to complete registration.
codestringrequiredThe verification code received via SMS or voice call.phone_number_idstringrequiredThe WhatsApp Business phone number ID being verified.whatsapp_phone_numbers_list#List the phone numbers registered under a WhatsApp Business Account.
Returns each number's id, display number, verified name, and quality rating.
Use whatsapp_phone_number_get for a single phone number's full details.3 params
List the phone numbers registered under a WhatsApp Business Account. Returns each number's id, display number, verified name, and quality rating. Use whatsapp_phone_number_get for a single phone number's full details.
waba_idstringrequiredThe WhatsApp Business Account ID.fieldsstringoptionalComma-separated list of fields to return per phone number.limitintegeroptionalMax number of phone numbers to return per page.whatsapp_qr_code_create#Create a WhatsApp QR code or short link pre-filled with a message, for customers to start a chat.
Returns the code id, prefilled message, deep link URL, and optionally a QR image URL.
Use whatsapp_qr_code_update to change an existing code's message instead of creating a duplicate.3 params
Create a WhatsApp QR code or short link pre-filled with a message, for customers to start a chat. Returns the code id, prefilled message, deep link URL, and optionally a QR image URL. Use whatsapp_qr_code_update to change an existing code's message instead of creating a duplicate.
phone_number_idstringrequiredThe WhatsApp Business phone number ID the code should message.prefilled_messagestringrequiredMessage text pre-filled when a customer opens the chat (max 140 characters).generate_qr_imagestringoptionalImage format for a generated QR code image.whatsapp_qr_code_delete#Delete a WhatsApp QR code or short link.
Returns a success confirmation.
Use whatsapp_qr_codes_list to find the code id first.2 params
Delete a WhatsApp QR code or short link. Returns a success confirmation. Use whatsapp_qr_codes_list to find the code id first.
phone_number_idstringrequiredThe WhatsApp Business phone number ID.qr_code_idstringrequiredThe QR code's id to delete.whatsapp_qr_code_get#Get a single WhatsApp QR code or short link by its code id.
Returns the prefilled message and deep link URL.
Use whatsapp_qr_codes_list to find the code id first.2 params
Get a single WhatsApp QR code or short link by its code id. Returns the prefilled message and deep link URL. Use whatsapp_qr_codes_list to find the code id first.
phone_number_idstringrequiredThe WhatsApp Business phone number ID.qr_code_idstringrequiredThe QR code's id.whatsapp_qr_code_update#Update the pre-filled message on an existing WhatsApp QR code or short link.
Returns the code id, updated prefilled message, and deep link URL.
Use whatsapp_qr_codes_list or whatsapp_qr_code_get to find the code id first.3 params
Update the pre-filled message on an existing WhatsApp QR code or short link. Returns the code id, updated prefilled message, and deep link URL. Use whatsapp_qr_codes_list or whatsapp_qr_code_get to find the code id first.
phone_number_idstringrequiredThe WhatsApp Business phone number ID.prefilled_messagestringrequiredNew pre-filled message text (max 140 characters).qr_code_idstringrequiredThe QR code's id to update.whatsapp_qr_codes_list#List all WhatsApp QR codes and short links created for a phone number.
Returns each code's id, prefilled message, and deep link URL.
Use whatsapp_qr_code_get for a single code's full details.1 param
List all WhatsApp QR codes and short links created for a phone number. Returns each code's id, prefilled message, and deep link URL. Use whatsapp_qr_code_get for a single code's full details.
phone_number_idstringrequiredThe WhatsApp Business phone number ID.whatsapp_send_contacts_message#Send one or more WhatsApp contact cards to a recipient.
Returns the message id once accepted by Meta.
Use whatsapp_send_text_message for plain text instead. Only deliverable within the 24-hour customer service window; use whatsapp_send_template_message to start a new conversation.3 params
Send one or more WhatsApp contact cards to a recipient. Returns the message id once accepted by Meta. Use whatsapp_send_text_message for plain text instead. Only deliverable within the 24-hour customer service window; use whatsapp_send_template_message to start a new conversation.
contactsarrayrequiredArray of contact card objects (name, phones, emails, org, etc.) following WhatsApp's contact schema.phone_number_idstringrequiredThe WhatsApp Business phone number ID sending the message.tostringrequiredRecipient's WhatsApp ID or phone number in E.164 format.whatsapp_send_interactive_message#Send an interactive WhatsApp message — reply buttons, a list menu, or a call-to-action URL button.
Returns the message id once accepted by Meta.
Use whatsapp_send_text_message for plain text. Only deliverable within the 24-hour customer service window; use whatsapp_send_template_message to start a new conversation.3 params
Send an interactive WhatsApp message — reply buttons, a list menu, or a call-to-action URL button. Returns the message id once accepted by Meta. Use whatsapp_send_text_message for plain text. Only deliverable within the 24-hour customer service window; use whatsapp_send_template_message to start a new conversation.
interactiveobjectrequiredThe full interactive object: type (button, list, or cta_url), optional header/footer, body, and action.phone_number_idstringrequiredThe WhatsApp Business phone number ID sending the message.tostringrequiredRecipient's WhatsApp ID or phone number in E.164 format.whatsapp_send_location_message#Send a WhatsApp message containing a map pin for a specific location.
Returns the message id once accepted by Meta.
Only deliverable within the 24-hour customer service window; use whatsapp_send_template_message to start a new conversation.6 params
Send a WhatsApp message containing a map pin for a specific location. Returns the message id once accepted by Meta. Only deliverable within the 24-hour customer service window; use whatsapp_send_template_message to start a new conversation.
latitudenumberrequiredLocation latitude.longitudenumberrequiredLocation longitude.phone_number_idstringrequiredThe WhatsApp Business phone number ID sending the message.tostringrequiredRecipient's WhatsApp ID or phone number in E.164 format.addressstringoptionalAddress of the location.namestringoptionalName of the location.whatsapp_send_media_message#Send an image, video, document, or audio WhatsApp message, referencing media either by an uploaded media_id or a public link.7 params
Send an image, video, document, or audio WhatsApp message, referencing media either by an uploaded media_id or a public link.
media_typestringrequiredType of media being sent.phone_number_idstringrequiredThe WhatsApp Business phone number ID sending the message.tostringrequiredRecipient's WhatsApp ID or phone number in E.164 format.captionstringoptionalCaption text. Supported for image, video, and document — not audio.filenamestringoptionalFilename to display. Only used for document media.media_idstringoptionalID of a previously uploaded media file. Provide this or media_link, not both.media_linkstringoptionalPublicly accessible URL of the media file. Provide this or media_id, not both.whatsapp_send_reaction_message#Send an emoji reaction to a previously received WhatsApp message, or remove a reaction with an empty emoji.
Returns the message id once accepted by Meta.
Use whatsapp_mark_message_read to acknowledge a message without reacting to it.4 params
Send an emoji reaction to a previously received WhatsApp message, or remove a reaction with an empty emoji. Returns the message id once accepted by Meta. Use whatsapp_mark_message_read to acknowledge a message without reacting to it.
emojistringrequiredA single emoji to react with. Pass an empty string to remove a previous reaction.message_idstringrequiredThe WhatsApp message ID (wamid) being reacted to.phone_number_idstringrequiredThe WhatsApp Business phone number ID sending the reaction.tostringrequiredRecipient's WhatsApp ID or phone number in E.164 format.whatsapp_send_template_message#Send a pre-approved WhatsApp message template. Required to initiate contact with a recipient outside the 24-hour customer service window.5 params
Send a pre-approved WhatsApp message template. Required to initiate contact with a recipient outside the 24-hour customer service window.
language_codestringrequiredLanguage code the template was approved in.phone_number_idstringrequiredThe WhatsApp Business phone number ID sending the message.template_namestringrequiredName of the approved message template.tostringrequiredRecipient's WhatsApp ID or phone number in E.164 format.componentsarrayoptionalArray of template component objects (header/body/button parameters) matching the template's variable placeholders.whatsapp_send_text_message#Send a plain text WhatsApp message to a recipient.4 params
Send a plain text WhatsApp message to a recipient.
bodystringrequiredThe message text (max 4096 characters).phone_number_idstringrequiredThe WhatsApp Business phone number ID sending the message.tostringrequiredRecipient's WhatsApp ID or phone number in E.164 format.preview_urlbooleanoptionalWhether to render a link preview if the text contains a URL.whatsapp_subscribed_apps_list#List the apps currently subscribed to webhook events for a WhatsApp Business Account.
Returns each subscribed app's id, name, and any override callback URI.
Use whatsapp_subscribed_apps_subscribe to add this app to the list.1 param
List the apps currently subscribed to webhook events for a WhatsApp Business Account. Returns each subscribed app's id, name, and any override callback URI. Use whatsapp_subscribed_apps_subscribe to add this app to the list.
waba_idstringrequiredThe WhatsApp Business Account ID.whatsapp_subscribed_apps_subscribe#Subscribe this app to receive webhook events (messages, status updates) for a WhatsApp Business Account, optionally overriding the callback URL for just this WABA.
Returns the subscription record, including the app id and any override callback URI.
Use whatsapp_subscribed_apps_list to see current subscriptions, or whatsapp_subscribed_apps_unsubscribe to remove one.3 params
Subscribe this app to receive webhook events (messages, status updates) for a WhatsApp Business Account, optionally overriding the callback URL for just this WABA. Returns the subscription record, including the app id and any override callback URI. Use whatsapp_subscribed_apps_list to see current subscriptions, or whatsapp_subscribed_apps_unsubscribe to remove one.
waba_idstringrequiredThe WhatsApp Business Account ID.override_callback_uristringoptionalA callback URL to use for this WABA instead of the app's default webhook URL.verify_tokenstringoptionalVerification token Meta will echo back when validating the override callback URI.whatsapp_subscribed_apps_unsubscribe#Unsubscribe this app from webhook events for a WhatsApp Business Account, stopping delivery of messages and status updates.
Returns a success confirmation.
Use whatsapp_subscribed_apps_list to confirm current subscriptions first.1 param
Unsubscribe this app from webhook events for a WhatsApp Business Account, stopping delivery of messages and status updates. Returns a success confirmation. Use whatsapp_subscribed_apps_list to confirm current subscriptions first.
waba_idstringrequiredThe WhatsApp Business Account ID.