This guide explains how to embed the CloudTalk Phone interface into your own web application using an iframe.
User level:
Admin
Install the iFrame
Initialization
To embed and initialize CloudTalk Phone:
Use an
iframewith the following source format:
https://phone.cloudtalk.io?partner=yourappnameReplace
yourappnamewith your system’s identifier in thepartnerquery parameter.
Example:
<iframe src="https://phone.cloudtalk.io?partner=mycrm" allow="microphone *" height="700px" width="420px"></iframe>
Requirements
Minimum dimensions: 700px height × 420px width
The CloudTalk Phone must be embedded in a Single Page Application (SPA). It should not be reloaded when navigating between views within your app.
Notifications are not supported in the embedded version. In some cases, users may see a warning like "Notifications are not enabled" - this is a known visual issue and does not impact functionality.
Listening to Events
You can register for CloudTalk Phone events using window.onmessage. This allows your system to respond to events such as incoming calls or call hangups (e.g., by showing a contact detail panel or bringing the phone into focus).
Supported Events
ringing– triggered when there’s an incoming callhangup– triggered when a call ends
You might want to maximize a minimized phone window when there's an incoming call, or automatically open the caller's contact detail page in your system.
Example:
window.onmessage = function(e) {
const eventData = JSON.parse(e.data);
console.log(eventData);
};
Sample Payload
{
"event": "ringing",
"properties": {
"call_uuid": "12345678-1234-1234-123a-012345a6789b",
"external_number": "+44 20 3868 0167",
"internal_number": "+1 888 487 1675",
"contact": {
"id": 1234,
"name": "John Doe",
"company": "Company Inc.",
"contact_emails": [
"[email protected]",
"[email protected]"
],
"contact_numbers": [
"+44 20 3868 0167",
"+44123123123"
],
"external_urls": [
{
"external_system": "mycrm",
"external_url": "https://mycrm.io/contact/123"
}
],
"tags": ["VIP", "Europe"]
}
}
}
If you need further assistance or have any questions, you can contact our Support team. We are always here to help you!