Get started

Sandbox

Try the API without connecting your own number. Your WhatsApp joins the heysteff shared number and an sk_test_ key sends messages to it there. Your replies reach your webhooks like any other message.

Join your WhatsApp#

In the panel, under Developers, you will find your workspace code (shaped like DEV-K7Q2MX) and a button that opens WhatsApp with the message already written. Send it from the phone you want to test with. You get a welcome message once you join.

You can join up to 5 phones per workspace. When a sixth joins, the oldest one leaves. To leave, send SALIR to the sandbox number.

Create a test key#

From the same panel, or in Settings → Developers → API keys by checking Test key. It starts with sk_test_ and only has three scopes: messages:write, conversations:read and conversations:write (hand off to a person, pause the bot and resolve, only on sandbox conversations). Everything else (contacts, campaigns, events, payments) works on the workspace's real data and returns 403 test_key_not_allowed.

Send your first message#

The same POST /v1/messages as always. You do not need channel_connection_id: a test key always sends through the sandbox number.

curl https://app.heysteff.com/api/v1/messages \
  -H "Authorization: Bearer $HEYSTEFF_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_cloud",
    "to": "+56912345678",
    "content": "Hello from the heysteff sandbox"
  }'

The response includes "sandbox": true. With the same key, GET /v1/conversations and GET /v1/conversations/{id}/messages only return sandbox conversations.

Limits#

• WhatsApp only, and only to phones that joined your sandbox. A test key never writes to a customer.
• Only within 24 hours of that phone's last message: that is WhatsApp's rule for free-form messages. If it closed, send anything to the number and try again.
• No templates: yours do not exist in the heysteff WhatsApp account.
• There is a daily send cap per workspace.
• Sandbox conversations do not wake up the agent or your automations.

When you want to write to customers, connect your number in Settings → Channels and use an sk_live_ key.

Sandbox errors#