Manage Translations via API
The Flow XO bot has translations for many different languages so that you can easily implement bots in your language of choice. These translations include basic automated messages such as question reminders and validation error messages, as well as input keywords such as terminating a conversation, skipping a question, etc.
You may find, however, that you want to override some of our translated phrases with your own even though we already support your preferred language. For example, when a user does not answer a question in a timely manner, you may want to globally customize the specific phrase used to remind the user to answer your question without having to make changes to the configuration of every single question in every single one of your flows. Or perhaps you want to change the "quit" keyword, so that the user has to type something other than "Bye" or "Quit" to end a conversation early.
To support these use cases, we have exposed a translations API that will allow you to override all or some of the default translations for any given language.
Please keep in mind that you will only need to supply translations for phrases or keywords you want to override from the existing defaults. It is not necessary to supply a complete set of phrases and keywords.
The following translation management functions are available:
1.Creating a new custom translation override for a specific language
2. Updating a translation override by id
3. Listing all translation overrides for your account
4. Listing a single translation override by id
5. Deleting a translation override
Authorization
You must authorize all calls to the Flow XO API using your API key and an authorization header. Details can be found here: https://support.flowxo.com/article/289-api-authorization
API Url
To use the Flow XO API, you will need to send HTTP requests to the following endpoint. The last part of the URL will depend on the method you are calling, but the base address is:
https://flowxo.com/api/translations
Creating a new translation override
You can add a translation override to your agency account by issuing a POST request:
POST https://flowxo.com/api/translations
With the following payload:
{
"lang":"en",
"tokens": {
"conversation_quit":"Ok, no problem! Hope to see you again..."
},
"keywords": {
"quit":["go away","stop"]
}
}
The result will look like this:
{
"_id": "xxx",
"user": "yyy",
"last_updated_at": "2022-07-13T16:46:28.723Z",
"created_at": "2022-07-13T06:54:02.384Z",
"keywords": {
"quit": [
"ta ta"
]
},
"tokens": {
"conversation_quit":"Ok, no problem! Hope to see you again..."
},
"lang": "en"
}
The inputs are as follows:
1. lang : The locale code of the language you wish to target. For instance, English is "en", Spanish is "es". For the languages we support, these are the locale codes you would use in the "lang" field when creating a translation:
'ar', // Arabic 'bg', // Bulgarian 'de', // German 'el', // Greek 'en', // English 'es', // Spanish 'fi', // Finnish 'fr', // French 'it', // Italian 'iw', // Hebrew 'jp', // Japanese 'ko', // Korean 'nl', // Dutch 'pt', // Portuguese 'ru', // Russian 'th', // Thai 'tr', // Turkish 'uk', // Ukrainian 'zh', // Chinese
2. tokens : This is a map of all the phrases you wish to override, along with your preferred translations/phrasing. Here are the available phrases. Remember, you only need to include in your payload the phrases you want to override. If your tokens configuration does not have a particular phrase, the default will be used by Flow XO.
"tokens": {
"a_date": "a date",
"a_datetime": "a datetime",
"an_integer": "an integer",
"a_decimal": "a decimal",
"a_number": "a number",
"a_time": "a time",
"an_email": "an email",
"connection_deleted": "Sorry, this Flow XO bot has been deleted.",
"conversation_abandoned": "You didn't answer, so I'll go away for now.",
"conversation_choices": "Answer with %s.",
"conversation_clarify_try": "I didn't get that, can you try again?",
"conversation_clarify_exact": "Make sure you type your answer carefully.",
"conversation_multitext": "Reply with as many messages as you like and just say 'finished' when you're done.",
"conversation_quit": "Bye!",
"conversation_reminder": "Just a reminder to answer my question.",
"conversation_skip_suffix": "To skip this question, say 'skip'.",
"conversation_shortcuts": "Choose from %s.",
"conversation_skip_denied": "Sorry, you can't skip this question.",
"conversation_validation_error_expecting": "I was expecting %s, could we try again?",
"conversation_validation_regex_error": "That doesn't look right, could we try again?",
"conversation_validation_regex_error_unsafe": "An unexpected error occurred.",
"connection_account_disabled": "Sorry, we're unable to respond to your message at the moment.",
"service_unavailable": "Sorry, your message couldn't be processed because of a temporary error, please try again.",
"start": "start",
"welcome_default": "Hello, this is %s.",
"welcome_message_shortcuts": "Choose from %s.",
"help": "help",
"and": "and",
"or": "or",
"options": "Options",
"menu_back": "< Back",
"menu_home": "Home",
"menu_not_found": "Menu not found",
"evaluation_response": "Thanks for your feedback!"
}
3. Keywords : This is a list of the keywords (input phrases) you want to override. Keep in mind that the keywords are fuzzy matched to allow for mis-spellings and typos, so choose keywords that are not likely to be used as normal replies or very similar to normal replies as part of your users responses to your questions. Also note that when you supply a specific set of keywords, for instance for the "quit" action, the list of available keywords will completely replace the default list. This means that if you want to override "quit" and you provide the single keyword ["enough"] then ONLY "enough" will trigger the quit action, and the previous quit keywords such as "bye" and "quit" will no longer work. So if you want to keep some of the existing keywords for a specific action like "quit" you will need to specify in your keyword list the ones you want to keep as well as the ones you want to add, for example ["quit","bye","enough"]
"keywords": {
"quit": ["quit", "exit", "goodbye", "bye", "end"],
"skip": ["skip", "skipped", "dont know"]
}
Updating a translation override
You can update a particular translation by its ID, which you will find in the "_id" field when querying translations through the API.
PUT https://flowxo.com/api/translations/{translation_id}
With the following payload:
<pre>
{
"tokens": {
"conversation_quit":"Catch you later!"
}
}
The result will look like this:
{
"_id": "xxx",
"user": "yyy",
"last_updated_at": "2022-07-13T16:46:28.723Z",
"created_at": "2022-07-13T06:54:02.384Z",
"tokens": {
"conversation_quit":"Catch you later!"
},
"lang": "en"
}
Listing a single translation
You can retrieve the data of a single translation by issuing a GET request:
GET https://flowxo.com/api/translations/{translation_id}
The result will look like this:
{
"_id": "xxx",
"user": "yyy",
"last_updated_at": "2022-07-13T16:46:28.723Z",
"created_at": "2022-07-13T06:54:02.384Z",
"tokens": {
"conversation_quit":"Catch you later!"
},
"lang": "en"
}
Listing all translations for your account
GET https://flowxo.com/api/translations
The result will look like this:
[
{
"_id": "xxx",
"user": "yyy",
"last_updated_at": "2022-07-13T16:46:28.723Z",
"created_at": "2022-07-13T06:54:02.384Z",
"tokens": {
"conversation_quit":"Catch you later!"
},
"lang": "en"
},
{
"_id": "xxx",
"user": "yyy",
"last_updated_at": "2022-07-13T16:46:28.723Z",
"created_at": "2022-07-13T06:54:02.384Z",
"tokens": {
"conversation_quit":"Catch you later!"
},
"lang": "en"
}
]
Notes:
* Although not documented here, this translation API can allow you to specify specific translations that only apply to a single Bot, or even a single Flow. If you have a need for this level of detailed configuration, please reach out to support to help you configure your scenario.
* If you have an Agency account, and you create a translation using an API token from the master account, the translations will apply to all sub-accounts automatically. If you only want to specify a translation for a single sub-account, make sure you use an API token that is specific to the sub-account and not the master account.
That's It for now!
Let us know if you have questions/feedback on this API at support@flowxo.com