Console Banner API

overview the console banner feature allows platform and product admins to create and manage banners that inform the app users about important notifications, scheduled maintenance, or downtimes directly within the console once configured, banners display in real time, ensuring that all relevant users are informed banner can be created for the different level types stack level for core platform wide activities (e g , system wide maintenance) tenant level for tenant specific updates (e g , customer specific reminders) solution level for specific solutions like dispatchone or tms (e g , scheduled downtime for a particular solution) info to learn more about the usage and implementation of these banners, refer to the json examples section at the bottom of this page accessing the banner api to access the banner feature, platform/product admins must have the appropriate permissions if you do not have admin access, reach out to us by visiting the developer portal at https //portal os1 delhivery com/ and click the contact us button to request access once you have admin access, follow the steps below to start using the banner api prerequisites user role ensure you have the product admin role to access the banner creation api api access all banner api requests require a valid access token to ensure only authorized users (product admins and support users) can create, update, or delete banners refer to the get access token section and get your access token api configuration the banner api allows product admins to create, update, and delete banners for their applications the below section outlines how to use the api, including the endpoints, request parameters, and sample example code snippets configuration parameters this table outlines the parameters used in the banner api requests, including headers, query parameters, and path parameters parameter data type description required x developerplatform access string access token for authentication yes leveltype string type of the level at which the banner is applicable (e g , stack) yes solutionid string id of the solution no bannerid string universal unique identifier for the banner (used for updating and deleting) yes activitydate string date of the banner display (in yyyy mm dd format) yes activefromtime string start time for banner display (iso 8601 format) yes activeuntiltime string end time for banner display (iso 8601 format) yes activitystarttime string the exact start time of the activity that the banner is notifying users about (in iso 8601 format) yes activityendtime string the exact end time of the activity that the banner is notifying users about (in iso 8601 format) yes title string the title of the banner yes message string the main message of the banner yes data object key value pairs for dynamic content in message yes creating a banner 1\ register a banner (post) register a new banner using the banner api make sure all required fields are valid and that you have the necessary support access with the provided access token to register a banner, send a post request using the endpoint below post /developer/support/banners when making requests to the banner api, include the following header and parameters request header all requests to the banner api must include the following header x developerplatform access this is the access token used for authentication request parameters parameter description required x developer platform access access token for authentication (mandatory) yes orgid unique identifier of the user’s organization yes sample request { "leveltype" "stack", "levelids" \[ "p1" ], "title" "scheduled maintenance alert!", "content" { "message" "we have planned for maintenance from {{activitystarttime}} to {{activityendtime}} on {{activitydate}} during this time this application will be temporarily unavailable", "data" { "activitystarttime" "2024 08 29t23 00 00 000z", "activityendtime" "2024 08 29t23 30 00 000z", "activitydate" "2024 08 29" } }, "activefromtime" "2024 08 29t00 00 00 000z", "activeuntiltime" "2024 08 29t23 30 00 000z" } note ensure the activitystarttime and activityendtime fall within the activefromtime and activeuntiltime additionally, banners cannot be created for any past date or time sample response { "data" { "id" "banner 54cbf964 ca94 4855 8542 33bfa7fbef76" }, "request" { "url" "string", "method" "string", "params" {}, "query" {}, "body" {} } } 2\ get all banners (get) retrieve a list of banners for a specific level using the get method this allows you to fetch active banners for a particular level on the current day to get the specific bannerid, send the get request using the following endpoint get /developer/support/banners request parameters parameter description x developer platform access access token for authentication (header) yes leveltype specifies the type of level for which banners are requested must be one of stack, tenant, or solution ye query parameter leveltype type of the level for which banners are requested sample response { "banners" \[ { "bannerid" "banner 54cbf964 ca94 4855 8542 33bfa7fbef76", "leveltype" "stack", "levelids" "\['p1']", "title" "scheduled maintenance alert!", "content" { "message" "string", "data" { "activitystarttime" "2024 08 29t23 00 00 000z", "activityendtime" "2024 08 29t23 30 00 000z", "activitydate" "2024 08 29" } }, "activefromtime" "2024 08 29t00 00 00 000z", "activeuntiltime" "2024 08 29t23 30 00 000z" } ] } in this example, leveltype is the query parameter being used to filter the results returned by the api 3\ get banner by id retrieve the details of a specific banner by providing its unique bannerid using the get method get /developer/support/banners/{bannerid} request parameters parameter description required x developer platform access access token for authentication (mandatory) yes bannerid unique identifier for a specific banner yes sample response { "bannerid" "string", "leveltype" "stack", "levelids" "\['p1']", "title" "scheduled maintenance alert!", "content" { "message" "string", "data" { "activitystarttime" "2024 08 29t23 00 00 000z", "activityendtime" "2024 08 29t23 30 00 000z", "activitydate" "2024 08 29" } }, "activefromtime" "2024 08 29t00 00 00 000z", "activeuntiltime" "2024 08 29t23 30 00 000z" } 4\ update a banner (patch) update an existing banner using the patch method this allows you to modify various properties of the banner such as title, content, active times, etc note banner’s leveltype and levelids field cannot be updated if these attributes need changes, you must delete the banner and create a new one to update a banner, send the patch request using the following endpoint patch /developer/support/banners/{bannerid} request parameters parameter description required x developer platform access access token for authentication (mandatory) yes bannerid unique identifier for a specific banner yes orgid unique identifier for the user’s organization yes sample request { "title" "scheduled maintenance alert!", "content" { "message" "we have planned for maintenance from {{activitystarttime}} to {{activityendtime}} on {{activitydate}} during this time this application will be temporarily unavailable", "data" { "activitystarttime" "2024 08 29t23 00 00 000z", "activityendtime" "2024 08 29t23 30 00 000z", "activitydate" "2024 08 29" } }, "activefromtime" "2024 08 29t00 00 00 000z", "activeuntiltime" "2024 08 29t23 30 00 000z" } sample response { "data" { "id" "banner 54cbf964 ca94 4855 8542 33bfa7fbef76" }, "request" { "url" "string", "method" "string", "params" {}, "query" {}, "body" {} } } 4\ delete a banner (delete) to delete a banner, send a delete request to the appropriate api endpoint with the bannerid of the banner you wish to remove delete /developer/support/banners/{bannerid} sample response { "data" { "id" "banner 54cbf964 ca94 4855 8542 33bfa7fbef76" }, "request" { "url" "string", "method" "string", "params" {}, "query" {}, "body" {} } } upon successful deletion, the api will delete the specific banner json examples stack level banner this banner notifies users of a planned maintenance event that affects the core services related to the overall system, applicable to all users in the stack { "leveltype" "stack", "levelids" \["p1"], "title" "scheduled maintenance alert!", "content" { "message" "we have planned maintenance from {{activitystarttime}} to {{activityendtime}} on {{activitydate}} during this time, core services under this stack will be unavailable ", "data" { "activitystarttime" "2024 08 29t23 00 00 000z", "activityendtime" "2024 08 29t23 30 00 000z", "activitydate" "2024 08 29" } }, "activefromtime" "2024 08 29t00 00 00 000z", "activeuntiltime" "2024 08 29t23 30 00 000z" } tenant level banner this banner serves as a payment reminder for a specific tenant to ensure only the relevant users are notified { "leveltype" "tenant", "levelids" \["tenant 123"], "title" "payment reminder", "content" { "message" "dear user, your payment is due on {{activitydate}} please make the payment to avoid service interruption ", "data" { "activitydate" "2024 10 01" } }, "activefromtime" "2024 09 20t00 00 00 000z", "activeuntiltime" "2024 10 01t23 59 59 000z" } solution level banner this banner is specifically meant for users of the dispatchone solution, providing them information about when the service will be unavailable due to maintenance { "leveltype" "solution", "levelids" \["solution 456"], // this id would correspond to dispatchone "title" "downtime notification for dispatchone", "content" { "message" "the downtime will be from {{activitystarttime}} to {{activityendtime}} on {{activitydate}} ", "data" { "activitystarttime" "2024 10 05t17 00 00 000z", "activityendtime" "2024 10 05t19 00 00 000z", "activitydate" "2024 10 05" } }, "activefromtime" "2024 10 01t00 00 00 000z", "activeuntiltime" "2024 10 05t19 00 00 000z" }