Skip to main content

Registering Your Skill

Overview​

In order to use your Skill in a project, you first need to register the Skill in DDNA Studio. This page provides an overview of how to register your Skill in DDNA Studio and the recommended best practices for its configuration.

Adding Skills​

Skills are added to DDNA Studio as a JSON object known as a Skill Definition. Below is an example Skill Definition that can be adapted for your own Skill.

{
    "name": "Example Skill Format(string)",
    "summary": "This skill is created for demonstration purposes(string)",
    "description": "This skill is created for demonstration purposes (string)",
    "isPublic": "false | true (boolean)",
    "status": "ACTIVE| DELETED | INACTIVE | REVIEW (enum)",
    "serviceProvider": "DIALOGFLOW | DIALOGFLOW_CX | WATSON | LUIS | ORCHESTRATION_SERVER | SKILL_API | SKILL_ASYNC_API (enum)",
    "ownerId": "auth0|******* (optional string)",
    "organizationId": "Organization ID of Owner (optional number)",
    "endpointInitialize": "https://test.com?state=initialize (url)",
    "endpointSession": "https://test.com?state=session (url)",
    "endpointExecute": "https://test.com?state=execute (url)",
    "endpointEndSession": "https://test.com?state=end_session (url)",
    "endpointEndProject": "https://test.com?state=end_project (url)",
    "endpointMatchIntent": "https://test.com?state=match_intent (url)",
    "config": {
        "matchType": "PHRASE | CUSTOM | FALLBACK (enum)",
        "skillType": "DEFAULT | INTENT_MATCHER | PRE_PROCESS | POST_PROCESS | PRE_POST_PROCESS | BASE_CORPUS (enum)",
        "exitPhrase": ".*",
        "configMeta": [
            {    
                "name": "Configuration details that can be viewed and/or edited by DDNA Studio project creators",
                "type": "TEXT | TEXT_AREA | PASSWORD | NUMBER | SELECT | BOOLEAN",
                "label": "Description of the configuration option",
                "required": "false | true (boolean)",
                "placeholder": "A short hint that describes the expected value for the input field (e.g. a sample value or a short description of the expected format).",
                "defaultValue": "The default pre-configured value for the input field. This value can be updated by the user as required."
            }
        ],
        "privateConfig": [
            {
                "name": "Configuration details that cannot be viewed or edited by DDNA Studio project creators",
                "value": ""
            }
        ],
        "examplePhrases": [
            {
                "lang": "en",
                "value": "Skill: Hi I'm Viola. How's your day going?"
            },
            {
                "lang": "en",
                "value": "User: Hi I'm good thanks."
            },
            {
                "lang": "en",
                "value": "Skill: That's great to hear. Welcome to Soul Machines. I can help answer questions about Soul Machines as well as our products and services. So what would you like to know about us?"
            }
        ],
        "privacyAndTerms": [
            {
                "links": [
                    {
                        "name": "Privacy Policy",
                        "value": "https://www.soulmachines.com/privacy-policy/"
                    },
                ]
                "organization": "Soul Machines"
            }
        ]

    }
}

endpointInitialize​

URL to your AWS Lambda service, Azure functions or wherever your Initialize endpoint for the Skill is hosted.

endpointExecute​

URL to your AWS Lambda service, Azure functions or wherever your Execute endpoint for the Skill is hosted. Alternatively, if you are using the Skills Async API, this should be a websocket endpoint allowing connection to your Skill service.

endpointSession​

URL to your AWS Lambda service, Azure functions or wherever your Session endpoint for the Skill is hosted.

endpointEndProject​

URL to the hosted Skill you want to delete.

config​

Can be used to configure the parameters required by your Skill and the privacy policy, terms and skill documentation.

exitPhrase​

The phrase used to exit your Skill. This can be a string for an exact match or a regex expression. For example you could use the regex ".*" to exit your Skill at the end of the conversation turn. Note: If the endConversation flag is being used, then this is not necessary.

configMeta​

This can be used to get any required and/or optional configuration parameters from DDNA Studio project creators when they are adding the Skill to the project. There are several possible options here: text, text area, password, number, select and boolean.

TEXT​

Allows you to get an alphanumeric string as a configuration parameter. This could be used to get API keys, welcome or fallback phrases etc. Ideally, you should use the defaultValue field to indicate your default text, and the placeholder field to provide an example or description of the text that is expected. 

