Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to WhatsApp

Scalekit connector
Open markdown

The WhatsApp connector lets your AI agent act in each user's WhatsApp account. Each user connects their own WhatsApp access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 36 tools.

Tools
36
What they doRead · write · destructive
13 · 18 · 513 read18 write5 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    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. Create the WhatsApp connection

    In AgentKit > Connections, create a WhatsApp connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    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. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'whatsapp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize WhatsApp:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'whatsapp_businesses_list',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their WhatsApp credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • whatsapp_business_account_getGet details for a WhatsApp Business Account, such as its name, currency, timezone, and message template namespace.Read-only

    Get Business Account

    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.

    Inputs

    waba_idstringrequired
    The WhatsApp Business Account ID.
    fieldsstring
    Comma-separated list of fields to return.
  • whatsapp_business_profile_getGet the WhatsApp Business Profile (about, address, description, email, vertical, websites, profile picture) for a phone number.Read-only

    Get Business Profile

    Get the WhatsApp Business Profile (about, address, description, email, vertical, websites, profile picture) for a phone number.

    Inputs

    phone_number_idstringrequired
    The WhatsApp Business phone number ID.
    fieldsstring
    Comma-separated list of fields to return.
  • whatsapp_businesses_listList the Meta Business Manager accounts the connected access token can act on.Read-only

    List Accessible Businesses

    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.

    Inputs

    fieldsstring
    Comma-separated list of fields to return per business.
    limitinteger
    Max number of businesses to return per page.
  • whatsapp_client_wabas_listList the WhatsApp Business Accounts (WABAs) shared with a Business Manager account through Embedded Signup, but not owned by it.Read-only

    List Client WhatsApp Business Accounts

    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.

    Inputs

    business_idstringrequired
    The Meta Business Manager account ID.
    fieldsstring
    Comma-separated list of fields to return per WABA.
    limitinteger
    Max number of WABAs to return per page.
  • whatsapp_media_get_urlRetrieve the temporary download URL and metadata for an uploaded or received WhatsApp media item.Read-only

    Get Media URL

    Retrieve the temporary download URL and metadata for an uploaded or received WhatsApp media item. The URL expires after 5 minutes.

    Inputs

    media_idstringrequired
    The WhatsApp media ID.
  • whatsapp_message_template_getGet a single message template's details by exact name, including approval status and components.Read-only

    Get Message Template

    Get a single message template's details by exact name, including approval status and components.

    Inputs

    namestringrequired
    Exact template name to look up.
    waba_idstringrequired
    The WhatsApp Business Account ID.
    fieldsstring
    Comma-separated list of fields to return.
  • whatsapp_message_templates_listList message templates configured on the WhatsApp Business Account, with optional filters.Read-only

    List Message Templates

    List message templates configured on the WhatsApp Business Account, with optional filters.

    Inputs

    waba_idstringrequired
    The WhatsApp Business Account ID.
    fieldsstring
    Comma-separated list of fields to return per template.
    limitinteger
    Max number of templates to return per page.
    statusstring
    Filter templates by status.
  • whatsapp_owned_wabas_listList the WhatsApp Business Accounts (WABAs) that a Business Manager account owns.Read-only

    List Owned WhatsApp Business Accounts

    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.

    Inputs

    business_idstringrequired
    The Meta Business Manager account ID.
    fieldsstring
    Comma-separated list of fields to return per WABA.
    limitinteger
    Max number of WABAs to return per page.
All 73 in Communication