​
Obtaining Credentials from Meta

Connecting Kapso requires specific IDs and a permanent access token obtained from Meta’s platforms. The process involves interacting with the Meta Developer Portal and potentially the Meta Business Suite/Manager.
Disclaimer: Meta’s interfaces and processes change frequently. Always consult Meta’s official WhatsApp Business Platform documentation as the primary source of truth. This guide outlines the general steps and concepts involved.

​
Step-by-Step Process

​
1. Set Up a Meta App

  • You need a Meta App registered in the Meta Developer Portal (developers.facebook.com).
  • If you don’t have one, create a new App, typically choosing the “Business” app type.

​
2. Add the WhatsApp Business Platform

  • Within your Meta App’s dashboard, add the “WhatsApp Business Platform” product.
  • This will link your Meta App to WhatsApp capabilities.

​
3. Configure the WhatsApp Product & Get IDs

  • During the WhatsApp product setup (or in its configuration settings later), you will link or select a Meta Business Account.
  • You will associate a specific Phone Number with this App for sending and receiving messages. This process often involves verifying the phone number.
  • Within the WhatsApp configuration section of your Meta App (often under “API Setup” or similar), you should be able to find:
    • The Phone Number ID: The unique identifier for the specific phone number linked to this App.
    • The WhatsApp Business Account (WABA) ID: The identifier for the overarching Business Account linked during setup.
  • Note: This section often displays a temporary access token. Do not use this temporary token for the Kapso configuration.

​
4. Create a System User

  • For a stable, long-term API connection, Meta recommends using System Users.
  • Navigate to your Meta Business Settings (often accessible via business.facebook.com).
  • Go to the “Users” section and select “System Users”.
  • Add a new System User. Give it an appropriate name (e.g., “Kapso API Access”) and assign it an “Admin” or appropriate role.

​
5. Assign Assets & Permissions

  • After creating the System User, you need to grant it access to the relevant WhatsApp assets.
  • Click “Add Assets” (or similar) for the System User.
  • Select “WhatsApp Accounts” and choose the specific WABA linked to your App.
  • Grant necessary permissions. You will typically need at least:
    • whatsapp_business_messaging (for sending/receiving messages)
    • whatsapp_business_management (for managing templates, settings etc.)
  • Ensure you grant “Full control” or sufficient permissions for these tasks.

​
6. Generate a Permanent Access Token

  • For the System User you just configured, find the option to “Generate new token”.
  • Select the Meta App you configured in steps 1-2.
  • Crucially, select the necessary permissions again when generating the token (specifically whatsapp_business_messaging and whatsapp_business_management).
  • Set the token expiration to Never. This ensures you get a permanent token suitable for server-to-server integration like Kapso.
  • Generate the token. Copy this token immediately and store it securely. Meta will only show it to you once.

​
Required Credentials Summary

You will need these three pieces of information for Kapso configuration:
  • Phone Number ID (from Meta App’s WhatsApp API Setup)
  • WhatsApp Business Account (WABA) ID (from Meta App’s WhatsApp API Setup or Business Settings)
  • Permanent System User Access Token (generated via Business Settings for a System User with correct permissions and ‘Never’ expiry)

​
Configuring WhatsApp in Kapso

After obtaining the necessary credentials from Meta, you need to configure them in Kapso and set up the webhook connection. This process involves both project-level and agent-level configurations.

​
Project-Level Configuration

WhatsApp connection details are managed at the Project level within Kapso. This allows a single project to potentially connect to multiple different WhatsApp phone numbers or business accounts if needed.
1

Go to WhatsApp Configurations

Access the “WhatsApp Configurations” area within your Kapso Project sidebar
2

Manage Configurations

Here you can view existing configurations, edit them, or create new ones
3

Create/Edit Configuration

When adding or editing a configuration, you will need to provide:
  • A recognizable Name for this specific configuration within Kapso (e.g., “Support Line”, “Sales Number”)
  • The Phone Number ID obtained from Meta
  • The WhatsApp Business Account (WABA) ID obtained from Meta
  • The Permanent System User Access Token obtained from Meta
  • A Custom Verify Token: You will define a unique, secret string here. This token acts like a password that Meta will use when sending messages to your Kapso webhook URL, ensuring the requests are legitimate. Copy this token immediately after creating it, as you will need to enter it into the Meta webhook settings
  • Webhook Endpoint (Optional): If you want to receive webhook events from WhatsApp in your own application, you can specify your endpoint URL here. Kapso will act as a proxy, forwarding WhatsApp events to your specified endpoint
4

Save

Save the configuration details in Kapso
Each saved configuration represents a specific WhatsApp phone number linked to your project.

​
Setting Up the Webhook in Meta

This step tells Meta where to send incoming WhatsApp messages and events so Kapso can receive them.
1

Go to Meta Developer Portal

Go to your App settings within the Meta Developer Portal
2

Find Webhooks

Locate the “Webhook” configuration section for the “WhatsApp Business API” product associated with your App
3

Configure Webhook

Callback URL: Use Kapso Webhook Callback URL https://meta-webhooks.kapso.ai/whatsapp
Verify Token: Paste the Webhook Verify Token that you copied from Kapso
4

Subscribe to Events

You need to subscribe to specific events. Ensure you subscribe at least to the messages event field. This ensures Kapso receives notifications for incoming user messages
5

Verify and Save

Click the “Verify and Save” button in Meta. Meta will send a test request to the Callback URL with the Verify Token. If Kapso receives it correctly (which it should if the URL and Token are correct), the webhook will be verified and saved
Kapso acts as a proxy between Meta and your application. When WhatsApp sends events to Kapso, if you’ve configured a webhook endpoint in your WhatsApp configuration, Kapso will forward these events to your specified endpoint while also processing them within the Kapso platform.

​
Agent-Level Configuration

After setting up a WhatsApp Configuration at the project level, you need to associate specific agents with it:
1

Go to Agent Settings

Go to the Agent settings page
2

Go to WhatsApp Settings

Find the WhatsApp configuration area for the agent (often a dedicated tab or section)
3

Link Configuration

Select the WhatsApp Configuration you created at the project level
4

Set as Primary (Optional)

You might designate this configuration as the “primary” one for the agent, meaning this agent will be responsible for handling inbound messages received on the associated phone number. If you want this agent to process all incoming messages, you must set it as the primary agent
5

Save

Save the agent’s WhatsApp association
Your Kapso agent should now be connected to WhatsApp, ready to process incoming messages and send responses based on your graph logic.