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	integer	If specified, the ribbon is only shown to sessions under this specific trading account.

info

The rules.ribbons array may include several ribbon objects, so you can combine parameters to create custom sets of controls shown under different circumstances. For example, some ribbons can be shown only to sessions under a specific account, while others are shown only to sessions whose account belongs to a certain White Label (brokerName).

Targeting follows three cases, depending on the parameters in the request body:

• If a valid ctidTraderAccountId is specified, the ribbon is shown only to sessions logged in under that account.
• If ctidTraderAccountId is unspecified but a valid brokerName is specified, and no ribbon matches by account, the ribbon is shown to sessions under that brokerName.
• If neither ctidTraderAccountId nor brokerName is specified, and no ribbon matches by account or brokerName, the ribbon is shown to all sessions under the specified brokerCrmName.

Expected status code

201

Errors

See Error codes.

Request example

curl -X PUT 'https://HOST:PORT/cid/oauth2/ctid/inAppControls?token=04d95575-c9af-42fba72e-2f0ce93f01d4' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"brokerCrmName": "BESTBROKERCRM", "userId": 10345533, "rules": {"ribbons": [{"color": "#ff33ee", "title": "MyRibbon one", "action": {"urlinApp": "https://exampleurl.com"}, "enabled": true, "closable": true, "ctidTraderAccountId": 6530877}, {"color": "#33ffee", "title": "MyRibbon two", "action": {"urlExternal": "https://anotherurl.com"}, "enabled": true, "closable": true, "brokerName": "smartBroker"}]}}'

To clear all ribbons for a user, send an empty rules object:

curl -X PUT 'https://HOST:PORT/cid/oauth2/ctid/inAppControls?token=04d95575-c9af-42fba72e-2f0ce93f01d4' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"brokerCrmName": "BESTBROKER", "userId": 10335, "rules": {}}'