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

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

Event	Payload example
v1.frame.ready	`{ eventName: 'v1.frame.ready', source: 'streamojiavatars' }`
v1.avatar.exported	`{ data: { avatarId, url, userId, thumbnailUrl, // included when thumbnail=true }, eventName: 'v1.avatar.exported', source: 'streamojiavatars', }`
v1.user.set	`{ data: { id }, eventName: 'v1.user.set', source: 'streamojiavatars', }`

{
  eventName: 'v1.frame.ready',
  source: 'streamojiavatars'
}

v1.avatar.exported

{
  data: {
    avatarId,
    url,
    userId,
    thumbnailUrl, // included when thumbnail=true
  }, 
  eventName: 'v1.avatar.exported',
  source: 'streamojiavatars', 
}

v1.user.set

{
  data: { id },
  eventName: 'v1.user.set',
  source: 'streamojiavatars',
}

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	`iframe.contentWindow.postMessage( JSON.stringify({ target: 'streamojiavatars', type: 'subscribe', eventName: 'v1.*' }), '' );`

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.

Examples

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

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);
}