Publish Your Bot as a Custom REST API

Publish your NativeChat chatbot on a custom/REST channel.

NativeChat allows publishing a chatbot on a REST channel.

Using our REST API, you can create your own UI implementation and use the NativeChat bot engine if out-of-the box channel integrations do not fit your use case.

Setup

Create a new channel in NativeChat

To receive messages and other events sent by your channel users, you need to enable REST channel.

1. Open the Publishing section of your NativeChat bot.
2. Click the Add button for REST to open the Add REST channel configuration form.
3. Enter a name for your custom channel and click the Add configuration button.
4. Use the Bot ID, Channel ID and Channel Access Token to make requests to get the bot response for a given user utterance.

Configuration

Send Message

You can send messages to the bot on behalf of the user.

Endpoint

https://api.nativechat.com/v1/bots/:BOT-ID/channels/:CHANNEL-ID/rest/:CHANNEL-NAME

You can get the BOT-ID, CHANNEL-ID and CHANNEL-NAME from the channel configuration in the publish section on the NativeChat portal.

Request Headers

Authorization: Bearer CHANNEL-ACCESS-TOKEN
Content-Type: application/json

You can get the CHANNEL-ACCESS-TOKEN from the channel configuration in the publish section on the NativeChat portal.

Request Method

POST

Request Body

{
  sender: {
    id: string;
    timezone?: string;
    token?: string;
  },
  message: {
    text?: string;
    context?: object;
    location?: {
      latitude: number,
      longitude: number;
    };
    attachments?: [{
      mimeType: string;
      name: string;
      payload: {
        url: string
      }
    }];
    event?: {
      type: 'authentication';
      data: {
        token: string;
        origin: string;
      };
    };
}

• sender

  • id A unique ID to identify a sender. Sending messages to the bot with the same user ID would result in continuing the conversation of that user with the bot.
  • timezone (optional) You can set the user timezone with the first message from the user to the bot. The timezone will be used when formatting dates with the $date formatter or identifying dates in user messages using our NLP engine.
  • token (optional) If you have protected steps in your conversation (steps that require the user to log in), you need to pass the user token to all subsequent messages once obtained.

• message An object describing the user message.

  • text (optional) The text of the user message to the bot.

  • context (optional) An object with entity values supplied to the bot with the start of a conversation. These values can be used in the conversation defined in the Cognitive Flow. For example, if you know some of the information that the conversation gathers before a user starts chatting with the bot (like user profile information, preferences, etc.), you can supply it to the bot to improve user experience by not asking questions you already know the answers to.

  • location (optional) The location that the user submits as part of their response. You can use this property when you have defined a question step in the conversation that expects an entity of type Location in the user response.

  • attachments (optional) An array of objects describing file attachments to the user message. You can use this property to supply URLs to files as a response to a question step in the conversation that expects an entity of type File in the user response.

  • event (optional) Currently, the only supported event type is authentication. You will need this property in case you require the user to authenticate in the chat session. For information how to setup this type of authentication, go to the authentication topic.

    • token The token from the response you received when calling the account linking endpoint.
    • origin The origin should be either the domain of the login page or it should be listed in the trusted domains.

Bot Response

The response of the bot to a user message is in the form an array of objects, each describing a single message.

Bot Response Message

[{
    text?: string;
    quickReplies?: string[];
    richQuickReplies?: [{
        value: string;
        title: string;
        imageUrl?: string;
    }];
    template?: {
        type: 'single-select' | 'multi-select' | 'carousel' | 'location-picker' | 'date-picker' | 'button' | 'grid';
        buttons?: [{
            title: string;
            url?: string;
        }];
        items?: [{
            value?: string;
            title: string;
            subtitle: string;
            imageUrl: string;
        }];
        title?: string;
    };
    v2template?: {
        type: 'single-select' | 'multi-select' | 'carousel' | 'location-picker' | 'date-picker' | 'button' | 'grid';
        buttons?: [{
            title: string;
            url?: string;
        }];
        items?: [{
            value?: string;
            title: string;
            subtitle: string;
            imageUrl: string;
        }];
        title?: string;
    };
}]

• text (optional) The text of the bot message to the user.

• quickReplies (optional) A list of strings with all possible options that the user can select from. This list is populated with values when you set display type quick-reply for the step in the Cognitive Flow. If the values that you have used in the Congitive Flow are objects with title, value and image, then value will be used in the quickReplies list.

• richQuickReplies (optional) An array of objects. Similarly to quickReplies, this array is populated with values when you set display type quick-reply for the step in the Cognitive Flow. Unlike quickReplies, richQuickReplies contains the full objects if the values that you have used in the Congitive Flow are objects with title, value and image. If the values that you have used in the Congitive Flow are strings, then title and value are set to the string and image is empty.

• template / v2template (optional) An object describing a bot response with display type different from quick-reply. When v2template is provided, template is specified for backward compatibility only and should not be used. If v2template is not provided, use template.

  • type A string describing the type of the bot response. Possible values are: single-select, multi-select, carousel, location-picker, date-picker, button and grid. The value of this property depends on the display and step types specified in the Cognitive Flow.
    
    In case you require the user to authenticate in the chat session, when the user reaches a step that requires authentication, the bot will send a response with a button type template and the URL and title, provided in settings/authentication.

  • buttons (optional) An array of objects describing the buttons that the UI should show. For single-select, multi-select, location-picker and date-picker, the array contains two buttons - one, describing the button that opens the picker and another, describing the button that submits the selection. For carousel and button, the array contains only one button which submits the selection.
    • title The text of the button.
    • url (optional) The URL that the button opens. This property is set for steps of type link or when the user reaches a step that requires them to authenticate in the chat session.

  • items (optional) An array of objects. Used for single-select, multi-select, carousel, date-picker and grid types. For the date-picker type, this array lists the valid dates from which the user can select as specified in the Cognitive Flow if set. For the other supported types, the property lists the items of the step. The values of the properties for each item are determined by the template object that you provide for the step in the Cognitive Flow. The items are determined by the data or data-source provided for the step in the Cognitive Flow.

  • title (optional) A string representing the title of the grid. Used only for steps with grid type.