In-app controls

Broker → cTrader endpoint for creating or updating in-app controls (ribbons). Authenticated with the Manager Token (see Authentication of API calls).

Create or update in-app controls

Sets up one or more ribbon controls displayed to a specific user in cTrader.

Method	URL
PUT	/oauth2/ctid/inAppControls

Request body

Key	Required?	Data type	Description
brokerCrmName	Yes	string	See broker identification.
userId	Yes	integer	The ID of the user to whom the ribbons will be displayed.
rules	Yes	object	An object containing the ribbon definitions. Send an empty object to clear all existing ribbons for this user.
rules.ribbons	Yes	array	An array of ribbon objects. Each object defines one ribbon.
rules.ribbons[].color	Yes	string	Six-digit HEX colour value ("#ff33ee", for instance).
rules.ribbons[].title	Yes	string	Text displayed on the ribbon.
rules.ribbons[].enabled	Yes	boolean	Whether the ribbon is shown to the user.
rules.ribbons[].closable	Yes	boolean	Whether the user can dismiss the ribbon. Dismissed ribbons reappear on subsequent application launches.
rules.ribbons[].action	Yes	object	Action triggered when the user interacts with the ribbon.
rules.ribbons[].action.urlExternal	No	string	External URL opened in a separate browser window on interaction.
rules.ribbons[].action.urlinApp	No	string	In-app URL opened in an iframe on interaction.
rules.ribbons[].brokerName	No	string	If specified, the ribbon is only shown to sessions under this broker name.
rules.ribbons[].ctidTraderAccountId	No	string	If specified, the ribbon is only shown to sessions under this specific trading account.

Expected status code

201

Errors

See Error codes.