{"openapi":"3.0.3","info":{"title":"WhatSimule Studio REST API","version":"1.0.0","description":"Official WhatSimule Studio REST API to programmatically create, query, and export interactive WhatsApp simulations. Available for users subscribed to Small and Business plans.","contact":{"name":"CHAMBAPRO S.A.P.I DE C.V. Support","url":"https://whatsimule.chamba.pro"}},"servers":[{"url":"https://whatsimule.com","description":"Production API Server"}],"tags":[{"name":"Simulations","description":"Create and manage embeddable WhatsApp simulations"},{"name":"Media Export","description":"Direct PNG image rendering and asynchronous MP4 video generation with webhooks"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your personal API Key generated in My Account (Small or Business plans)."}},"schemas":{"ScriptStep":{"type":"object","required":["sender","type","content"],"properties":{"sender":{"type":"string","enum":["user","assistant"],"description":"Sender of the message."},"type":{"type":"string","enum":["text","image","audio"],"description":"Content type of the message."},"content":{"type":"string","example":"Hello! How can I help you today?","description":"Message text content or URL of the image/audio."},"delay":{"type":"integer","description":"Animation delay in milliseconds.","default":1000,"example":1000},"senderName":{"type":"string","description":"Optional display name of the sender for group chats (leave omitted for 1-on-1 chats)."},"caption":{"type":"string","description":"Optional caption if message type is image."}}},"SimulatorConfig":{"type":"object","properties":{"assistantName":{"type":"string","example":"Customer Care Agent"},"deviceStyle":{"type":"string","enum":["iphone","android","none"],"example":"iphone","description":"Device layout frame: iphone (Apple iOS), android (Google Android), or none (frameless canvas)."},"theme":{"type":"string","enum":["light","dark"],"example":"dark"},"typingMode":{"type":"string","enum":["direct","typing"],"example":"direct"},"speedMultiplier":{"type":"number","example":1},"rotateX":{"type":"number","example":15,"description":"3D perspective rotation around X axis in degrees (-45 to 45)."},"rotateY":{"type":"number","example":-10,"description":"3D perspective rotation around Y axis in degrees (-45 to 45)."},"rotateZ":{"type":"number","example":5,"description":"3D perspective rotation around Z axis in degrees (-45 to 45)."},"zoom":{"type":"number","example":1.1,"description":"Perspective zoom level multiplier (e.g. 1.0 to 1.5)."},"perspective":{"type":"object","description":"Optional structured 3D perspective camera configuration.","properties":{"rotateX":{"type":"number","example":15},"rotateY":{"type":"number","example":-10},"rotateZ":{"type":"number","example":5},"zoom":{"type":"number","example":1.1},"yOffset":{"type":"number","example":0}}}}},"CreateSimulationPayload":{"type":"object","required":["steps"],"properties":{"title":{"type":"string","example":"WhatsApp Sales Demo"},"config":{"$ref":"#/components/schemas/SimulatorConfig"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/ScriptStep"}}}},"SimulationResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"id":{"type":"string","example":"3b679e62-8c2a-44c3-8388-a701e888d705"},"title":{"type":"string","example":"WhatsApp Sales Demo"},"slug":{"type":"string","example":"whatsapp-sales-demo"},"embedUrl":{"type":"string","example":"https://whatsimule.com/embed/3b679e62-8c2a-44c3-8388-a701e888d705/whatsapp-sales-demo"},"iframeSnippet":{"type":"string"},"webComponentSnippet":{"type":"string"},"createdAt":{"type":"string","example":"2026-07-28T21:00:00.000Z"}}},"ExportPngPayload":{"type":"object","properties":{"simulationId":{"type":"string","description":"UUID of an existing simulation (optional if steps is provided)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/ScriptStep"}},"config":{"$ref":"#/components/schemas/SimulatorConfig"}}},"ExportVideoPayload":{"type":"object","properties":{"simulationId":{"type":"string","description":"UUID of an existing simulation (optional if steps is provided)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/ScriptStep"}},"config":{"$ref":"#/components/schemas/SimulatorConfig"},"webhookUrl":{"type":"string","example":"https://your-domain.com/api/webhooks/video","description":"Optional URL to receive video.completed or video.failed event notifications. If omitted, download link is emailed to account email and available via status polling."},"fps":{"type":"integer","default":24,"example":24},"durationSeconds":{"type":"integer","default":12,"example":15}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/simulations":{"post":{"tags":["Simulations"],"summary":"Create a new embeddable simulation","description":"Programmatically creates a simulation script and returns player URLs, <iframe> snippet, and Web Component tag.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSimulationPayload"},"example":{"title":"WhatsApp Sales Demo","config":{"assistantName":"Sales Specialist","deviceStyle":"iphone","theme":"dark","rotateX":12,"rotateY":-8,"rotateZ":4,"zoom":1.1},"steps":[{"sender":"user","type":"text","content":"Hi there! What plans do you offer?"},{"sender":"assistant","type":"text","content":"Hello! We offer Small and Business plans tailored for your needs."}]}}}},"responses":{"201":{"description":"Simulation successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationResponse"}}}},"400":{"description":"Invalid payload structure."},"401":{"description":"Unauthorized or API Key ineligible (requires Small or Business plan)."}}},"get":{"tags":["Simulations"],"summary":"List all simulations created by API","description":"Retrieves all simulations associated with the active API Key.","responses":{"200":{"description":"List of simulations successfully retrieved."},"401":{"description":"Unauthorized."}}}},"/api/v1/simulations/{id}":{"get":{"tags":["Simulations"],"summary":"Get details of a simulation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Simulation UUID."}],"responses":{"200":{"description":"Simulation details retrieved successfully."},"404":{"description":"Simulation not found."}}},"delete":{"tags":["Simulations"],"summary":"Delete a simulation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Simulation UUID."}],"responses":{"200":{"description":"Simulation deleted successfully."},"404":{"description":"Simulation not found."}}}},"/api/v1/export/png":{"post":{"tags":["Media Export"],"summary":"Export simulation to PNG image (Synchronous)","description":"Generates a high-resolution PNG image screenshot of the simulation with custom 3D rotation, perspective zoom, and device frame (iphone, android, or none). Returns binary image data directly with `Content-Type: image/png`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportPngPayload"},"example":{"simulationId":"3b679e62-8c2a-44c3-8388-a701e888d705","config":{"deviceStyle":"android","theme":"dark","rotateX":15,"rotateY":-10,"rotateZ":5,"zoom":1.15}}}}},"responses":{"200":{"description":"Direct binary PNG image file","content":{"image/png":{}}},"400":{"description":"Missing simulation data."},"401":{"description":"Unauthorized."}}}},"/api/v1/export/video":{"post":{"tags":["Media Export"],"summary":"Export simulation to MP4 video (Async queue)","description":"Enqueues MP4 video rendering in BullMQ. `webhookUrl` is optional. If provided, an HTTP POST event notification is dispatched upon completion. If omitted, an email with the download link is sent to your account email, and job status can be polled via `GET /api/v1/export/video/{jobId}`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportVideoPayload"},"example":{"simulationId":"3b679e62-8c2a-44c3-8388-a701e888d705","fps":24,"durationSeconds":12}}}},"responses":{"202":{"description":"Rendering job successfully queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"status":{"type":"string","example":"queued"},"jobId":{"type":"string","example":"123"},"simulationId":{"type":"string","example":"3b679e62-8c2a-44c3-8388-a701e888d705"},"statusUrl":{"type":"string","example":"https://whatsimule.com/api/v1/export/video/123"},"webhookUrl":{"type":"string","example":"https://your-domain.com/api/webhooks/video"}}}}}},"400":{"description":"Malformed request payload."},"401":{"description":"Unauthorized."}}}},"/api/v1/export/video/{jobId}":{"get":{"tags":["Media Export"],"summary":"Fetch status and download URL of a video export job","description":"Retrieves current status (\"queued\", \"active\", \"completed\", \"failed\"), progress percentage, and download URL (when completed) for a queued MP4 video export job.","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"},"description":"The job ID returned when enqueuing the video export job."}],"responses":{"200":{"description":"Job status details successfully retrieved.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"jobId":{"type":"string","example":"123"},"status":{"type":"string","example":"completed","description":"Current status: queued | active | completed | failed"},"progress":{"type":"number","example":100,"description":"Progress percentage (0-100)"},"statusText":{"type":"string","example":"Completed"},"simulationId":{"type":"string","example":"3b679e62-8c2a-44c3-8388-a701e888d705"},"downloadUrl":{"type":"string","example":"https://whatsimule.com/api/video/download/whatsimule_123.mp4"},"completedAt":{"type":"string","example":"2026-07-28T19:30:45.000Z"},"expiresAt":{"type":"string","example":"2026-07-29T19:30:45.000Z"},"error":{"type":"string","example":null}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Job not found or expired."}}}}}}