Generate Client Token (Handshake)

Initializes the Robofy widget and returns the widget configuration, available chatbot agents, and an authorization token for further widget communication.

Endpoint

Request Body

{
  "chatbot_id": "UOmfsaU...",
  "project_id": "24..",
  "version": 2
}

Request Parameters

Field	Type	Required	Description
`chatbot_id`	string	Yes	Public chatbot identifier used to load the correct agent.
`project_id`	string	Yes	Project identifier linked with the widget.
`version`	number	Yes	Widget version. Use `2` for the current widget.

Success Response

{
  "message": "Widget handshake completed successfully",
  "data": {
    "token": "JWT_TOKEN",
    "chatbots": [
      {
        "chatbot_id": "UOmfsaU_vRhAfIwDFrFLoXZUz9nHBAkDNkDygeBCjw",
        "agent_name": "Gujarat - Kitchenware - 49586759",
        "agent_type": "Public",
        "description": "Answers customer questions, troubleshoots issues, and reduces support ticket volume.",
        "avatar_image_path": "https://d2gnxsx8m1azoo.cloudfront.net/avatars/general/6.jpg",
        "greeting": "How can I assist you today?",
        "sort_order": 0,
        "quick_questions": [],
        "lead_capture": {
          "form_title": null,
          "form_subtitle": null,
          "submit_button_text": null
        }
      }
    ],
    "widget": {
      "header": {
        "title": "Hello there 👋",
        "subtitle": "How can I help you today?",
        "chat_tab_label": "Chat",
        "input_placeholder": "Type message here..",
        "download_transcript_label": "Download Transcript",
        "end_session_label": "End Chat Session"
      },
      "branding": {
        "theme_mode": 0,
        "theme_color": "#2563EB",
        "show_powered_by": true,
        "widget_position": "bottom-right",
        "widget_bubble_icon": "https://app-reseller.s3.us-west-2.amazonaws.com/defaulticon/default-icon-2.svg",
        "brand_name": "Robofy"
      },
      "behaviour": {
        "open_on_page_load": false,
        "show_on_mobile": true,
        "show_microphone": true,
        "close_after_time": 60,
        "enable_sources": true,
        "enable_suggested_questions": true
      },
      "loader": {
        "loader_texts": [
          "Understanding Query",
          "Analyzing",
          "Thinking",
          "Collecting Data",
          "Generating Response"
        ],
        "enable_loader": true
      },
      "reset_modal": {
        "reset_chat_modal_title": "Reset Chat",
        "reset_chat_modal_description": "This will permanently remove this conversation, including messages and any chat context stored for this session.",
        "confirm_reset_chat_button_text": "Yes, reset",
        "cancel_reset_chat_button_text": "Cancel",
        "enable_reset_chat_modal": true
      },
      "privacy": {
        "enable_chat_rating": false,
        "capture_ip_address": false,
        "chatbot_privacy_term": null
      },
      "custom_css": null,
      "custom_js": null
    }
  }
}

Response Fields

Root

Field	Type	Description
`message`	string	Status message for the handshake request.
`data`	object	Contains token, chatbot list, and widget configuration.

`data`

Field	Type	Description
`token`	string	JWT token returned after successful handshake. Use this token for authorized widget requests.
`chatbots`	array	List of chatbot agents available for the widget.
`widget`	object	Widget UI, branding, behaviour, loader, reset, privacy, and custom script settings.

`chatbots[]`

Field	Type	Description
`chatbot_id`	string	Chatbot identifier.
`agent_name`	string	Display name of the agent.
`agent_type`	string	Agent visibility type. Example: `Public`.
`description`	string	Short description of the agent.
`avatar_image_path`	string	Agent avatar image URL.
`greeting`	string	Initial greeting shown to the user.
`sort_order`	number	Display order of the agent.
`quick_questions`	array	Suggested questions shown to the user.
`lead_capture`	object	Lead capture form configuration.

`widget.header`

Field	Type	Description
`title`	string	Widget header title.
`subtitle`	string	Widget header subtitle.
`chat_tab_label`	string	Label for the chat tab.
`input_placeholder`	string	Placeholder text inside the message input.
`download_transcript_label`	string	Label for transcript download action.
`end_session_label`	string	Label for ending the chat session.

`widget.branding`

Field	Type	Description
`theme_mode`	number	Widget theme mode.
`theme_color`	string	Primary widget color in HEX format.
`show_powered_by`	boolean	Shows or hides powered-by branding.
`widget_position`	string	Widget position on the website. Example: `bottom-right`.
`widget_bubble_icon`	string	Widget launcher icon URL.
`brand_name`	string	Brand name shown in the widget.

`widget.behaviour`

Field	Type	Description
`open_on_page_load`	boolean	Opens the widget automatically on page load.
`show_on_mobile`	boolean	Shows or hides the widget on mobile devices.
`show_microphone`	boolean	Shows or hides microphone input.
`close_after_time`	number	Auto-close time in seconds.
`enable_sources`	boolean	Enables source display in responses.
`enable_suggested_questions`	boolean	Enables suggested questions.

`widget.loader`

Field	Type	Description
`loader_texts`	array	List of loading messages shown while generating a response.
`enable_loader`	boolean	Enables or disables loader messages.

`widget.reset_modal`

Field	Type	Description
`reset_chat_modal_title`	string	Reset modal title.
`reset_chat_modal_description`	string	Reset modal description.
`confirm_reset_chat_button_text`	string	Confirm button text.
`cancel_reset_chat_button_text`	string	Cancel button text.
`enable_reset_chat_modal`	boolean	Enables or disables the reset confirmation modal.

`widget.privacy`

Field	Type	Description
`enable_chat_rating`	boolean	Enables or disables chat rating.
`capture_ip_address`	boolean	Enables or disables IP address capture.
`chatbot_privacy_term`	string	null

`widget.custom_css`

Type	Description
string	null

`widget.custom_js`

Type	Description
string	null

Notes

Call this API before rendering the widget.

Store the returned token securely in the widget runtime.

Use the returned widget object to configure the widget UI and behaviour.

Use the returned chatbots array to display available agents.

Generate Client Token (Handshake)

Endpoint#

Request Body#

Request Parameters#

Success Response#

Response Fields#

Root#

data#

chatbots[]#

widget.header#

widget.branding#

widget.behaviour#

widget.loader#

widget.reset_modal#

widget.privacy#

widget.custom_css#

widget.custom_js#

Notes#

Request

Responses