Skip to main content

​
Create a test session

  1. Go to WhatsApp → Sandbox in your project
  2. Click Add Test Number
  3. Enter your WhatsApp phone number (the one you’ll test from)
  4. Click Create

​
Activate your session

After creating a session, you’ll see:
  • A 6-character activation code (e.g., “ABC123”)
  • The Kapso sandbox WhatsApp number
  • A direct link to start the conversation
To activate:
  1. Click the Open WhatsApp button
  2. Send your activation code as a message
  3. You’ll receive a confirmation message
Activation codes expire 15 minutes after the session is created. Create a new session to get a fresh code.

​
Move a number to another project

A phone number that is already active in another sandbox session can be claimed. Create a session for it in the new project, then send the activation code from WhatsApp. Once activated:
  • the new session becomes active
  • the previous session becomes superseded and its open sandbox conversations are closed
  • new inbound messages route only to the active session
The code must be sent from the phone number the session was created for.

​
Route to an agent

  1. Navigate to WhatsApp → Configurations in your project
  2. Find the Sandbox WhatsApp configuration (automatically created)
  3. Go to your agent settings
  4. Select Sandbox WhatsApp as the WhatsApp configuration
  5. Save the agent

​
Route to a flow

  1. Navigate to WhatsApp → Configurations in your project
  2. Find the Sandbox WhatsApp configuration (automatically created)
  3. Go to WhatsApp → Flows in your project
  4. Create or edit a flow
  5. Add an Inbound Message Trigger
  6. Select Sandbox WhatsApp as the WhatsApp configuration
  7. Deploy the flow

​
Route to webhooks

  1. Navigate to WhatsApp → Configurations in your project
  2. Find the Sandbox WhatsApp configuration (automatically created)
  3. Click on the Sandbox WhatsApp configuration
  4. Go to Manage Webhooks
  5. Add webhook URLs for the events you want to receive

​
Manage test sessions

Go to WhatsApp → Sandbox to view all sessions:
  • See which phone numbers are authorized
  • Check which agent/config each session uses
  • Delete sessions when done testing
Each session has a status: pending_activation (waiting for the code), active, or superseded (replaced by a newer session for the same number).

​
Limitations

The sandbox is for testing message flows, not production features.

​
Common errors

“Active sandbox session required to send messages” You’re sending to a number that isn’t registered in your sandbox session. The to field must match the phone number you added to your session. “Sync from WhatsApp” button disabled Template sync is not available for sandbox numbers. Connect a production number to sync templates. Can’t activate sandbox session
  • Verify you’re sending the exact 6-character code (case-sensitive)
  • Send from the phone number you registered, not a different device
  • Check the sandbox number is correct (displayed in your session)
  • Codes expire after 15 minutes — create a new session to get a fresh one