Developer Center

• 1: Developer API
• 1.1: Changelog
• 2: Languages
• 3: iFrame Integration
• 4: RTMP Streaming

1 - Developer API

You can now manage your account using Wordly’s REST APIs. You can view the OpenAPI documentation and try out the APIs yourself over at the API Reference page provided that you have a developer API key.

Please note that the API Reference page acts on live data, so be cautious when using it.

New features will be added regularly, so stay tuned for more updates!

Changelog

Click here to view the changelog.

Getting a Developer API Key

A developer API key must be included as a header for all requests. You must have a Wordly account, and your account must be added to an allow list before you can create and use an API key. You can request to have your account added by contacting Wordly Support.

Once your account has been added to the allow list, you can create a non-expiring API key in the Portal by following these steps:

1. Go to your user profile page in the Wordly Portal.
2. Click on the ‘+’ icon button in the API Key row to create a new API key.

If you do not see the API Key row in your profile, then your account has not been added to the allow list.

Getting Started

The following section will help get you started in using Wordly’s REST APIs. You can view the Open API documentation and try out the API yourself over at https://api.wordly.ai/reference.

Authorization Header

In order to use the API, you must include the x-wordly-api-key header with every request. The value of this header is your developer API key.

Example: x-wordly-api-key: f716690b-4e9a-4656-9523-7003637eb6cc

Failure to provide the API key in the header will result in a 401 (i.e., unauthorized) response from the server.

Versioning

As new versions of the API are released, the request and response body schemas may change.

Wordly will include the x-wordly-api-version header in every response which tells you which version of the API the response body is conforming to.

Example: x-wordly-api-version: 1.0

Conversely, you can provide the x-wordly-api-version header in your requests to pin the request and response body schema to a specific API version. This ensures that your requests will continue to work when new versions of the API are released.

If you do not provide the x-wordly-api-version header in your requests, then Wordly will assume the latest API version. Therefore, we strongly recommend that you include this header with every request.

Errors

If an error occurs while processing your request, you will receive an HTTP error response. In most cases, you will receive a JSON response body in the following format:

{
  "message": "An error message will be here.",
  "code": 2003,
  "errors": [
    {
      "message": "Any additional error information..."
    },
    {
      "message": "...will be listed here."
    }
  ]
}

The code field is a numeric error code that is specific to Wordly. The table below is a list of possible error codes that you may receive in an error response.

Deleting a Developer API Key

If you wish to delete and revoke your API key, then you can do so through the Portal. You are free to generate a new API key after deleting your existing one.

Follow these steps to delete your API key:

1. Go to your user profile page in the Wordly Portal.
2. Click on the trashcan icon button in the API Key row to delete your API key.

Notes

Caption Webhook Request Body

The Captions API allows an ongoing Wordly session to send live captions to a designated webhook URL. Captions will continue to be generated and sent until the Wordly session ends or until captioning is explicily stopped using the API.

A webhook URL must be provided when making the request to start captioning a Wordly session. As Wordly generates caption segments, they will be sent to the webhook URL via a POST request.

The body of this POST request will be a single JSON object that contains the following fields.

Voice Pack IDs

Sessions can be assigned a voice pack ID. A voice pack is a curated, one-to-one mapping of voices to available Wordly attendee languages. Attendees using the Wordly Web Attend app will hear transcriptions and translations using the voices in the specified pack if they elect to use the speak along feature.

Currently, there is no way to programmatically retrieve a list of available voice packs. However, the following curated voice packs can be used when specifying the voice pack ID for a session.

If you do not specify a voice pack when creating a session using the API, then the created session will use the voice pack selected in your Wordly profile. By default, your profile will be set to use the default voice pack, which is currently Voice Pack 1.

You can sample the voice packs for different languages when editing a session or updating your profile in the Wordly Portal.

1.1 - Changelog

Version: 1.7.0

Release date: November 1, 2024

What’s New

• Added automatic language selection (ALS) support for streaming.
• Added support for Kannada and Macedonian.

Version: 1.6.4

Release date: August 26, 2024

What’s New

• Added automatic language selection (ALS) fields for sessions.

Version: 1.6.3

Release date: July 26, 2024

What’s New

• Additional languages.

Version: 1.6.2

Release date: June 28, 2024

What’s New

• Added support for TTML transcript downloads.

Version: 1.6.1

Release date: May 30, 2024

What’s New

• Added support for plain text transcript downloads.

Version: 1.6.0

Release date: May 16, 2024

What’s New

• Added media transcription and translation APIs to allow developers to generate caption files for media files. See the API reference for more information on media transcription.
• Security and dependency updates.

Version: 1.5.8

Release date: April 19, 2024

What’s New

• Additional languages
• Security and dependency updates.

Version: 1.5.7

Release date: March 22, 2024