{
    "name": "no_match",
    "type": "TEXT",
    "label": "No Match Response",
    "required": false,
    "description": "Phrase the digital person will say if no match was found for the user's query",
    "placeholder": "Enter your personalized no match phrase here",
    "defaultValue": "Sorry, I don't have an answer for that",
    "toolTipText": "**Supports Markdown** - Basic text _styling_ and [links](http://google.com)"
}
TEXT_AREA​

This option offers an extended text field, allowing you to accommodate longer alphanumeric strings as configuration parameters. Initially it is displayed with a height of three horizontal rows, but it can expand to a maximum of eight rows. If the content exceeds the visible area, it automatically enables scrolling to handle the overflow. This feature is particularly useful for capturing more detailed information such as Digital Person knowledge, additional prompts, or welcome phrases. It is recommended to utilize the defaultValue field to set the default text and the placeholder field to provide an example or description of the expected text.

{
    "name": "prompt_hook",
    "type": "TEXT_AREA",
    "label": "Additional Prompting",
    "required": false,
    "description": "Any conversation goals, rules, or restrictions?",
    "placeholder": "e.g., I'm the Soul Machines Influencer and I love everything about my job! I keep my responses conversational, brief, and accurate",
    "toolTipText": "**Supports Markdown** - Basic text _styling_ and [links](http://google.com)"
}
PASSWORD​

Used to get the password from the user. Any text entered will be masked. Using the defaultValue field here is not recommended. Instead use the placeholder field to guide the user.

{
    "name": "user_password",
    "type": "PASSWORD",
    "label": "PASSWORD",
    "required": false,
    "description": "Password required to access premium services",
    "placeholder": "Please enter your password here",
    "toolTipText": "**Supports Markdown** - Basic text _styling_ and [links](http://google.com)"
}
NUMBER​

Allows you to restrict the user input to be a number only. Ideally, you should use the defaultValue field to indicate your default value, and the placeholder field to provide an example or description of the expected value.

{
    "name": "config_sleep_time",
    "type": "NUMBER",
    "label": "Wait time before going to sleep",
    "required": false,
    "description": "Enter the wait time in minutes before the digital human goes to sleep due to inactivity",
    "placeholder": "3",
    "defaultValue": "3",
}
SELECT​

Provides the option to allow the user to choose a predefined value from a drop down box. Note: The placeholder field will not do anything for this option. So it is highly recommended that a default value is used, and configured via the defaultValue parameter. 

{
    "name": "spoken_language",
    "type": "SELECT",
    "label": "Language that the digital human will speak",
    "options": [
        {
            "text": "English",
            "value": "en"
        },
        {
            "text": "Japanese",
            "value": "ja"
        },
        {
            "text": "Korean",
            "value": "jo"
        },
        {
            "text": "Arabic",
            "value": "ar"
        }
    ],
    "required": false,
    "defaultValue": "en"
}
BOOLEAN​

Provides the option to allow the user to enter a boolean value using a toggle button. Note: The placeholder field will not work here, as this is a toggle button, and hence there is no text box to display the placeholder value. It is highly recommended that the desired default value is set via the defaultValue parameter. 

{
    "name": "enable_transcription",
    "type": "BOOLEAN",
    "label": "Enable transcription services",
    "required": false,
    "description": "If enabled, conversations will be transcribed.",
    "defaultValue": "false"
}

privateConfig​

Used to define private parameters that DDNA Studio project creators will not have access to, when adding the Skill to the project. 

"privateConfig": [
    {
        "name": "servers",
        "value": {
            "primary_server": "https://my-primary-server.com",
            "secondary_server": "https://my-secondary-server.com"
        }
    }, 
    {
        "name": "env"
        "value": "production"
    }
]

examplePhrases​

Allows you to provide an example of what the conversation flow would look like.

privacyAndTerms​

Will allow you to provide links to your privacy policy, terms of use, and documentation. This will appear in the left navigation column when the DDNA studio creator is configuring the Skill. 

"privacyAndTerms": [
    {
        "links": [
          {
              "name": "Privacy Policy",
              "value": "https://www.soulmachines.com/privacy-policy/"
          },
          {
              "name": "Terms of Use",
              "value": "https://www.soulmachines.com/legal-notices/"
          }
        ],
        "organization": "Soul Machines"
    },
    {
        "links": [
          {
            "name": "Learn More",
            "value": "https://url/to/my/Skill/documentation"
          }
        ],
        "organization": "Example Skill Format Skill"
    }
]