Pass a Customer Prompt into cPanel Meridian

You can collect a customer’s website-building goals before sending them into the cPanel interface, then carry that prompt through to Nova in cPanel Meridian. Collect the prompt wherever it suits your signup process: on a signup form, in your online store, or through the Nova Prompt widget. The customer arrives at the builder with their prompt already in the input and never has to describe their site twice.

You can pass a prompt in two ways:

  • During account sign-in — Stage the prompt when you create the customer’s cPanel session. The prompt applies to whichever Nova card the customer opens first.
  • On the Nova for WordPress launch call — Send the prompt with the API call that creates the site. Use this method for integrations that never load the cPanel interface.

This guide covers Nova in cPanel Meridian. Customers reach Nova from their own cPanel account. Nova Experience works differently, because those customers log in to Nova directly. To pass a prompt into Nova Experience, read our Add Nova Experience to Your Customer Portal documentation. Neither method on this page changes how Nova Experience handles prompts.

Before you begin

The customer’s cPanel account must already be set up for Nova, on a package whose cPanel Theme is set to meridian. For the full setup procedure, read our Offer Nova in cPanel Meridian documentation.

Prompt token format

Both methods take the prompt in a promptToken parameter and apply the same rules:

  • The value must be base64-encoded. A value that is not valid base64 fails the call with an error that names the promptToken parameter, and no session or site is created.
  • The maximum decoded length is 5000 characters.

Review the following encoding example:

User prompt:

I want to create a restaurant website

Encoded prompt:

SSB3YW50IHRvIGNyZWF0ZSBhIHJlc3RhdXJhbnQgd2Vic2l0ZQ==

Pass a prompt during account sign-in

Include the promptToken parameter when you generate the customer’s one-time login URL with WHM API 1’s create_user_session function. The calling user must possess root-level access.

cPanel & WHM stores the prompt for that customer. Nova receives the prompt when the customer opens the Nova or Nova for WordPress card. The customer can open either card from the Website Builder section, or reach it through the new website onboarding flow. The builder opens with the prompt already in the input.

Include the following parameters in your request:

ParameterDescriptionExample
userThe customer’s cPanel account user.example1
serviceThe session’s service. Set this to the cPanel daemon.cpaneld
promptTokenThe base64-encoded prompt to pre-populate in the builder.SSB3YW50IHRvIGNyZWF0ZSBhIHJlc3RhdXJhbnQgd2Vic2l0ZQ==

For example, you can run the following command to create a session that carries a prompt:

whmapi1 create_user_session user=example1 service=cpaneld \
  promptToken=SSB3YW50IHRvIGNyZWF0ZSBhIHJlc3RhdXJhbnQgd2Vic2l0ZQ==

Then, redirect the customer to the url value that the function returns.

A prompt staged this way applies once. Nova consumes it the first time the customer opens a Nova card, and it does not reappear on a later visit. The stored prompt also expires, so stage it as part of the sign-in that sends the customer to Nova rather than ahead of time.

Pass a prompt on the Nova for WordPress launch call

If your integration creates sites entirely through the API and never loads the cPanel interface, include the promptToken parameter in your call to UAPI’s WPX::create_nova_for_wordpress_website function. The calling user must be the cPanel account user.

Include the following parameters in your request:

ParameterDescriptionExample
domainThe domain to build the WordPress site on.example.com
promptTokenThe base64-encoded prompt to pre-populate in the builder.QnVpbGQgbWUgYSBjb2ZmZWUgc2hvcCBzaXRlIHdpdGggb25saW5lIG9yZGVyaW5n

For example, you can run the following command to create a Nova for WordPress site from a prompt:

uapi --user=example1 WPX create_nova_for_wordpress_website \
  domain=example.com \
  promptToken=QnVpbGQgbWUgYSBjb2ZmZWUgc2hvcCBzaXRlIHdpdGggb25saW5lIG9yZGVyaW5n

The function returns a magic_link value. Redirect the customer to that URL to land them in Nova for WordPress with the prompt already in the input.

The promptToken parameter is optional. Existing calls that omit it behave exactly as before.

How the two methods interact

If you stage a prompt at sign-in and also pass one on the launch call, the prompt on the launch call takes precedence. That is the prompt Nova for WordPress opens with. The staged prompt stays available for the next Nova card the customer opens.

Prev
How WebPros Bills for Nova
Next
Use the Nova Experience on cPanel Module in WHMCS