Sandbox

Sandbox

Zernio runs a shared WhatsApp sandbox number every account can test against without purchasing or verifying their own number. Use it to validate message flows, bot replies, and webhook payloads end-to-end before going live.

Why activation matters

Without ownership verification, anyone with a Zernio API key could fire the verified Meta template from +1 202 908 7457 at any phone they typed. That would degrade the WABA's quality rating (shared across all users) and drain its messaging tier. Activation closes the abuse vector: only phones the user proved they control via a WhatsApp reply can be targeted from the sandbox.

Step 1 — Discover the sandbox

The sandbox phone number, the SocialAccount id you need to send from, and the locked template name all come back from the standard phone-numbers endpoint:

const { data } = await zernio.phonenumbers.listPhoneNumbers();
if (!data.sandbox) throw new Error('Sandbox not configured on this environment');
const { accountId, phoneNumber, template } = data.sandbox;
// accountId → use as `accountId` in inbox compose calls
// phoneNumber → the sandbox MSISDN (display only)
// template   → { name: 'sandbox_start', language: 'en' }

Step 2 — Start activation for a test phone

Posting a phone creates a pending session and immediately fires the verified sandbox_start template from the sandbox number to that phone. The end user opens WhatsApp on their phone and replies to that message — any text reply (including tapping the "Reply and verify" quick-reply button) flips the session to active.

One phone per user: if you already have a pending or active session for a different phone, the request returns a 400 naming the existing phone so you know to revoke it first.

const { data } = await zernio.whatsappsandbox.createWhatsAppSandboxSession({
  body: { phone: '+34688246216' }
});
console.log(data.session.id, data.session.status); // 'pending'
// Tell the user: "Check WhatsApp on +34 688 24 62 16 and reply to verify"

Step 3 — Wait for the user to reply

Activation is automatic. You can poll the list endpoint, or — if you've configured webhooks — listen for the conversation events.

const { data } = await zernio.whatsappsandbox.listWhatsAppSandboxSessions();
const session = data.sessions[0];
if (session?.status === 'active') {
  console.log('Verified at', session.activatedAt);
}

Step 4 — Send to the activated phone

Once active, the phone is a normal WhatsApp conversation in the user's inbox. Send the locked template using the standard inbox compose endpoint, addressed at the sandbox account. The same template + activation gate applies — random phone numbers are rejected.

const { data } = await zernio.messages.createInboxConversation({
  body: {
    accountId: sandbox.accountId,
    participantId: '34688246216',           // digits only, must match the activated phone
    templateName: sandbox.template.name,    // 'sandbox_start'
    templateLanguage: sandbox.template.language, // 'en'
    templateParams: []
  }
});
console.log('Conversation:', data.data.id);

After the user replies, the 24h customer-service window opens — within that window you can send free-form text via POST /v1/inbox/conversations/{conversationId}/messages exactly like any other conversation.

Replacing the activated phone

Activate a different phone by deleting the current session first, then creating a new one:

# 1. Revoke the existing session
curl -X DELETE "https://zernio.com/api/v1/whatsapp/sandbox/sessions/SESSION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Start activation for the new phone
curl -X POST "https://zernio.com/api/v1/whatsapp/sandbox/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+34999888777"}'

Common errors