What’s New

• Security and dependency updates.

Version: 1.5.6

Release date: March 15, 2024

What’s New

• Security and dependency updates.

Version: 1.5.5

Release date: December 1, 2023

What’s New

• Additional languages.

Version: 1.5.4

Release date: October 27, 2023

What’s New

• Additional languages.

Version: 1.5.3

Release date: October 10, 2023

What’s New

• Update languages.
• Security and dependency updates.

Version: 1.5.2

Release date: June 23, 2023

Changed

• Minor internal changes with no impact to users.

Version: 1.5.1

Release date: June 8, 2023

Changed

• Added more robust error handling when API key authorization fails.

Version: 1.5.0

Release date: April 21, 2023

What’s New

• Security and dependency updates.

Version: 1.4.0

Release date: March 17, 2023

What’s New

• Added a Captions API that will generate live captions from an ongoing Wordly session that will be distributed to a provided webhook URL. See the REST API help page “REST API Help Page”) and API reference for more information on captioning.
• API service version is now visible on the reference page.

Version: 1.3.1

Release date: March 7, 2023

Bugfixes

• Fixed an issue where certain internal server errors would generate the wrong API error response for consumers.

Version: 1.3.0

Release date: February 16, 2023

What’s New

• Added a voicePackId field to the Sessions API that allows for a voice pack to be optionally specified when creating and updating sessions. See the REST API help page and API reference for more information on voice packs.

  Existing sessions created before this change will automatically use a default voice pack.

Version: 1.2.0

Release date: January 30, 2023

What’s New

• Added a field to the glossary section object called substitutedPhrases. This field holds a map of replacement rules that can be seen in the Replace tab in the Portal.
• Check out the API reference for more information.

Version: 1.1.2

Release date: September 23, 2022

What’s New

• Added support for five new languages listed in the table below. These languages can now be used when creating/updating sessions, glossaries, or streams.

Version: 1.1.1

Release date: September 16, 2022

Changed

• (BREAKING) Updated the POST /sessions request so that the language code is now required.
• Updated the documentation for the streaming API found on the API reference page. The documentation now includes more detailed information.
• The default limit for both GET /sessions and GET /glossaries is now 10.
• Updated the error message when a blank search term is provided when sending a GET /glossaries or GET /sessions request.

Bugfixes

• Fixed an issue with the POST /sessions API where an error was returned when a user submitted a scheduledStart value in the request body that included a timezone offset (e.g., 2022-09-22T10:00:00-0700). Now, start times that include a timezone offset should work and no longer return an error.
• Added constraints to the GET /sessions request so that an error is returned if the page or limit query parameter is set to a value less than 1.

Version: 1.1.0

Release date: September 9, 2022

What’s New

• Added a new API for streaming media content to Wordly. Check out the API reference for more information.

Version: 1.0.0

Release date: August 15, 2022

What’s New

• 🎉 Initial release! CRUD operations for sessions and glossaries.

2 - Languages

Wordly supports a number of languages and the codes for each language are listed below.

Speaker Languages

These language codes can be used in all Wordly integrations and APIs:

Attendee Languages

Along with the languages above, these languages are supported in the Attend iframe and endpoints:

3 - iFrame Integration

Often, the easiest way to integrate Wordly translations into a platform or web application is to embed the ‘attend’ client in an HTML iFrame.

iFrame Embed

The basic HTML code for embedding Wordly translations in an iframe uses the standard HTML iframe tag:

    <iframe src="url" />

You place this in your application wherever you would like Wordly translations to appear. Typically you want to set width and height so the iframe will fill the space you leave for it. This can be done directly in the iframe tag, or via a class attribute. For example:

    <iframe src="url" width="100%" height="300px" />

Source URL

The url to use as the source is crafted from the Wordly session that you want to show your users. The basic format is:

    https://attend.wordly.ai/frame/<session id>

for example, something like:

    https://attend.wordly.ai/frame/ABCD-1234

where ‘ABCD-1234’ would be replaced with a Wordly session ID obtained from the Portal at https://portal.wordly.ai.

Source URL parameters

The url takes a number of optional arguments that can be used with sessions that require a passcode and to change the way the iframe content is displayed:

