Bridge events reference

This reference enumerates every message in the WebView bridge protocol, in both directions. All messages are JSON objects with a type field prefixed tars:.

tars:init

Starts the bridge session. Only the first tars:init takes effect. The widget answers with tars:ready.

Field	Type	Description
`platform`	string	Your platform label, for example `ios`, `android`, `react-native`
`version`	string	Your integration version label
`chrome`	object	`{ showHeader, showCloseButton }`, both booleans, both default `true`
`userData`	object	`{ name, email, phone, customData }`: end-user data to inject
`context`	object	Free-form context variables to inject into the conversation

{
  "type": "tars:init",
  "platform": "ios",
  "version": "1.0",
  "chrome": { "showHeader": false, "showCloseButton": true },
  "userData": { "name": "Ada Point", "email": "ada@example.com" },
  "context": { "screen": "checkout" }
}

tars:inject

Injects additional userData or context into the running conversation, same shapes as in tars:init. Send it any time after the handshake.

Field	Type	Description
`userData`	object	Same shape as in `tars:init`
`context`	object	Free-form context variables

tars:command

Sends a command to the conversation.

Field	Type	Description
`action`	string	`restart` or `set_variable`. Defaults to `restart`
`variableName`	string	With `set_variable`: the variable to set
`variableValue`	string	With `set_variable`: the value. Defaults to an empty string

restart restarts the conversation. set_variable writes one context variable into the running conversation.

tars:ready

The widget posts this message twice, and the two carry different fields. The first one arrives when the widget page mounts, and it holds only its type. It tells the app that the page is ready to receive tars:init. The second one is the bridge’s answer to tars:init, and it carries the fields below. Treat only the second one as the handshake, because the capabilities arrive with it.

Field	Type	Description
`version`	string	Protocol version, currently `"1"`
`capabilities`	string[]	`["navigate", "data", "close"]`

tars:navigate

Asks the app to navigate to a native route. Fired by a gambit’s navigate bridge event.

Field	Type	Description
`route`	string	The route, after variable interpolation
`params`	object	String parameters, each value interpolated

tars:data

Delivers captured conversation variables. Fired by a gambit’s data bridge event.

Field	Type	Description
`variables`	object	The conversation’s captured response variables at that point

tars:close

Asks the app to dismiss the chat screen. Fired by a gambit’s close bridge event. No payload.

Per-gambit bridge events

With Enable Bridge Events on, each gambit’s editor can attach one bridge event.

Setting	Description
Type	`navigate`, `data`, or `close`: which widget → app message fires
Route	For `navigate`: the native route string, supports interpolation
Params	For `navigate`: string parameters, each supports interpolation

The event fires when the conversation reaches the gambit. Reaching the same gambit twice in a row fires it once. A loop through another bridge gambit and back fires it again.

Variable interpolation

Route and param strings interpolate conversation variables with the {{scope.key}} syntax, for example {{response.email}} or {{enduser.name}}. One namespace and one key per token.

Case	Result
The scope and key resolve to a string	The token is replaced with the value
The scope is missing	The token is replaced with an empty string
The value is not a string	The token is left unchanged

Chrome control

chrome in tars:init controls the widget header for a native fit.

Field	Default	Effect when `false`
`showHeader`	`true`	Hides the widget header, so your native screen provides the title
`showCloseButton`	`true`	Hides the close button, so closing is driven by `tars:close` and native chrome

Welcome

Core concepts

Guides

Developer

Bridge events reference

App → widget messages

tars:init

tars:inject

tars:command

Widget → app messages

tars:ready

tars:navigate

tars:data

tars:close

Per-gambit bridge events

Variable interpolation

Chrome control

​App → widget messages

​tars:init

​tars:inject

​tars:command

​Widget → app messages

​tars:ready

​tars:navigate

​tars:data

​tars:close

​Per-gambit bridge events

​Variable interpolation

​Chrome control

​Related pages

App → widget messages

tars:init

tars:inject

tars:command

Widget → app messages

tars:ready

tars:navigate

tars:data

tars:close

Per-gambit bridge events

Variable interpolation

Chrome control

Related pages