Hannah API: developer sandbox

1. Get a key

Keys are issued by Quantum, one per integration. A sandbox key starts with qk_test_ and a live key starts with qk_live_. The key is shown once. Send it as a bearer token on every call.

Authorization: Bearer qk_test_...

2. Check the wire

curl https://automotivesalesintelligence.com/api/public/hannah/health \
  -H "Authorization: Bearer qk_test_..."

-> { "ok": true, "environment": "sandbox", "allowedChannels": ["web_chat","sms","email"] }

3. Find something to talk to

The sandbox has a fixed cast of buyers. Ask for them instead of hard coding ids.

curl https://automotivesalesintelligence.com/api/public/hannah/sandbox \
  -H "Authorization: Bearer qk_test_..."

-> { "ok": true, "opportunities": [ { "opportunityId": "...", "buyer": "Marcus Ellery", "vehicle": "2024 Chevrolet Silverado 1500", "stage": "new_lead" } ] }

4. Send a buyer message

curl -X POST https://automotivesalesintelligence.com/api/public/hannah/turn \
  -H "Authorization: Bearer qk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "opportunityId": "<from step 3>",
    "channel": "web_chat",
    "text": "Is the blue one still available?"
  }'

-> 200
{
  "ok": true,
  "environment": "sandbox",
  "conversationId": "uuid",
  "status": "sent | held_for_approval | denied | escalated",
  "reply": "...",
  "reason": "why Hannah did that",
  "policyEffect": "allow | deny | require_approval",
  "confidence": 0.82,
  "correlationId": "uuid"
}

Keep the conversationId and send it back on the next message so the thread stays together. A denied or held answer is a normal, expected outcome, not an error: read reason and show it to your operator. When approval is required, reply contains Hannah's safe acknowledgement to the buyer while the original answer remains held for a human.

Hannah is a lead-to-appointment specialist. She answers the buyer first, then moves qualified interest toward a verified visit or test drive. She can discuss broad, stable differences across competitor vehicles, but exact specifications, current pricing, incentives, recalls, and availability require a verified source. If she is uncertain, she says what needs checking instead of guessing.

5. Push events instead of asking

If your system already owns the inbox, push what happened and let Hannah react.

POST https://automotivesalesintelligence.com/api/public/hannah/events
{ "type": "buyer.message", "opportunityId": "uuid", "channel": "sms", "text": "..." }
{ "type": "lead.created", "opportunityId": "uuid", "payload": { } }

6. Receive what Hannah does

Give Quantum an HTTPS endpoint and every finished turn is posted to it, signed so you can prove it came from us. Verify before you trust the body.

Headers
  x-quantum-event: turn.completed | turn.escalated
  x-quantum-signature: hex HMAC-SHA256 of the raw body, using your signing secret

Node
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

Answer 200 within 10 seconds. Retries are automatic and duplicates are possible,
so treat the correlationId as the idempotency key.

Rules of the road

• Sandbox keys can only see the sandbox dealership. Ids from anywhere else return 404.
• No message from the sandbox ever reaches a phone or an inbox. Delivery is simulated and logged.
• Every key has a daily call cap. Over it, you get 429 with the count.
• 401 means the key is missing or unknown, 403 means revoked, expired or a channel you are not allowed on.
• The sandbox can be reset at any time, so do not store its ids permanently.

Machine readable spec: https://automotivesalesintelligence.com/api/public/hannah/openapi