Testing environments

Sandbox session testing

Create a sandbox session with a test phone number. Atlas processes the message through the sandbox agent without delivering anything to a real WhatsApp channel. Inspect the returned run object to verify intent detection, tool calls, and knowledge grounding.

POST /v1/atlas/sessions
{
  "idempotency_key": "sess_test_01HX9Z",
  "mode": "sandbox",
  "channel": "whatsapp",
  "customer": { "phone_number": "+6590000000" }
}
Response: {
  "session_id": "sess_01HXAB",
  "mode": "sandbox",
  "status": "active",
  "channel": "whatsapp"
}

POST /v1/atlas/events
{
  "idempotency_key": "evt_test_01HX9Z",
  "session_id": "sess_01HXAB",
  "channel": "whatsapp",
  "direction": "inbound",
  "content": { "type": "text", "text": "Hi, is the menu available?" }
}
Response: {
  "event_id": "evt_01HXAC",
  "status": "received"
}

Inspect run records

After a sandbox session processes a message, inspect the run record to audit what the agent did: which tools were called, what knowledge was retrieved, what intent was detected, and whether an approval was required.

GET /v1/atlas/sessions/{session_id}/runs?limit=10
Response: {
  "data": [
    {
      "run_id": "run_01HXAD",
      "session_id": "sess_01HXAB",
      "iteration": 1,
      "intent": "menu_inquiry",
      "status": "completed",
      "tools_called": [
        { "tool": "retrieve_knowledge", "args": { "q": "menu" }, "result": { "passages_found": 3 } },
        { "tool": "draft_reply", "args": { "text": "Here is our menu..." }, "status": "ok" }
      ],
      "knowledge_retrieved": [
        { "knowledge_id": "kn_01HXAC", "title": "Menu & Pricing", "relevance_score": 0.97 }
      ],
      "approval_required": false,
      "created_at": "2026-05-21T10:05:00Z"
    }
  ]
}

Approval workflow testing

Some actions — refunds, owner assignment, promotional discounts — require human approval before Atlas executes them. Test that the approval gate fires correctly by triggering a policy-gated action and confirming the run enters pending_approval state.

# Submit a refund action (likely policy-gated)
POST /v1/atlas/actions
{
  "idempotency_key": "act_refund_test_01HX9Z",
  "session_id": "sess_01HXAB",
  "action": "apply_loyalty_points",
  "params": { "points": -500, "reason": "customer complaint" }
}
Response: {
  "action_id": "act_01HXAE",
  "status": "pending_approval",
  "approval_state": "pending"
}

# Approve as operator
POST /v1/atlas/runs/{run_id}/approve
{
  "idempotency_key": "approve_01HX9Z",
  "approved": true,
  "note": "Approved per customer complaint policy"
}
Response: { "run_id": "run_01HXAD", "approval_state": "approved" }

Webhook replay testing

For external agent integrations, test webhook handlers by replaying a captured event payload against your endpoint. This validates signature verification, idempotency handling, and correlation ID propagation without triggering real customer messages.

# Replay a captured event (replace event_id to avoid duplicate detection)
POST /v1/atlas/events
{
  "idempotency_key": "replay_unique_key",
  "event_type": "conversation.message_received",
  "conversation_id": "conv_01HX9Z",
  "channel": "whatsapp",
  "customer": { "phone_number": "+6590000000" },
  "message": { "id": "wamid.xxx", "type": "text", "text": "Test replay message" }
}
# Confirm your webhook receives the event and your handler returns 200

Audit trail verification

After each test run, verify the complete action history is visible and queryable. Audit logs must include the principal that initiated the action, the intent detected, tools called, knowledge retrieved, and any approval decision.

GET /v1/atlas/runs/{run_id}
# Confirm all fields populated:
#   - session_id, iteration, intent
#   - tools_called array with args and results
#   - knowledge_retrieved array with relevance scores
#   - approval_required and approval_state
#   - created_at, updated_at

Testing checklist