Avatar Creator integration

If you followed the Quickstart you already integrated the Avatar Creator into a website using an iframe. This guide details the integration and customization options of this Avatar Creator.

Subscribe to Events

The iframe exposes a post message API that can be used to subscribe to events and for triggering certain actions.

To enable the events you need to append the parameter ?iframe=true to the avatar-creator URL.

https://avatars.streamoji.com/createAvatar/?iframe=true

Auth tokens in the iframe

Client auth tokens in the token query parameter are valid for about 30 minutes. When a token expires, API calls such as loading an avatar by avatarId return 401. Mint a new token from your backend, then either reload the iframe with an updated token= URL or post a setToken message (see Queries below). The iframe emits v1.auth.expired when getAvatarConfig rejects the token so your host can refresh proactively.

Emitted Events

All messages that the iframe emits will always contain a eventName and source and can be used for filtering the output that is emitted.

Event	Payload example
v1.frame.ready	`{ eventName: 'v1.frame.ready', source: 'streamojiavatars' }`
v1.avatar.exported	`{ data: { avatarId, url, userId, thumbnailUrl, // included when thumbnail=true avatarGender, // "male" \| "female" }, eventName: 'v1.avatar.exported', source: 'streamojiavatars', }`
v1.user.set	`{ data: { id }, eventName: 'v1.user.set', source: 'streamojiavatars', }`
v1.auth.expired	`{ eventName: 'v1.auth.expired', source: 'streamojiavatars', data: { reason: 'Token has expired (older than 30 minutes)' }, }`

Queries

Supported messages that can be posted to the iframe after the v1.frame.ready event has been emitted.

Effect Message example

Subscribe to all events

Effect	Message example
Subscribe to all events	`iframe.contentWindow.postMessage( JSON.stringify({ target: 'streamojiavatars', type: 'subscribe', eventName: 'v1.*' }), '' );`
Update auth token (e.g. after expiry) without reloading the iframe	`iframe.contentWindow.postMessage( JSON.stringify({ target: 'streamojiavatars', type: 'setToken', token: 'YOUR_NEW_CLIENT_JWT' }), '*' );`

iframe.contentWindow.postMessage(
  JSON.stringify({
    target: 'streamojiavatars',
    type: 'subscribe',
    eventName: 'v1.**'
  }),
  '*'
);

Update auth token (e.g. after expiry) without reloading the iframe

iframe.contentWindow.postMessage(
  JSON.stringify({
    target: 'streamojiavatars',
    type: 'setToken',
    token: 'YOUR_NEW_CLIENT_JWT'
  }),
  '*'
);

Avatar Creator Configuration

While you can configure most of the Avatar Creator features from the dashboard, for some use cases it might be helpful to do it by providing a query string to the URL.

Parameter	Value	Effect
`iframe`	`true`	Enables iframe mode and `postMessage` events.
`bodyType`	`'Half' \| 'Full'`	Selects a body type for the avatar in the editor.
`token`	`string`	External auth token for secure integration.
`avatarId`	`string`	Loads a specific avatar for editing.
`userId`	`string`	Optional user ID when loading an avatar that belongs to a different user.
`genderSelection`	`true`	Forces the gender selection screen to appear on load.
`saveConfirm`	`true`	Shows a confirmation modal before saving the avatar.
`whiteLabelTitle`	`string`	Custom title to display in the top bar for white-labeling.
`whiteLabelColor`	`string`	Custom theme color (hex format) for white-labeling the interface.
`thumbnail`	`true`	Generates a thumbnail Image of the Avatar and includes `thumbnailUrl` in the `v1.avatar.exported` event response.
`hidePremiumAssets`	`true`	Hides premium assets from the asset picker, showing only free assets.
`xr`	`true`	Hides full-body single-mesh outfits from the asset picker (for XR pipelines that need separable clothing meshes).

Examples

https://avatars.streamoji.com/createAvatar?iframe=true&bodyType=Full

https://avatars.streamoji.com/createAvatar?iframe=true&bodyType=Full&xr=true

https://avatars.streamoji.com/createAvatar?iframe=true&token=YOUR_TOKEN&avatarId=123

https://avatars.streamoji.com/createAvatar?iframe=true&genderSelection=true

https://avatars.streamoji.com/createAvatar?iframe=true&saveConfirm=true&whiteLabelTitle=My%20Brand&whiteLabelColor=%23FF5733

Downloading the Avatar

Once you receive the v1.avatar.exported event, you can download the final GLB file using the avatarId and your authToken.

async function downloadAvatar(avatarId, authToken) {
  const url = 'https://glb.streamoji.com/api/process?avatarId=' + avatarId;
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + authToken
    }
  });

  if (!response.ok) {
    throw new Error('Download failed: ' + response.status);
  }

  const blob = await response.blob();
  const downloadUrl = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = downloadUrl;
  a.download = 'avatar-' + avatarId + '.glb';
  document.body.appendChild(a);
  a.click();
  a.remove();
  window.URL.revokeObjectURL(downloadUrl);
}