Web connector

The Web connector exposes a generic HTTP API to talk to a Tock bot. It is used to integrate bots into websites and mobile apps, with the React and Vue kits, or any other client.

Connector type: web
Sources and README: connector-web
API: Swagger descriptor

Configuration

In Tock Studio, add a Web connector to the bot configuration (Settings > Configurations), with its relative path, for instance /web.

Field	Description
Web Security Mode	(optional) how the users are identified, see Security modes (default: `DEFAULT`)
Public Path (if different from local REST Path)	(optional) path of the connector as seen by the browser, behind a reverse proxy. Used as path of the security cookies

API usage

Send a message:

curl localhost:8080/web --data '{"query":"Hello","userId":"id"}'

The response contains the bot messages: texts, buttons, cards, carousels, widgets...

{
  "responses": [
    {
      "text": "Hey!",
      "buttons": [
        {
          "title": "Itineraries",
          "payload": "search?_previous_intent=greetings"
        }
      ]
    }
  ]
}

Select a button by sending its payload:

curl localhost:8080/web --data '{"payload":"search?_previous_intent=greetings","userId":"id"}'

Server-sent events (SSE) and streaming

With Server-sent events (tock_web_sse=true), the bot answers are also sent as events on a persistent connection, so that users see the first messages immediately, and that the bot can send push messages. The tock-react-kit uses the SSE stream when it is available.

Messages that cannot be delivered (user offline, or connected to another instance) are stored in MongoDB and delivered when the user reconnects: SSE works with multi-instance deployments.

With tock_web_direct_sse=true, a message can also be sent on the <path>/sse/direct route: the answers are then streamed directly on the same request.

When the bot streams its answers (for instance RAG answers generated by an LLM), the streamed chunks are merged in the final response (tock_web_connector_merge_stream_response, default true).

Push messages

When SSE is enabled, the bot can send push messages with the notify method. Unlike with messaging apps, there is no guarantee that the user receives the message: they may have closed their browser. If they reopen the page, they still receive it thanks to the message queue.

Security modes

The security mode of the connector is selected in its configuration:

Mode	Description
`DEFAULT`	`COOKIES` if `tock_web_cookie_auth` is `true` (or `basic`), `COOKIES_ENCRYPTED` if it is `encrypted`, `PASSTHROUGH` otherwise
`PASSTHROUGH`	No authentication: the user ID is provided by the client
`COOKIES`	The user ID is stored in a secure, HTTP-only `tock_user_id` cookie, generated by the server
`COOKIES_ENCRYPTED`	The `__Http-tock_user_token` cookie stores an encrypted ID and expiration date (AES-GCM, key derived from `tock_encrypt_pass`)
`JWT`	JSON Web Tokens are validated by your own `WebSecurityHandler` implementation, registered with the `JWT` tag through a `BotAdditionalModulesService`

Browsers do not send cookies across domains: with cookie modes, a reverse proxy is needed when the bot backend and the website are on different domains.

Other features

Markdown: with tock_web_enable_markdown=true, the text of the messages is converted from Markdown to HTML.
Custom widgets: implement WebWidget to send custom data to the client. With SSE, register the widget class in KMongo (KMongoConfiguration.bsonMapper.subtypeResolver.registerSubtypes(...)).
Extra headers: tock_web_connector_extra_headers lists extra HTTP headers allowed from the client (for instance authentication headers). With tock_web_connector_use_extra_header_as_metadata_request=true, their values are available as metadata in the bot.

Configuration properties

Property	Default	Description
`tock_web_cors_pattern`	any origin	Regex of the accepted CORS origins
`tock_web_sse`	`false`	Enables server-sent events
`tock_web_direct_sse`	`false`	Enables the direct SSE route
`tock_web_sse_keepalive_delay`	`10`	Seconds between two SSE pings
`tock_web_sse_message_queue_ttl_days`	`-1`	Days before undelivered messages are deleted (MongoDB 7.1+; negative: never)
`tock_web_sse_message_queue_max_count`	`50000`	Maximum number of queued messages
`tock_web_sse_message_queue_max_size_kb`	2 × max count	Maximum size of the message queue (KB)
`tock_web_cookie_auth`	none	`true` or `encrypted`: security mode used by `DEFAULT`
`tock_web_cookie_auth_max_age`	session	`Max-Age` of the cookie, in seconds
`tock_web_cookie_auth_path`	none	`Path` of the cookie, to share it between connectors
`tock_web_enable_markdown`	`false`	Converts Markdown messages to HTML
`tock_web_connector_extra_headers`	none	Extra HTTP headers allowed from the client
`tock_web_connector_use_extra_header_as_metadata_request`	`false`	Passes the extra headers as metadata
`tock_web_connector_merge_stream_response`	`true`	Merges streamed answers in the response

Chat with Tock

×