Skip to content
Scalekit Docs

WhatsApp

scalekit36 toolsBearer TokenCommunication

Connect to the WhatsApp Business Cloud API to send and receive messages, manage media, message templates, phone numbers, and business profiles for...

WhatsApp connector

  1. Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Add your Scalekit credentials to your .env file. 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>
  3. 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.

    1. 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.
    2. 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.

        Create system user dialog with a system username and Employee role selected

    3. 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.

        System user detail panel showing the Assigned assets tab with no assets assigned yet

    4. 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_messaging and whatsapp_business_management permissions.

      • Click Generate token and copy the token immediately.

    5. 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.
  4. 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.actions
    const connector = 'whatsapp'
    const identifier = 'user_123'
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'whatsapp_businesses_list',
    toolInput: {},
    })
    console.log(result)

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

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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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).

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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).

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
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.

NameTypeRequiredDescription
waba_idstringrequiredThe WhatsApp Business Account ID.