Skip to main content

Endpoint

Queue a synthetic iMessage conversation. Submission returns a job immediately; poll its status until it completes. The service renders original iMessage UI without sending real messages.
Scoped keys require content:render. The bearer key selects the organization. If you use an explicit organization, set the SDK’s orgId or the HTTP query parameter ?orgId=YOUR_ORG_ID; it must be an organization your key can access.
Start with the usage guide. The full input and result contract lists all nested fields, limits, defaults, and validation rules. The downloadable OpenAPI specification includes these endpoints and schemas.

Request body

The body is an IMessageConversationInput. Supply exactly one of contact or group, plus messages. All other top-level fields are optional.

TypeScript

Requires ugcinc@4.27.0 or later.
The SDK does not wait for this render to finish. See the complete polling example.

HTTP

Response

HTTP 200 means the request was accepted or the existing idempotent job was returned. It does not mean rendering has finished. Raw HTTP returns { "code": 200, "data": { ... } }. The SDK adds ok: true and a message to its normalized ApiResponse. data is an IMessageConversationJob: jobId, status, progress, fps, output, contentType, durationMs, and durationInFrames. A completed job includes a public HTTPS url. Failed or cancelled jobs include an error object. Render failures appear as a terminal job state; request failures use the HTTP errors below.

Idempotency and retry

An idempotencyKey is 1–128 characters. Within an organization, retry the same body with the same key to recover the same job. Object-key ordering does not matter; changing the body with that key returns 409 IDEMPOTENCY_CONFLICT. Omitting the key creates a new job. To rerender a failed or cancelled job, use a new key or omit it. Job-ownership records are retained for seven days.

Errors and limits

Native request errors include code, message, errorCode, and retryable. Authentication errors may omit the last two fields. Do not automatically retry an invalid body or reuse a conflicting idempotency key. The contract accepts at most 30 messages, 6,000 animated visible grapheme clusters, a 120-second compiled timeline, and a 16 MiB request. Image and avatar constraints also apply. See all validation rules.

Output profile

Video is H264 MP4 at 60fps, 1126×2436. Native PNGs are 1125×2436. The video adds one background-colored column for the codec’s even-width requirement. MP4 is lossy; a PNG snapshot is rendered from the original native scene, not extracted from compressed video. No audio track is generated by this endpoint. The current renderer uses the iPhone XS / iOS 18.6.2 appearance. Other device profiles, arbitrary fonts/layouts, effects, and image captions are not supported. Some reaction-animation frames can differ between independent renders; exact pixel-repeatability for those frames is not guaranteed.