• key: the session passcode if one is required to attend. Open sessions do not require a passcode.
• lang: the initial language code of the translations for this user. This is not often used. The translation languge will default to English or whatever the user has chosen in the past. See languages for the list of language codes.
• fgcolor: an HTML color for the text in the iframe. This value can be any valid HTML color name or a custom hex RGBA color. The default is white.
• bgcolor: an HTML color for the background of the iframe. This value can be any valid HTML color name or a custom hex RGBA color. The default is black.
• fgsize: an HTML size value for the text in the iframe. This value can be any valid HTML text size, including units. This defaults to the container text size and is not often used.
• tags: a boolean value that can be set to “true” to display speaker names in the iframe. This defaults to “false”.
• speakerLanguage: a boolean value that can be set to “false” to hide the display of the language the speaker is using. This defaults to “true”.
• enableTTS: a boolean value that can be set to “true” to enable text-to-speech support. When this value is ‘true,’ new buttons are added to the bottom bar allowing the user to select a voice for the text to be spoken out loud, and a mute/unmute button. This defaults to “false“.
• finalOnly: a boolean value that can be set to “true” to change the default value for the “Show only complete phrases” user setting. When this value is “true,” only completed translations will be shown to the user and partial translations will be suppressed.
• showScrollbar: a boolean value that can be set to “false” to prevent the scrollbar from appearing in the frame. When this value is set to “false,” users cannot scroll back to read earlier parts of a transcript.
• hide: a list of Wordly language codes to hide from the user. This parameter is a string of codes separated by commas. The specified languages will be removed from the various menus presented to the user. For example: ?hide=en,es,fr will remove English, Spanish, and French from the language menus. See languages for the list of language codes.
• show: a list of Wordly language codes to show to the user. This parameter is a string of codes separated by commas. The specified languages will be the only ones included in the various menus presented to the user. For example: ?show=en,es,fr will reduce all language menus to just English, Spanish, and French. See languages for the list of language codes.

Examples:

A url to display session ‘DCBA-4321’ in Spanish with big, green text would be:

    https://attend.wordly.ai/frame/DCBA-4321?lang=es&fgcolor=00FF00&fgsize=5em

and this emebedded in an iframe in your HTML might look like:

    <iframe src="https://attend.wordly.ai/frame/DCBA-4321?lang=es&fgcolor=00FF00" width="100%" />

A url to display session “DCBA-4321” with TTS enabled:

    https://attend.wordly.ai/frame/DCBA-4321?enableTTS=true

and this emebedded in an iframe in your HTML might look like:

    <iframe src="https://attend.wordly.ai/frame/DCBA-4321?enableTTS=true" width="100%" />

4 - RTMP Streaming

A common way for users and developers to send speech to Wordly for translation is via RTMP streaming, This can be useful when using Wordly to translate a conference session or webinar, or when embedding Wordly in an iframe.

RTMP Streaming

The streaming connection to wordly is via RTMP which requires two things:

• A streaming URL
• A stream key

Streaming URL

The Wordly streaming URL is:

    rtmps://media.wordly.ai/live

This will open an encrypted stream to the Wordly RTMP server.

There is an optional, unencrypted RTMP streaming link. However, we strongly encourage RTMPS as it is more secure. If you cannot use the RTMPS link for some reason, the unencrypted streaming URL is:

    rtmp://media.wordly.ai:8085/live

Stream Key

The stream key tells Wordly the session you are streaming to. This will be the same session as using in the iframe embed (if you are using an iframe). The stream key must also include the passcode to enable access to that session. For example:

    ABCD-1234_987654

Where AABCD-1234 is the Wordly session ID and 987654 is the passcode for the session.

Stream keys are generated automatically when a session is scheduled in the Wordly Portal, and you can find them and the streaming URLs in the session Streaming Shortcuts at https://portal.wordly.ai:

Adding a delay

Sometimes you may need to delay the stream you are sending to Wordly in order to match the delay of the video player in your integration. You add a delay as a parameter attached to the stream key. The delay is in milliseconds to allow fine tuning if needed.

For example you can add a delay of 15 seconds to the stream key above like this:

    ABCD-1234_987654?delay=15000

or if you prefer obscurity you can attach it to the end of the stream key like this:

    ABCD-1234_987654_15000

Adding a language

When you stream to a Wordly session, Wordly will expect speech in the stream to be in the language specified in the session. If the content is actually in a different language, you can override it in the stream key as an additional parameter. See languages for the list of language codes.

For example, to tell Wordly the content of the stream is in French, you can use a stream key like this:

    ABCD-1234_987654?lang=fr

or it can be appended to the stream key like this:

    ABCD-1234_987654_fr

You can also combine the language and delay parameters:

    ABCD-1234_987654?delay=15000&lang=fr

or

    ABCD-1234_987654_fr_15000

The language parameter is not often used. The current streaming language can be changed while streaming is active using the streaming controls in the Portal.

Streaming controls

You can open the live streaming controls in the Portal by clicking on the gear icon next to the session that you are streaming to:

With these controls you can change the language Wordly is expecting the stream speakers to be using. To change the language, pick the new language in the drop-down selector and click the red “Change” button:

Each time a new language is used, a blue quick-change button appears. The streaming language can be changed back to a previous language by clicking one of these buttons.

Finally, when streaming is complete, the “End” button can be used to end the Wordly session.