Oracle Cloud Infrastructure Documentation

D The SDK Helper Methods

Function Usage
conversation.payload() Retrieves the payload of the current user message. The payload contains the message text and other information, like the user ID.
conversation.text() Accesses the text string.
conversation.attachment() Accesses an attachment message.
conversation.location() Accesses a location message.
conversation.postback() Accesses a postback message.
conversation.transition(“action”) and conversation.transition() Directs the Dialog Engine to the next state in the dialog flow. The custom component can influence the navigation by returning an action string that you’ve mapped to state in the dialog flow.
  • Component-controlled navigation (conversation.transition(“action”))—To set the target state, pass a string argument that matches one of the supportedActions strings in the component module’s metatdata function, like nameFound and nameNotFound in the following snippet:
    metadata: () => ({
        "name": "helloWorld",
        "properties": {
          "properties": {
            "name": {
            "type": "string",
            "required": false"
        "supportedActions": ["nameFound", "nameNotFound"]
  • Dialog flow-controlled navigation (conversation.transition())—You can call this function with no arguments when the component module has no supportedActions definition (and therefore, no arguments to pass). In this case, the dialog flow definition sets the transition, not the component. For example, depending on the dialog flow definition, the Dialog Engine might move to the next state in the flow after transition method executes (transitions: {}) or on to a specific state:
      next: "newState"

    The dialog flow will also determine the transition when the component module has a supportedActions definition, but the function itself has no arguments.

conversation.channelType() Allows you to determine the messaging channel.
conversation.keepTurn(boolean) Enables your bot to retain control of the conversation. keepTurn essentially decides who provides input or a response: the bot or its user. So before you call done, you can indicate who goes next by calling either conversation.keepTurn(true) or convesationkeepTurn(false).
  • conversation.keepTurn(true)—Set to true to allow the bot to control the conversation. This is essentially the bot (through the component) asserting “It’s still my turn to speak.” Use this setting when the component doesn’t require user input or when it needs to send multiple replies in quick succession while suppressing user input.

  • conversation.keepTurn(false)—Set to false (the default) to enable the user to reply. This setting essentially hands control back to the user until the next reply from the component. It enables a typical back-and-forth conversation.

conversation.reply({text: "..."}) Returns the response from the messaging client. This response can be a simple text message, or a a more complex response with a rich UI that uses the functions of the MessageModel class in the Custom Component SDK. This function enables you to build more a complex response, such as a scrolling carousel on Facebook. For this type of response, you need to structure the JSON payload appropriately.

You must call done() to send the response, regardless of the number of calls made to conversation.reply. Provides access to the component input properties (
conversation.error Indicates that there was an error in the processing.
conversation.botId() Returns the ID of the bot that sent the request.
conversation.platformVersion() Returns the version of the message platform (such as Facebook 1.0).
conversation.text() Provides access to the NLP text message that triggered the invocation of the intent and the component.
conversation.variable(“name”,value) Provides read or write access to variables defined in the current flow. This function takes the following arguments:
  • variable(name)—Reads the name variable and returns its value.

  • variable(name, value)—Writes the value of the value variable to the name variable. Only enclose the value in quotes when it’s a string.

This function also creates a variable at runtime, one that can be used to track the state of component. You can use this when component needs to track its internal state because it doesn’t transition to the next state in the dialog flow.
conversation.nlpResult() Returns an NLPResult helper object for nlpresult variables. For example, you can find the value of an entity that was extracted from the user input by calling conversation.nlpResult.entityMatches(entity name). You can use this value to update an entity type variable.
conversation.request() Accesses the JSON object body that’s sent by the bot. Use this function to parse the payload for any information that's not directly exposed by one of the SDK functions.
conversation.response() Grants access to the HTTP response payload (a JSON object) that’s sent back to the bot when you call done().