How do I add a call-to-action?

Your business video hosting account lets you show overlays during your videos.

In this guide, we will use an overlay to provide a ‘call-to-action’, prompting the viewer for an action.

The goal

You can see the result of following the steps below in this video. You should see two call-to-action overlays - one shown in the top-left corner, and the other in the bottom-left corner.

One appears after 1 second, and the other after 2 seconds. To demonstrate the different uses, one contains just text, and the other contains an image, text and a link.

Note: The overlays will not appear if viewed full-screen in the native iOS/Android video player, since it is not possible to overlay content on top of them.

1. Choose a suitable video

You will first need to select a video you would like your overlay to appear during.

Click on that video’s thumbnail image within the content library. The video details page has a preview of the video, its title, its description, and so on. The part we are interested in is the one labelled Overlays. Click on the ‘Overlays tab and then on the ‘Manage overlays’ button.

You should see the option to add a new one.

You will now be asked for the overlay’s details including its type, content, position and size.

We need to ask for quite a lot of information due to the flexibility: you can show an image, and/or text, and/or include a link. Further, you can choose where to position the overlay - and also how big it should be. However normally you will use a standard size and position for all your overlays, so once you have created your first one you will be able to re-use many of the settings for each subsequent one.

2. Provide the basic details

The first two boxes ask for a title and (optional) description. These are not shown within the overlay but are used to identify it, since if you need to edit it - and have multiple ones - calling it something like ‘Product Name’ will help if you ever need to edit it.

Vidbeo overlays form (1)

You need to specify what this overlay will be used for. Here, we want the user to be prompted, so it is a ‘call-to-action’:

Vidbeo overlays form (3)

Since we have chosen ‘call-to-action’, we need to provide the image, text and/or link to show within it. We have used some example values - you can try your own text, link, and if you have a small image available and want to show one (we recommend a postage-stamp size no more than 40 pixels tall), its URL:

Vidbeo overlays form (3)

The result of entering those values is the lower of the two overlays shown below (but don’t leave the form yet - there is still the size and position to set):

Vidbeo overlays form (8)

You are asked when the overlay should appear and disappear. In our video, we want to show our overlay panel at 1 second and hide the overlay at 9 seconds. So we need to enter 00:01 in the first box, and 00:09 in the second box:

Vidbeo overlays form (2)

So now you need to tell the system how big your overlay should be - it can’t know, since it doesn’t know what content you will be showing within it - and also where it should be positioned.

In our example above, we want our overlay shown in the bottom-left corner. This is to demonstrate one of the tricks you can do with the positioning: you can use a negative value. That is because normally the size is relative to the left/top - but what if your player is resized? If we simply set a distance from the top-left corner, that might change. So we can set a distance from the bottom of the player by using a negative value. In this case we have set the overlay to be shown 60 pixels from the bottom of the player by using “-60px”:

Vidbeo overlays form (5)

The final two boxes contain the size of the overlay. Just like for the X and Y position, these can contain a “px” or “%” value. You might have to do some experimenting with the size you want, however for our example overlays in the image, we used 350px and 68px for the width and height.

You can always change the size if your overlay appears too big or too small:

Vidbeo overlays form (7)

Then the very last option is whether the video should pause when this overlay appears. Normally you wouldn’t want this - so we’ll choose no.

Finally, we are done. So click ‘Proceed’ and you should be returned to the page with a preview of the video player on. Hopefully in the bottom-right corner you should see your new overlay listed.

If you now play your video, you should see your overlay appear at your chosen time (for example at 00:01) like in our example video above.

If its content/position/size is not quite right, you can simply edit it: click on the little blue pencil button to the left of your overlay’s details on that page. That will re-open the form.

Note: any changes you make can take a few minutes to propagate and so you may not immediately see them take effect. Please wait a few moments, refresh the page and check again.

If you have created a call-to-action and that includes a link, two things can happen when the viewer clicks on it:

(a) They can be taken to a new URL

(b) A function can be called.

If you simply want the viewer to be taken to a new page URL - for example to find out more about the product featured - then you can do this without using our Player API. Your overlay should already be working right now without doing anything further.

You can skip the rest of this guide.

However if you want to trigger an action, like ‘add to basket’, that is a bit more complicated, as it will involve some JavaScript. You will need some knowledge of web development to be able to do this.

So, assuming you do want to run some JavaScript when the link is clicked, with your player details page still open if you scroll up the page you will find a dropdown menu asking whether to enable the Player API. The Player API needs to be enabled in order for a page to interact with an embedded player (such as handling clicks on overlays) so please choose ‘Yes’.

Next, just to the right of that is another box. This asks for the domains you will use the Player API from. For security, the player needs to know which domains to listen for messages from (requests to the Player API are made by sending messages to the player). If you have multiple sites, enter them separated by a comma. For example:

Player API domains

Once done, click ‘Save changes’ in the top-right. The page will refresh.

The Player API is now active - however requests can only be made using it if you include our library on the same page your video is embedded on. Requests are passed as messages. This is because all web browsers prevent cross-domain communication and since our player is served from a different domain to your page, the two would not normally be allowed to communicate. This communication is made possible by a function called postMessage that was introduced in HTML5. We have built a small library that means you do not have to worry about exactly how these messages are constructed - you simply call a function whose name we provide and the actual message-handling is done behind-the-scenes.

You can find that library on GitHub.

Please now save a copy of that .js file and make sure it is available to your web page. That way you will be able to call the functions listed in our Player API and not have to worry about how the messages are constructed and processed to make the requests happen.

You will usually do this by adding a script tag to your page that includes the file. For example:

<script src="/path/to/vp_js.v1.1.0.js"></script>

The final step is to implement the function that you would like to be called when the viewer clicks on the link in the overlay.

In our example, we entered a URL in the action box (our pretend #buy-flowers page). However if we wanted to call a function, we would have instead put that function’s name - such as addToBasket - in that box.

In which case, in your page you will then need to implement a function with that name that handles the player’s response:

function addToBasket(response) {
    // quick validation ...
    if (typeof response != "object" || response.type != "overlayLinkClicked") {
        return false;

    // pause the video using the Player API ...
    vpJS.request("vp_iframe_VIDEOID", "pause", "VIDEOID");

    // show a message (here you would implement your own action) ...
    alert("Item added to basket");

The first line is just doing some quick validation to check the response is indeed an object, and the type property is overlayLinkClicked. The next line is optional - it pauses the video when the item is clicked. You can see it uses our library (vpJS). You can see why the request is called that by reading through our Player API documentation. Finally, we have simply popped up a message using ‘alert’ that says the item has been added to the basket.

If you have any questions, please email us at and we’ll do our best to help you get the most from this powerful and flexible feature.

Go back to the questions about videos