Configure the CRM gateway
You need a callmetra. organization administrator, an available CRM slot and Vtiger Cloud administrator permissions. This integration uses the Generic Phone Calls API for call events and popups.
Create a Generic gateway in Vtiger Cloud
- Open the top-right user menu and choose Settings.
- Select Extensions → Phone Configuration → Add Gateway.
- Set Gateway: Generic, Gateway Status: Active, and enter a label such as callmetra.
- Change Default Gateway only deliberately. This setup does not require replacing an existing production default.
- Leave Enable Outgoing Calls disabled for this setup. The adapter logs outbound events but does not dial numbers through CRM click-to-call.
- Save and securely copy the Vtiger Secret Key. This is the gateway secret to enter in callmetra.
Depending on the interface, the alternative route is Phone Calls → Settings/Customize → Phone Configuration/Provider Configuration. If the module is missing, check your edition, installation and permissions. Official phone setup.
In callmetra., open Integrations → Add integration → Vtiger Cloud. Enter the tenant domain, such as company.od2.vtiger.com, without a path, and the gateway secret. Save. Direct Cloud subdomains and regional odN/odx hosts are supported.
Map employees
In Vtiger, open Settings → User Management → Users and edit each intended CRM user. Set their Office Phone; the field may also be available under that user’s My Preferences.
In callmetra., choose Employee mapping or Manage mappings. Match each phone extension to that exact Office Phone value. The extension and Office Phone do not have to be identical. A contact’s phone field is not a substitute for the user field. Search and pagination keep large teams manageable.
Vtiger uses the destination value to identify the user. Without a matching user Office Phone, technical delivery can succeed while the expected popup is absent. Office Phone and call events.
Verify with an authorized test
- Sign in to Vtiger as the intended user; check Phone Popup Configuration and phone permissions.
- Select Test Vtiger on the callmetra. connection, then choose an employee mapping.
- Outside the demo, Start test requires confirmation: it creates a real CRM test record and can trigger configured workflows. No phone is dialled.
- Check delivery status and the CRM popup. End test queues the closing event immediately; an end is also scheduled after 60 seconds. Retries can delay it. The CRM test record remains.
- Confirm the popup on the connection card only after observing it yourself.
The dialog tracks start and end separately. HTTP success is not automatic popup verification. The demo simulates delivery. Follow up with a real incoming, answered and ended call, plus outbound calls and transfers where needed.
Generic Phone Calls API versus REST API
The phone adapter sends form POSTs to /modules/PhoneCalls/callbacks/Generic.php using X-VTIGER-SECRET. Initiated, connected, hangup and mapped transfers share a correlated call ID.
The general Vtiger REST API instead uses a login username and personal Access Key. Those credentials are not a gateway secret and are not needed by this adapter.
If the popup is missing
Check the gateway status and secret, exact Office Phone mapping, signed-in Vtiger user and popup permissions. Delivery activity shows retries and failures. An HTML login page is not accepted as successful API delivery. Continue with Troubleshooting; do not include secrets or unredacted customer data in support requests.