Sandbox

Quickstart diagnostics

Response

Simulate inbound

This is the canonical sandbox inbound endpoint. Use it with a tx_sandbox_... key that has sandbox:write. For WhatsApp service-window tests, set from to the customer phone you will later send to, and set to to the sandbox sender id used by the outbound request.

curl "$TYXTER_API_BASE_URL/v1/sandbox/inbound-messages" \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -H "tyxter-trace-id: diag_open_window" \
  -d '{
    "channel": "whatsapp",
    "from": "+5511999999999",
    "to": "sandbox_sender",
    "type": "text",
    "text": { "body": "Opening the sandbox service window" }
  }'

The WhatsApp inbound from must be a possible E.164 subscriber number. An impossible number is rejected with 400 invalid_phone_e164 (param: from) before rate-limiting, idempotency, or any persistence — a real provider can never deliver a message from an impossible number, so the sandbox simulator does not accept one either. This check is WhatsApp-only; Instagram from values are opaque provider ids and are not phone-validated.

Request body

Response

Simulate a template status change

Sandbox keys can move a local template into rejected, paused, or disabled without calling Meta. This deterministic fixture lets an integration verify its template lifecycle and webhook handling. Production keys are rejected.

Request body

Response

Arm an LLM failure

Arms the next sandbox completion with a normalized provider failure. Omit ttl_seconds for a one-shot fixture, or bound how long the fixture remains active. Re-arming replaces the current fixture. This write supports Idempotency-Key and never calls a live provider.

Request body

Response

Simulate Flow completion

To prove the flow.completed webhook without a real Meta submission, drive an outbound flow send through the flow_completed scenario. POST /v1/sandbox/inbound-messages with type: "flow" only emits message.received; it does not emit flow.completed. The supported path is a normal POST /v1/messages flow send tagged with metadata.sandbox_scenario = "flow_completed". This outbound fixture does not simulate Meta's ordinary inbound interactive.nfm_reply callback.

Full five-step sequence with a sandbox key:

1. POST /v1/flows — create a flow.
2. POST /v1/flows/{id}/publish — publish it (sandbox auto-publishes locally and assigns a provider_flow_id).
3. GET /v1/flows/{id} — read provider_flow_id from the response.
4. POST /v1/messages with the flow message below.
5. GET /v1/webhook-events/listen?event_type=flow.completed — read the completion proof.

curl "$TYXTER_API_BASE_URL/v1/messages" \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "channel": "whatsapp",
    "sender": { "type": "whatsapp_phone_number", "id": "sandbox_sender" },
    "recipient": { "type": "phone_e164", "id": "+15551234567" },
    "message": {
      "type": "flow",
      "flow": {
        "body": { "text": "Tap below to complete your booking." },
        "action": {
          "name": "flow",
          "parameters": {
            "flow_id": "<provider_flow_id from GET /v1/flows/{id}>",
            "flow_token": "booking-7f3a",
            "flow_cta": "Book now"
          }
        }
      }
    },
    "metadata": {
      "sandbox_scenario": "flow_completed",
      "sandbox_flow_response": { "email": "[email protected]", "size": "M" }
    }
  }'

metadata.sandbox_flow_response is optional and controls the submitted response data. The sandbox returns it verbatim as submission.response; it defaults to { "sandbox": true }. The listen response returns the same flow.completed data shape a real Meta submission produces:

{
  "object": "webhook_event_listen",
  "data": [
    {
      "type": "flow.completed",
      "payload": {
        "type": "flow.completed",
        "data": {
          "flow_id": "flw_...",
          "name": "lead_capture",
          "status": "published",
          "provider_flow_id": "1234567890",
          "rejection_reason": null,
          "submission": {
            "id": "sub_...",
            "provider_token": "booking-7f3a",
            "response": { "email": "[email protected]", "size": "M" },
            "message_id": "msg_...",
            "received_at": "2026-04-27T12:05:00.000Z"
          }
        }
      }
    }
  ]
}

submission.provider_token echoes the flow_token you sent, and submission.message_id is the source outbound message. Do not duplicate flow_token in metadata.sandbox_flow_response for correlation; use those two fields instead. Production Meta interactive.nfm_reply parsing strips a top-level token, but the sandbox fixture returns the configured response as supplied.