¶ Embedded UCP
In this document you can find the step-by-step explanation of how you can load a embedded version of UCP from your website.
¶ The powerful iframe HTML tag!
The most easily way to load UCP from your site is by using an iframe HTML tag. Lets go to the explanation of how to use this powerful HTML tag in your site to load the application.
Lets use the following vocabulary to talk about your website and UCP
- webParent: The URL of the website that you want to load UCP from
- webUCP: The URL of UCP website (Ex: https://qvoice.ca/ucp/login)
The URL of UCP FULLSCREEN website (Ex: https://qvoice.ca/ucp/login?fullscreen=true)
¶ Insert the iframe HTML tag in your website (webParent)
In the HTML document of your website (webParent) or inside your component if you are working with React you should insert the following:
<iframe title='ucp' src='{webUCP}' allow='notifications; microphone' />
Lets talk about the attributes of the iframe
- title: This is the title of your iframe, we suggest to use ucp to easily recognize it
- src: This is the source of the content of the iframe, in other terms it is the URL of the website that you want to load, in this case we are talking about webUCP (URL of UCP website)
Important: Always use the URL of UCP with the /login path at the end, otherwise the content of UCP will not be loaded successfully
Incorrect usage: https://qvoice.ca/ucp
Correct usage: https://qvoice.ca/ucp/login
- allow: This is a list of permissions splited by ; that you grant to the embedded website. UCP uses two of them, notifications in order to have the ability to push notifications and microphone in order to access the audio input that will be used during your calls
Important: If you do not want to grant these two permissions to UCP you should take into account that incoming and outgoing calls are not going to work
Finally you should see UCP embedded inside your website, for sure you can customise the styles of the iframe.
Important: We strongly suggest to use a minimum size of 300 pixels x 300 pixels in order to give the UI enough space to normally display the elements
Enjoy Embedded UCP in your website!
¶ Receiving messages in parent window from Embedded UCP
Embedded UCP sends call events to the parent window so you can subscribe to these events by opening a listener in the parent window.
Below you can find the examples of the events:
{
"type": "UCP_INCOMING_CALL",
"payload": {
'call_id': "8a9e7f1e-af22-4257-84d2-043e56dc0d1e",
"caller_id_name": "John Doe",
"caller_id_number": "1234567890",
"queue_id": "1234567890",
"queue_name": "Test Queue",
"campaign_name": "Test Campaign",
"lead_id": "1234567890",
"user_id": "1234567890",
"user_ext": "1000"
}
},
{
"type": "UCP_ANSWERED_CALL",
"payload": {
'call_id': "8a9e7f1e-af22-4257-84d2-043e56dc0d1e",
"caller_id_name": "John Doe",
"caller_id_number": "1234567890",
"queue_id": "1234567890",
"queue_name": "Test Queue",
"campaign_name": "Test Campaign",
"lead_id": "1234567890",
"user_id": "1234567890",
"user_ext": "1000"
}
},
{
"type": "UCP_HANGUP_CALL",
"payload": {
'call_id': "8a9e7f1e-af22-4257-84d2-043e56dc0d1e",
"user_id": "1234567890",
"user_ext": "1000"
}
},
{
"type": "UCP_OUTGOING_CALL",
"payload": {
'call_id': "8a9e7f1e-af22-4257-84d2-043e56dc0d1e",
'callee_id_number': "1237",
"user_id": "1234567890",
"user_ext": "1000"
}
}
- Receiving messages in parent window
window.addEventListener('message', function(event) {
if (event.data.type === "UCP_INCOMING_CALL") {
console.log('INCOMING CALL FROM UCP: ', event.data)
} else if (event.data.type === "UCP_ANSWERED_CALL") {
console.log('ANSWERED CALL FROM UCP: ', event.data)
} else if (event.data.type === "UCP_HANGUP_CALL") {
console.log('HUNGUP CALL FROM UCP: ', event.data)
} else if (event.data.type === "UCP_OUTGOING_CALL") {
console.log('OUTGOING CALL FROM UCP: ', event.data)
}
}, false)
¶ Sending messages from Parent window to Embedded UCP
The parent window can also send messages to the embedded UCP to trigger specific actions. This allows you to control UCP functionality directly from your website.
¶ Making calls from Parent window
You can initiate calls from the parent window by sending a message to the embedded UCP iframe. Here's how to do it:
document.getElementById('ucp-iframe').contentWindow.postMessage({
type: 'MAKE_CALL',
payload: {
destination: '1234'
}
}, '*')
Important considerations:
-
iframe ID: Make sure your iframe has an
idattribute so you can reference it. For example:<iframe id="ucp-iframe" title='ucp' src='{webUCP}' allow='notifications; microphone' /> -
Message structure: The message must follow the specific format with
typeandpayloadproperties. -
Destination: The
destinationfield should contain the phone number you want to call. -
Origin parameter: The
'*'parameter allows the message to be sent to any origin. For security reasons, you might want to specify the exact UCP domain instead.
¶ Available message types
Currently, the following message types are supported:
- MAKE_CALL: Initiates an outgoing call to the specified destination
Note: More message types will be added in future versions to support additional UCP functionality.
¶ Example implementation
Here's a complete example showing how to add a button that makes a call from the parent window:
<iframe id="ucp-iframe" title='ucp' src='https://qvoice.ca/ucp/login' allow='notifications; microphone' />
<button onclick="makeCall('1234567890')">Call 123-456-7890</button>
<script>
function makeCall(destination) {
const iframe = document.getElementById('ucp-iframe');
iframe.contentWindow.postMessage({
type: 'MAKE_CALL',
payload: {
destination: destination
}
}, '*');
}
</script>
Now you can control UCP functionality directly from your parent website!